# Create a Workspace (https://docs.ctxpipe.ai/docs/workspaces/create-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

<Steps>
  <Step>
    ### 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.
  </Step>

  <Step>
    ### 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](#root-folder).

    Choose **Create Workspace**.
  </Step>

  <Step>
    ### 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](/docs/workspaces/linked-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](/docs/workspaces/settings#upgrades). If ctxpipe cannot write,
    the step shows the reason. See
    [Write access](/docs/workspaces/settings#write-access).
  </Step>

  <Step>
    ### 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.
  </Step>
</Steps>

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 Workspace `name` in 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](/docs/workspaces/settings#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.

<Cards>
  <Card title="Knowledge files" href="/docs/workspaces/knowledge-files" description="How to write files that ctxpipe can use." />

  <Card title="Connections" href="/docs/connections" description="Mirror Linear, Notion, Confluence, Slack, PagerDuty, and Plain into the Workspace." />
</Cards>