Skip to content

docs: a short guide to setting up workstreams #466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
saucam merged 1 commit into from
Nov 13, 2026
Merged

docs: a short guide to setting up workstreams #466

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -422,6 +422,7 @@ Full detail — keybindings, slash commands, ranking weights, rotation threshold
- **[Parallel sessions + git worktrees](docs/FEATURES.md#parallel-sessions--git-worktrees)** — run features side by side; branches share one workspace memory, anchored on `git-common-dir`.
- **[Execution modes](docs/FEATURES.md#execution-modes)** — `guarded` / `interactive` / `autonomous`, the last with a write-action budget that reverts to guarded when spent.
- **[Mid-turn streaming input](docs/FEATURES.md#mid-turn-streaming-input-vscode-parity)** — send a follow-up while Claude is still responding; `now` / `next` / `later` priority.
- **[Workstreams](docs/CONFIGURATION.md#setting-up-workstreams)** — group your work (a client, a team, a personal setup) so each session gets only its own MCP servers, credentials, folders and memory.
- **[Attachments](docs/FEATURES.md#attachments)** — `@file` mentions, one-shot `/context`, and persistent `/pin`; drag-drop in the web UI.

**Automation**
Expand Down
12 changes: 12 additions & 0 deletions docs/CONFIGURATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -369,6 +369,18 @@ A workstream is a named line of work: a company, a client, a project, a team, a
Each session belongs to exactly one, its home, and the home decides what the session is given.
The design is [workstreams-design.md](workstreams-design.md).

### Setting up workstreams

Nothing is enforced until the last step, so you can try each one safely.

1. See a proposal: `codeoid workstream import` (it looks in `~/Workspace`; `--root <dir>` for another folder) groups your repositories by their git remote's owner and lists the MCP servers in Claude's global config, as a config block to review. It writes nothing.
2. Add the workstreams you want, in Settings → Workstreams in the web UI or in the `workstreams` block of `config.json` (below). Give each one an id and match rules, and a `share` policy if other workstreams shouldn't read it.
3. Check a few folders with `codeoid workstream match <dir>`. It shows the workstream a folder gets and the rule that chose it. A path rule wins over a remote rule, so add one for a repository whose remote matches the wrong workstream.
4. Declare the credentials your workstreams use and set their values, in Settings → Credentials or as described under [Credentials](#credentials). Then give each workstream its servers, env and git identity.
5. Turn on isolation: the toggle in Settings → Workstreams, or `"isolateGlobalServers": true`. From then on a session gets only its workstream's servers and credentials, and can't read other workstreams' folders or memory.

To go back, turn isolation off. Your workstreams stay configured, and sessions get every server again.

```jsonc
"workstreams": {
"default": "personal", // home for a folder nothing matches; leave out to have none
Expand Down
Loading