---
url: https://bishop.agentdeployment.co/running/worktrees.md
description: >-
  Giving each thread its own git worktree so threads don't write over each
  other's files.
---

# 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:

```json
{
  "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:

```json
{
  "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](/running/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](/deploying/cleanup) 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:

```sh
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.