Shared context

Experimental

Shared context workspaces are experimental. Open Settings → Experimental and enable Shared context workspaces before creating one. Enabling the setting makes the workspace type available; it does not create or modify a workspace.

A shared context workspace groups related repositories under one feature context. New shared context workspaces use lazy branch groups: the app creates the group and its shared instructions first, then materializes a repository worktree only when the task needs that repository.

Existing shared context workspaces created by older versions remain available with their original eager child-worktree structure.

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 feature whose implementation, fixtures, and end-to-end tests live in different repositories.

Keep unrelated tasks in separate regular workspaces.

Create a shared context workspace

Enable the experiment, create a workspace, and choose the repositories that may participate. Then choose an AI setup depth:

• Analyze repositories (recommended) uses the selected provider and model to write repository-role guidance.
• Template only writes basic AGENTS.md and CLAUDE.md files without analyzing the repositories.

The thorough option lets you choose the provider and model that prepares the context. The setup step writes guidance; it does not begin implementation in every repository.

Branch groups and child worktrees

In shared context mode:

• A branch group represents one cross-repository feature or task.
• The group root carries shared context and is not itself a Git repository.
• Each materialized child is a normal Git worktree with its own repository path, branch, target, diff, and Git actions.
• A multi-repository group starts without child worktrees. A single-repository group materializes its only child immediately.
• The app creates additional children only when the task needs them.

Child branches normally use the branch-group name. If that branch is already checked out in one repository, the app may choose a close suffix for that child rather than blocking the whole group.

To materialize a child from a group terminal or agent session, run:

Copy

sc worktree ensure-child <repository-name>

Run the command from the branch-group context. It uses the app’s managed worktree flow and returns the child path. You can also use the app’s creation controls when you want to choose participating repositories and the branch name manually.

Feature context

The group root contains the cross-cutting artifacts that orient agents and humans:

• FEATURE.md records the objective, scope, constraints, affected repositories, and cross-repository contracts.
• AGENTS.md and CLAUDE.md point sessions toward that feature context and repository map.
• The context/ folder can hold supporting notes or artifacts that do not belong to one child repository.

Update FEATURE.md as discovery changes the scope. Materialize only the repositories classified as required; leave possibly related repositories uncreated until the work actually needs them.

Shared diffs

The group view shows diffs grouped by child repository. Each repository keeps its own branch and file list, and the group summarizes the participating changes.

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.

File search at the group level aggregates files from materialized children and labels results by repository. Select a child when you want its normal repository-specific commands and Git context.

Run behavior

The group surfaces run targets from participating projects. Each command still runs in the child worktree that owns it. Configure project-specific named run targets as described in Project config and scripts, for example:

Copy

{
  "run": [
    { "name": "Web", "commands": ["bun run dev"], "default": true }
  ]
}

If a run target is missing, confirm that its repository has been materialized and that the project defines the command.

Cleanup

Review and clean up each materialized child as its own Git worktree. A child may still contain changes, unpushed commits, an open PR/MR, or useful session history even when the cross-repository task looks complete.

Before deleting the branch group, confirm that every participating repository is safe to remove. See Worktree cleanup for the checks the app applies.