Git worktrees for agent sessions — and why we shipped the cleanup in the same release

A background sub-agent forked off a parent session, inherited the parent's exact working directory, and kept working while the parent's own edits changed the tree underneath it — mid-investigation, live, in our own dev process. Someone had to interrupt the sub-agent to tell it the ground had moved. That's the failure mode git worktrees exist to fix.

Workain sessions can now run in their own git worktree instead of sharing a folder's checkout — one session, one branch, one directory nobody else is touching mid-task. It's on by default for any git-linked folder, with a checkbox and branch picker right in session creation, branch badges on folders and sessions, and a view of orphaned worktrees in workspace settings — overridable per session, folder, or project if you'd rather turn it off. Automatic registration and cleanup shipped in the same release as the isolation itself.

A normal git checkout ties one directory to one branch at a time — switch branches and the files on disk change under you. git worktree add gives you a second directory, backed by the same repository, checked out to a different branch, at the same time. Same commit history, same remotes, no cloning — an extra working directory pointed at whatever branch you want, deleted when you're done without touching the repository itself.

Why this matters more for an agent than for a person

A person running two branches at once usually just doesn't — you stash, switch, come back. An agent doesn't have that reflex. If two sessions are pointed at the same folder, they're editing the same files on disk at the same time, whether or not either one knows the other exists.

Claude Code, Cursor, and Vibe Kanban have each independently shipped the same fix: give each task or agent its own worktree, as a real built-in capability rather than a manual workaround. (Cursor and Vibe Kanban do this by default; Claude Code exposes it as an explicit per-subagent setting.)

What it costs

Isolation isn't free. More worktrees means more disk, and more moving parts to lose track of. We've watched a shared /tmp on a dev box fill to 100% from nothing more exotic than dozens of leftover worktrees nobody had cleaned up — git, gh, and the test runner stopped working for everyone on that box until someone went and manually cleared it out. That happens anywhere worktrees get created faster than anyone remembers to remove them, on any team's machine, not just ours.

The real risk: forgetting what you isolated

Watching a different part of this org run its own worktree-per-session setup made the risk concrete. Every session got its own worktree — sound in principle — but the only record of which worktrees were actually still live was a manually-updated notes file, and under real load it was kept current in roughly one case out of fifteen.

Two crashes on that same box show the two halves of the risk separately. An earlier one: every worktree got checked by hand afterward, and nothing was lost, because each session's real output already lived on disk independent of whatever process was running it. A later one killed every session at once, and this time only a small hardcoded list came back automatically — everything else was left for someone to sort out worktree by worktree, with no system telling anyone what still needed attention, and no record of what that manual sweep did or didn't catch. The worktrees themselves were never the exposed part; not knowing which ones still mattered was.

That's why the registration and cleanup mechanism — the system tracking which worktrees are actually still in use and reclaiming the rest on its own — went into the same release as the isolation here, rather than a phase 2 to get to eventually. A worktree that outlives its session gets found and removed by the system itself; nothing depends on someone remembering to check a list.

When it earns its keep, and when to turn it off

It defaults on for us now, which flips the practical question from "should I turn this on" to "when is it worth turning off." If you're running one agent on one task at a time, a shared checkout is simpler and there's nothing to isolate it from — turning it off there costs nothing. Worktree isolation earns its keep once you've got more than one session that might touch the same files concurrently — a supervisor spawning sub-agents, parallel exploratory branches, anything where you genuinely need to know whether another session already changed a given file.

Running this solo, turning it on for one folder costs nothing you'll notice — disk is cheap at that scale, and cleanup is automatic. Running it across a team or a fleet of agents is where the discipline actually matters, and it's worth checking whether whatever you're using solved the registration/cleanup half or just added the isolation and left the bookkeeping to you.

A worktree keeps sessions from stepping on each other's files by convention, not by a hard boundary — any process with the right permissions can still cd into another worktree if it wants to. It's isolation for coordination. Don't treat it as a security control.