Create a Workspace
Choose or create the git repository that holds the knowledge of a Workspace.
Add Workspace has two steps. Step 1 chooses the Workspace repository. When you choose it, the Workspace exists and ctxpipe starts to read it. Step 2 adds the code repositories and tools that the Workspace reads. Step 2 is optional.
Before you start
- Connect GitHub on Connectors if you want to select or create a repository on GitHub. ctxpipe can write only to the repositories that the ctxpipe GitHub App can access.
- Choose the repository for the knowledge of this Workspace. An empty repository is good. An existing documentation repository is good too.
Create the Workspace
Open Add Workspace
Choose + next to Workspaces in the sidebar. You can also choose Create Workspace on Home, or on the GitHub setup page after you connect GitHub.
Choose the repository
Choose one of these options:
- Select GitHub: search the repositories that the ctxpipe GitHub App can see.
- Create on GitHub: open the new-repository page of GitHub. Create the repository, make sure that the App can access it, then come back and select it.
- Paste URL: use any git URL. ctxpipe cannot write to a repository that is not on GitHub, so that Workspace is read-only.
To keep the Workspace in one folder of a larger repository, type the folder
in Root folder, for example docs/context. See
Root folder.
Choose Create Workspace.
Add code repositories and tools
ctxpipe checks that it can write to the repository and sets it up. Then it shows the Sources of the new Workspace:
- Choose Add repositories under GitHub to link code repositories.
- Choose Add next to a connected tool, such as Linear or Notion.
- Choose Add another connection (or Add connection) to connect a new tool. This closes Add Workspace.
Each change opens a pull request that adds a source file under sources/.
The change applies after you merge it. You can make the same changes later
in Settings. Choose Open Workspace (or Done) to finish.
If the repository has ctxpipe content from an earlier version, the step shows Upgrade this Workspace before you add sources. See Upgrades. If ctxpipe cannot write, the step shows the reason. See Write access.
Wait for the first index
ctxpipe reads the default branch and builds the index. You can start a conversation at once. The answers improve when indexing is done.
A repository can be the Workspace repository of only one Workspace in an organization. Other Workspaces can link it as a linked repository.
What ctxpipe adds to the repository
On a writable repository, ctxpipe makes one setup commit that adds these files if they are missing:
AGENTS.md, with the Workspacenamein its front matter and a short folder map;.agents/skills/ctxpipe-knowledge/SKILL.md, which tells coding agents how to write knowledge files for this Workspace;.ctxpipe/workspace.yaml, which holds the repository format, on a repository that has no ctxpipe content yet.
ctxpipe keeps the files that exist. It adds only what is missing.
Root folder
The root folder is the folder of the repository that holds the Workspace. The default is the root of the repository.
- ctxpipe reads and writes only below the root folder. This applies to the
knowledge files,
AGENTS.md,sources/,.ctxpipe/workspace.yaml, connector mirrors, ingestion, and conversation commits. - The paths in Files, in conversations, and in the MCP tools are relative to the root folder.
- ctxpipe refuses a conversation push that changes a file outside the root folder.
- The root folder is a relative path, such as
docs/context. It cannot start with/or contain..or.git. It can contain only letters, numbers,.,_,-, and/.
When you change the root folder in Settings, ctxpipe reads the Workspace again from the new folder. The current index serves until the new one is ready. Files in the old folder stay where they are.