Shared context

Shared context workspaces are experimental. Enable Settings > Experimental > Shared context workspaces before using this flow.

A shared context workspace groups related child repositories or worktrees under one parent. Each child worktree keeps its own repository path and git state.

When to use shared context

Use shared context for related repositories or worktrees, such as:

• A frontend worktree, backend API worktree, and database migration worktree for one feature.
• A mobile app worktree, server worktree, and shared SDK worktree that need one review pass.
• A docs worktree and app worktree for a feature that changes both product behavior and documentation.
• A parent task that dispatches smaller child tasks across related repositories.
• A feature with separate implementation, fixture, and end-to-end test worktrees.

Keep unrelated tasks in separate regular workspaces.

Parent and child model

In shared context mode:

• The parent groups the children.
• Each child worktree keeps its own repo path, branch, and diff.
• File search and review aggregate across child repos.
• The parent surfaces run state for each child run command.
• Notifications and navigation route back to the child that needs attention.

The parent view groups the children without removing isolation between them.

Shared diffs

The parent view shows diffs grouped by child repo. Each repo keeps its own branch and file list, and the parent summarizes total additions and deletions.

To review a shared context workspace:

1. Start with the repo-level summary.
2. Expand one child repo at a time.
3. Review each child branch as its own unit.
4. Confirm that cross-repo changes line up.

Shared run behavior

The parent coordinates run commands across child projects that define a run script. Configure a project-specific run command as:

{
  "run": ["bun run dev"]
}

If the parent run button does not start the expected command, check each child project’s settings and confirm it defines a run script.

Cross-cutting context to track

A shared context workspace gives no built-in notes surface, so record what cuts across the children somewhere durable, such as:

• Acceptance criteria.
• The cross-repo API contract.
• The review order.
• The branch or release target.

Cleanup

Before deleting a shared parent, confirm what will happen to its children. Child worktrees may still hold useful changes, open PRs, or session history.