Git worktrees

Two agents editing the same checkout will trip over each other. A git worktree gives each one its own folder and branch, while sharing the repository's history.

Starting an agent in a worktree

1. Open a project that is a git repository.
2. Click New session (or Start a session in an empty pane) and turn on Isolate in a git worktree.
3. Keep the suggested branch name (like codeherd/session-4f2a) or type your own, and choose the branch to start from.
4. Pick the agent. It starts in the new worktree; the pane header shows the branch.

Worktrees live in ~/.codeherd/worktrees/, outside your repository, so they never clutter it or your .gitignore.

Using a worktree you already have

An agent can also run in a worktree that already exists: one you made yourself with git worktree add, wherever it lives, or one an earlier session left behind.

• In Start a session, turn on Isolate in a git worktree, choose Existing worktree and pick it from the list.
• Or click Worktrees in the project header and press Start a session here next to it.

It starts as it is: nothing is copied and the setup command doesn't run. Several sessions can share one worktree, though they'll be editing the same files.

Setting up new worktrees

A fresh checkout has none of your git-ignored files and no installed dependencies, so it usually can't build yet. Choose Worktree Setup… from a project's menu in the sidebar (or Edit next to the setup summary when starting a session) to tell CodeHerd how to prepare each new worktree:

• Copy files from the main checkout: globs, relative to the repository root, of untracked or ignored files to copy over. The default copies every .env and .env.* file, nested ones included. Nothing inside node_modules is copied, and existing files are never overwritten.
• Then run: a command like pnpm install. It runs through your login shell in the new session's terminal, where you can watch it, before the agent starts. If it fails, CodeHerd waits for you to press Enter so you can read why.
• Check worktrees together with: a build or type check, run by Check together (below).

Setup runs once per worktree, when its session first starts; restarting or resuming the session doesn't run it again. The settings are stored in CodeHerd, not in your repository, so a cloned repo can never make CodeHerd run a command you didn't write.

When worktrees overlap

Separate folders keep agents from overwriting each other, but two branches that change the same file still have to be merged. CodeHerd compares the active project's worktrees every few seconds, counting both commits and uncommitted edits:

• A yellow warning next to a session in the sidebar means another session's worktree changed some of the same files. Hover it to see which.
• It turns red once both branches have commits that git can't merge cleanly, before either is merged.
• The Changes pane names the other session and marks the shared files. It also says whether the two changed the same lines (or neighbouring ones, which git treats the same way). If they did, it lists each place with the session that changed it last. Click one to see both versions of those lines side by side.

That's your cue to let one agent finish first, or tell the other to stay out of those lines.

Checking worktrees together

Overlap warnings only see text. Two agents can change different files that git merges without a word and still break each other: one renames a function, the other adds a call to the old name. To catch that, build them together:

1. Click Worktrees in the project header, then Check together….
2. Pick the worktrees (those with agents working in them are picked already) and enter a check command, like pnpm typecheck or cargo check. It's saved with the project's worktree setup.
3. Press Run check. CodeHerd puts their work, committed or not, on top of the main checkout's branch, runs your setup command and then the check, and shows the output as it goes.

The worktrees themselves are never touched: the combination is checked out in a hidden worktree of its own, which keeps its installed dependencies between checks, so the next one is quicker. If two of them conflict, CodeHerd says where instead of running anything. Closing the dialog stops a check that is still running.

Reviewing and merging

A worktree is a normal git branch. Review it, commit, push or merge it with your usual tools: git diff main...codeherd/session-4f2a, a pull request, or your editor.

Cleaning up

• Closing a pane offers to remove its worktree too, already turned on when CodeHerd made the worktree and it has no uncommitted changes. A worktree you made yourself is kept unless you turn it on, and one another session still uses is never offered.
• The Worktrees button in the project header lists every worktree, with uncommitted changes and attached sessions, and lets you reveal, remove or prune them.