D11 · Worktrees & agent view

D10's subagents answered "how do we split the work"; today answers "how do the files not collide": a worktree gives every parallel session its own copy of the files, and agent view is the control desk for those sessions — who's running, who's waiting on you, who's finished, at a glance.

Why this lesson comes today

D10 covered subagents: splitting one task across multiple agents advancing in parallel — that's parallelism of work. But as long as they all write files in the same working directory, parallelism has a ceiling — two sessions edit the same file, and the later write clobbers the earlier one. This lesson adds the other dimension, parallelism of files: Officialthe official docs explicitly divide the labor between the parallel mechanisms — worktrees isolate file changes, while subagents and agent teams organize the work itself, and the two stack.

This lesson is also the foundation for D12 agent teams: sessions can only collaborate if each has its own turf. And once background sessions multiply, you need a panel to keep watch over them — that's this lesson's second lead, agent view. To go straight into the full multi-session parallel playbook afterwards, read on with Tip B2: Running parallel sessions with worktrees and Tip B1: Multiple sessions or multiple agents.

Core concepts, explained

git worktree: one repo, many workbenches

OfficialA git worktree is a separate working directory: it has its own files and its own branch, but shares the same repository history and remotes with the main checkout. Each Claude Code session runs in its own worktree, so one session's edits can never touch another session's files — build a new feature on one side while fixing a bug on the other.

Our takeAn analogy: the repo's .git is a library's collection, and the main checkout is the reading desk you usually sit at. Worktrees are extra desks, each with a different branch's files spread out — the desktops never interfere, but every book is borrowed from the same collection, and returns (commits) all go back into that same collection.

Misconception: a worktree is not a clone

Our takeA common misreading is "a worktree is just another clone". The difference is what gets shared: a clone is a second, complete repository with independent history, synced back and forth via push/pull; a worktree copies only the working files, and Officialgit commands inside it write directly to the main repo's shared .git directory — commit in a worktree and the main checkout can see that branch immediately, so merging back to the main branch is one local merge or one PR, with no "cross-repo ferrying". Beyond .git, a worktree also shares project-level plugins and saved permission approvals with the main checkout ("Yes, don't ask again" is written back to the main checkout's .claude/settings.local.json and applies repo-wide).

Opening an isolated session with --worktree

OfficialStart with --worktree (short form -w) and a name, and Claude Code creates the worktree and opens the session right inside it. The default location is .claude/worktrees/<name>/ under the repo root, with a new branch named worktree-<name>; omit the name and one is generated for you (like bright-running-fox). Run it again in another terminal with a different name and you have a second session that can't interfere with the first.

claude --worktree feature-auth   # terminal 1
claude --worktree bugfix         # terminal 2, fully isolated from terminal 1

OfficialA few companion moves: add .claude/worktrees/ to .gitignore so worktree contents don't show up as untracked files in the main checkout; a worktree is a fresh checkout, so gitignored files like .env aren't in it by default — add a .worktreeinclude file at the project root (gitignore syntax) to have them copied automatically into every new worktree; new worktrees branch off the repo's default branch (usually main) — set worktree.baseRef to "head" to branch off your current HEAD instead, carrying your unpushed work along; claude --worktree "#1234" branches straight off a PR. Mid-session, you can also just tell Claude to "work in a worktree" and it creates one with the EnterWorktree tool. In the desktop app, every new session lives in its own worktree by default.

Cleanup and merging

OfficialWhen you exit an interactive worktree session, Claude checks whether it contains anything that deleting would lose (changes, untracked files, new commits):

• Clean + unnamed session: worktree and branch are deleted automatically; named sessions get asked first, so you can keep them around to come back to.
• Has work: asks whether to keep or delete. Keep, and the directory and branch stay for a later return; delete, and the work goes with it.
• Run non-interactively with -p: no exit prompt, no cleanup — remove it yourself with git worktree remove.

Our takeThere's no dedicated "merge" command because none is needed: the work sits on the worktree-<name> branch and history is shared, so back in the main checkout it's simply git merge worktree-<name>, or push the branch and open a PR — the same as merging any other branch.

OfficialSubagents can each take a worktree too: tell Claude to "use worktrees for your agents", or pin it in a custom subagent's frontmatter with isolation: worktree (building on D10). A subagent's temporary worktree is deleted automatically if it ends with no changes; those with changes stay on disk and are collected by a periodic sweep according to the cleanupPeriodDays setting — the sweep skips worktrees that still hold work, and never touches the ones you opened yourself with --worktree.

agent view: every background session on one screen

OfficialAgent view opens with claude agents: one screen for all your background sessions — what's running, what's waiting for your input, what's done. Each row is a full Claude Code session hosted by a separate supervisor process, running continuously with no terminal attached. Sessions are grouped by status, with "Ready for review" (PR opened) and "Needs input" at the top; the row icon's color and animation signal state: animated = working, yellow = waiting for your input, green = done, red = failed. The one-line summary in each row is generated by a Haiku-class model, and when a session has opened a PR the row ends with a status-colored #1234 tag. Note it's currently a research preview: it needs Claude Code v2.1.139 or later, and the UI and shortcuts may change.

OfficialOne lap around the core controls: type a task in the bottom input box and press Enter to dispatch a new background session (every line you enter is a new session — fire off several in a row to run them in parallel); select a row and press Space to open a peek panel showing its latest output or the question it's asking, and type right there to reply; press Enter or → to attach into the full conversation, and ← on an empty input box to detach back to the list; Esc exits agent view with sessions still running. Send an existing foreground session to the background with /bg (or ← on an empty input box); from the shell, claude --bg "task" dispatches directly, managed with claude attach / logs / stop / rm <id>. Two limits: every background session burns subscription quota independently — ten in parallel burn ten times as fast; and sessions run on your machine — they survive sleep, but shutdown stops them.

How the two lock together

OfficialAgent view's file isolation is worktrees, exactly: each background session starts from your working directory but moves itself into its own worktree under .claude/worktrees/ before touching any files — parallel sessions read the same checkout, but each writes in its own. This is skipped when you're already inside a worktree, or when the directory isn't a git repo at all (and no WorktreeCreate hook is configured); to turn it off entirely, set worktree.bgIsolation to "none" in project settings. When a background session finishes its edits in a worktree, it wraps up by securing the work: it commits without asking, pushes the branch if the repo has a remote, and opens a draft PR when the task calls for it — but it never pushes to main/master, never force-pushes, never merges, and your own git conventions in CLAUDE.md or the task take precedence. Pressing Ctrl+X twice in agent view deletes the session together with its worktree (uncommitted changes go too) — though a worktree with unpushed commits is never deleted.

Hands-on: doable today

Requires a project that is a git repo. About 25 minutes end to end.

1. Run claude --version to check your version (agent view needs v2.1.139+; the latest at the time of writing is 2.1.222). If Claude has never run in this project, run claude once at the project root first to accept workspace trust, or --worktree will error out.
2. Add .claude/worktrees/ to the project's .gitignore. Expected: the worktrees you open later won't pollute git status in the main checkout.
3. Run claude --worktree demo. Expected: the session starts inside .claude/worktrees/demo/ on branch worktree-demo.
4. Paste the prompt below as-is and let it prove its own isolation:

You should be inside a git worktree right now. In order:
1. Run pwd and git branch --show-current, and tell me the current directory and branch;
2. Append the line "worktree isolation test" to README.md and commit it to the
   current branch — do not push;
3. Run git worktree list and explain in one sentence how the main checkout and the
   current worktree relate in the output.

5. Open another terminal and run git status and git worktree list in the main checkout. Expected: the main checkout is clean and README unchanged, yet git worktree list shows two lines — isolation and sharing verified in one go.
6. Exit the worktree session. Expected: because it holds a new commit, Claude asks whether to keep or delete; choose keep. Then merge and clean up from the main checkout: git merge worktree-demo, followed by git worktree remove .claude/worktrees/demo.
7. Try agent view: run claude agents, type a small task in the bottom input box (like "summarize this repo's directory structure") and press Enter. Expected: a row appears, its icon animating to show Working; press Space to peek at its progress, Enter to attach into the full conversation, ← on an empty input box to return to the list. When it finishes, press Ctrl+X twice to delete the row (remember: its worktree is deleted with it).

How to know you've learned it

• Without notes, you can explain worktree vs clone: what's isolated (files, branch, directory) and what's shared (.git history, remotes, plugins, permission approvals).
• The hands-on ran end to end: after committing in the --worktree session, the main checkout could merge that branch immediately; and you saw the cleanup prompt on exit.
• You can say when a background session automatically moves into a worktree, when it skips that, and what deleting a session in agent view means for its worktree.
• Self-check: you ran a one-off task with claude -p --worktree ci-run — is the worktree still there afterwards? How do you clean it up? (Answer: yes — non-interactive runs get no exit cleanup; remove it yourself with git worktree remove.)