Isolate risky work in a worktree

A git worktree is a second working directory for the same repository, on its own branch, sharing history and remotes with your main checkout. The agent can refactor freely there while your primary checkout stays clean and buildable.

When PromptConduit flags this

PromptConduit marks a session as “worktree used” if any of its events show that the working directory is a git worktree, carry a worktree path, call the EnterWorktree or ExitWorktree tool, or fire the WorktreeCreate hook.

The “Consider a worktree for heavy work” note (severity: info) fires when no worktree was used and the session was heavy:

• Editor extension (live session): at least 80 tool calls, in a session with at least 3 prompts.
• Web Trends view: at least 400 tool calls across the selected period, with at least 5 prompts, and no worktree use anywhere in it.

This is an informational nudge, not a warning. Plenty of heavy sessions belong in the main checkout. The note is there for the ones where a failed attempt would leave a mess.

Why it matters

Worktrees isolate file edits. That gives you three things:

• A cheap undo. If the attempt goes wrong, remove the worktree and branch. Your main checkout never moved, so there’s nothing to revert by hand.
• Parallel work without collisions. You keep building, testing, or reviewing in your main checkout while the agent edits in its own copy. Two agent sessions in two worktrees don’t overwrite each other.
• A clean review boundary. Everything the agent did is on one branch, so you review it as a diff and merge or discard it like any other branch.

It is not a cost optimization in itself. The benefit is lower risk on big, speculative, or long-running changes.

What to do

Start the session in a worktree. In Claude Code:

claude --worktree refactor-auth

That creates .claude/worktrees/refactor-auth/ on branch worktree-refactor-auth. Run the same command with a different name in a second terminal for a second isolated session. Add .claude/worktrees/ to your .gitignore so the worktree contents don’t show up as untracked files in the main checkout.

Or ask mid-session. Tell Claude to “work in a worktree” and it uses the EnterWorktree tool to create one and move the session into it.

Set up the environment. A worktree is a fresh checkout, so install dependencies there. To carry gitignored files across automatically, add .worktreeinclude at the project root:

.env
.env.local

Pick the base. New worktrees branch from the repository’s default branch. To branch from your current local HEAD instead (for example, to carry unpushed commits), set "worktree": { "baseRef": "head" } in settings.

Clean up on exit. A clean, unnamed worktree is removed automatically. If there is work in it, Claude Code asks whether to keep it and prints a claude --worktree <name> --resume command for later. For worktrees you created by hand, use git worktree list and git worktree remove.

Combine with planning and delegation. Approve a plan first, then let it execute in the worktree. For parallel edits by several subagents, ask Claude to “use worktrees for your agents”, or add isolation: worktree to a custom subagent’s frontmatter so each one gets its own temporary worktree.

How to check it worked

In the editor extension’s coaching tab, the Worktree cell under “How you drove the agent” reads Yes · Isolated on a branch when the live session used one, and No · Ran in the main checkout otherwise. The note stops appearing for heavy sessions once they run in a worktree.

PromptConduit also records the repository and branch on every event, so a worktree session shows up under its own branch. If you track spend per repository, see Cursor AI spend by repo and model for how the repo and branch context is used. Setup for the coaching tab is in /docs/editor-extension.