Worktree Mode

Threads share one working directory by default, so two people directing an agent in two threads can have it write the same files. Worktree mode gives each thread its own git worktree:

{
  "agent": {
    "worktrees": true
  }
}

Each thread works in a worktree named bishop-<team>-<channel>-<thread>, and stays in it for every later message. It lives in .claude/worktrees/ at the root of the repository the agent is in. That's the agent directory itself, unless --agent is a git URL, where it's .bishop/agents/<slug>/mirror.git/.claude/worktrees/. git worktree list always says.

How it gets there depends on the harness:

• Claude creates the worktree the first time the agent decides to edit a file, so a thread that only asks questions never gets one. Bishop names it, tells the agent to enter it, and refuses edits in the shared checkout until it has. The branch is the worktree name prefixed with worktree-.
• Codex has no equivalent tool, so Bishop creates the worktree itself and starts the session inside it. Every thread gets one whether or not it edits anything, and the branch is the worktree name exactly.

Either way the agent commits on that branch and says which one it is.

Missing files in a worktree

A new worktree holds only tracked files, so node_modules and anything else your repository ignores is missing. Under Claude, symlink what the build needs:

{
  "agent": {
    "worktrees": true,
    "options": {
      "settings": {
        "worktree": {
          "symlinkDirectories": ["node_modules"],
          "baseRef": "head"
        }
      }
    }
  }
}

Bishop sets baseRef to head so a worktree branches from wherever the agent directory is now. Set it to fresh to branch from origin/<default-branch> instead. Everything else the harness offers here, including sparsePaths for a large monorepo, works the same way. Under Codex, Bishop always branches from HEAD and there's nothing to configure.

What it guarantees

Under Claude, Bishop refuses Edit, Write, and NotebookEdit in the shared directory until the agent has entered its worktree, and tells the agent why. Bash isn't checked, since a command's target can't be read off its text. So this keeps threads out of each other's way, but it isn't a sandbox: an agent determined to write outside its worktree can. Under Codex the session starts in the worktree, and sandboxMode limits where it can write, or nono when the sandbox is on.

When the agent directory isn't a git repository, there's nothing to isolate. Bishop warns at startup and says so once in each thread, then edits the directory directly.

Removing a worktree

A worktree outlives the thread that made it, and Bishop collects it along with its branch once the thread has been quiet long enough. To remove one sooner under Claude, unlock it first, since the harness locks each one while its session holds it and the lock outlives the process:

git worktree list
git worktree unlock .claude/worktrees/bishop-T1-C1-1712345678-123456
git worktree remove .claude/worktrees/bishop-T1-C1-1712345678-123456

Add --force to remove to discard uncommitted changes in it. Check git -C <worktree> status first: that's where a thread's unfinished work is.