Mooring
All guides

Claude Code worktrees

Give each Claude Code task a worktree of its own

You want each Claude Code task kept apart from your main checkout, and from the other tasks. A git worktree does that. Here is what claude --worktree makes, and how to tidy up after.

A git worktree is a second folder for the same repository, on a branch of its own. Run claude --worktree with a name, and Claude Code makes one, by default in .claude/worktrees in your repository, and starts the session there, so its edits stay out of your main checkout.

A worktree is a second folder for one repository

A git repository usually has one working folder, the one you cloned. A worktree adds another, on a branch of its own.

Its files are separate, so a change made there leaves your main checkout alone. The history is shared. Every worktree uses the repository’s one .git directory, so a commit made in any worktree is in the repository straight away.

That makes a worktree a good home for a Claude Code task. The session edits only its own folder, while you, or another session, carry on elsewhere.

Good to know

  • Worktrees keep file edits apart. To split one task between helpers inside a single session, use subagents instead.

In Mooring: No git worktree list. Every worktree, however it was made, is a row in the sidebar under its project.

Mooring’s main window. In the sidebar, skiver’s tile, reading SKV, its ticket code, sits in the column on the left, and the panel beside it lists the main folder and three worktrees, each named by its card, with the questions last asked of Claude under the first. The middle is that worktree’s Claude tab, where Claude has just added a sweep that clears stale typing indicators. On the right, the Cards tab lists seven cards, each with its key, status in colour, priority, title and description, among them “Dave has been typing for three days” and “Paginate #random.”
In Mooring: A project’s main folder and three worktrees, each on a branch of its own.

What claude --worktree makes

Give claude --worktree, or -w for short, a name for the task. Before the session opens, Claude Code makes two things: a folder, .claude/worktrees/add-search, and a new branch checked out in it, worktree-add-search.

# folder .claude/worktrees/add-search, branch worktree-add-search
claude --worktree add-search

# the same, shorter
claude -w add-search

# no name: Claude Code makes one up
claude --worktree

Good to know

  • The new branch starts from the repository’s default branch on the remote, usually main, not from the branch you have checked out. So work you haven’t pushed isn’t in it.
  • With no name, Claude Code makes one up, in the style of bright-running-fox.
  • A second terminal with a second name gives a second session, in a separate worktree.
  • The folder must be a git repository Claude Code already trusts. If claude has never run there, run it once and answer the trust prompt.

In Mooring: No commands. Right-click the project’s tile in the sidebar, choose New Worktree…, then click Create. Mooring makes the folder in .claude/worktrees, on a worktree- branch.

Start from a pull request

To work on an open pull request, give its number in place of a name, with a # in front. Claude Code makes the worktree from the pull request’s head commit, in .claude/worktrees/pr-1234.

claude --worktree "#1234"
claude --worktree https://github.com/acme/app/pull/1234

Good to know

  • Put the number in quotes, or the shell may read everything from the # on as a comment.
  • A link to a GitHub pull request or a GitLab merge request works too.

Get a new worktree ready to run

Claude Code builds the worktree from what git tracks, so it starts out like a fresh clone. The source is all there, but nothing git ignores is: no .env, no node_modules, no build output.

  1. Ignore the worktrees and list the files to copy, from the main checkout.
  2. Install the dependencies inside the new worktree.
# from the main checkout: ignore the worktrees, bring .env into new ones
echo ".claude/worktrees/" >> .gitignore
echo ".env" >> .worktreeinclude

# inside a new worktree: install, as in a fresh clone (a Node project here)
cd .claude/worktrees/add-search
npm install
Mooring's main window with the files pane open on the skv-1-dave-is-typing worktree. The tree is open down to src/presence/typing.ts, and README.md is selected. The panel under the tree describes it: its kind, its size, when it was created and modified, and where it is, the project root.
In Mooring: A worktree’s own files, in a tree beside its terminal.

What happens when you leave

When you leave a session in a worktree, Claude Code looks at what the worktree holds.

If nothing has changed, it removes the worktree along with its branch. If you gave the session a name of its own, it asks first.

If the worktree holds uncommitted changes or new commits, Claude Code asks what to do. Keep it, and the folder and the branch stay put. Remove it, and both are deleted, work and all.

To come back to a kept worktree, run the command Claude Code prints on the way out:

claude --worktree add-search --resume

Good to know

  • A session’s name is its own, not the worktree’s. claude --worktree add-search on its own starts an unnamed session.

Start from a task, and see where each one stands

The --worktree option takes a name, not a task. So the name is where the task goes.

  1. Name the worktree after its ticket, such as skv-42-add-search, so the folder and the branch both name the task.
  2. Give Claude the task as your first message.
# every worktree: folder, latest commit, branch
git worktree list

# changes not yet committed in one worktree
git -C .claude/worktrees/skv-42-add-search status --short

# commits the branch adds over the remote’s main
git log --oneline origin/main..worktree-skv-42-add-search

In Mooring: No git commands. Select a task in the Cards tab, press ⌘S, then click Create. Each sidebar row shows its branch, commits ahead and uncommitted files.

Mooring's main window on the skv-1-dave-is-typing worktree. At the foot of the files pane, the Branch section compares it with main: one commit ahead, five lines added in one file, a green “No conflicts with main”, and a Files 1 | Commits 1 switch above the file the branch adds, typing.ts.
In Mooring: What a worktree’s branch adds over main, and whether it merges cleanly.

Move stray changes into a worktree

Sometimes the work starts in your main checkout before you think of a worktree. Stashes belong to the repository, not to one folder, so the changes can move across.

  1. In the main checkout, set the changes aside: git stash push -u -m "add-search"
  2. Still there, start the worktree session, and leave it running: claude --worktree add-search
  3. In a second terminal, go into the new worktree: cd .claude/worktrees/add-search
  4. Bring the changes over: git stash pop

Good to know

  • Keep the session open until the pop is done. Leave it while the worktree is still clean, and Claude Code removes it and its branch, unless the session has a name of its own.
  • The new branch starts from the remote’s main, not from your checkout, so the changes may not fit cleanly.
  • If the pop runs into conflicts, git keeps the stash. Fix the conflicts, then run git stash drop.

In Mooring: No stash. Choose Move to a New Worktree… from the main folder row’s ⋯ menu, and name the work. Files git isn’t tracking yet stay in the main folder.

Tidy up after a merge

Once the branch is merged, remove the worktree, then its branch. Neither step throws work away by accident.

  1. In the main checkout, bring main up to date: git pull
  2. Remove the worktree: git worktree remove .claude/worktrees/add-search
  3. Delete its branch: git branch -d worktree-add-search

Good to know

  • git worktree remove refuses while the worktree has changed or untracked files.
  • git branch -d deletes a branch only when git can see it was merged.
  • After a squash merge git can’t see that, and -d refuses. Check the work is in main, then use -D.

In Mooring: No git commands. Remove Worktree… in the row’s ⋯ menu deletes the folder and branch, even after a squash merge, and warns first if work would be lost.

With Mooring

Everything above works with plain Claude Code and git. Mooring takes the bookkeeping away. No branch names to make up: ⌘S suggests one from the task. No git worktree list: each sidebar row shows its branch, commits ahead and uncommitted files. No stash to juggle: Move to a New Worktree… carries stray changes across. No cleanup commands: Remove Worktree… deletes the folder and branch.

Worktrees made either way, side by side

Mooring builds its sidebar’s list of worktrees from git, not from its own records. So a worktree made with claude --worktree gets a row beside the ones Mooring made.

A row takes its name from the branch, minus the worktree- prefix, with the full branch underneath: worktree-add-search shows as add-search. A row linked to a task shows the task’s key and title instead.

Mooring makes its own worktrees in the same place, the project’s .claude/worktrees folder, on branches that start with worktree- too, so both kinds follow one pattern.

Mooring’s main window on the skiver project. A column of tiles runs down the left edge, one for each project. The pointer rests on skiver’s tile, which reads SKV, its ticket code, and a popover beside it names the project, skiver, with its ticket code SKV and its folder, ~/Development/skiver, then lists the main folder and the three worktrees, each with its card: SKV-1 “Dave has been typing for three days”, SKV-2 “Rate-limit searches for ‘is it Friday yet’” and SKV-5 “Stay ‘Away’ through a token refresh.” Behind it, Claude is at work in the first worktree’s tab.

From a task to a worktree with ⌘S

Select a task in the Cards tab and press ⌘S, or choose Send to New Worktree… from its right-click menu.

A sheet suggests a name and shows the folder and the branch it will make, such as .claude/worktrees/skv-42-add-search on the branch worktree-skv-42-add-search. Here skv-42 is the task’s ticket key.

Click Create, and Mooring makes the worktree, opens a Claude tab in it, and waits for Claude’s prompt before handing the task over.

The first time Claude starts in a project, it asks you to trust the folder, and Mooring waits for your answer.

⌘S on SKV-4, and the New Worktree sheet names its worktree.

When Claude is slow to start

If Claude’s prompt isn’t ready within 20 seconds, Mooring says so above the tab. Try Again hands the task over in the same worktree and tab, so trying again never makes a second worktree.

Mooring's main window with a new tab open in the skiver worktree made for SKV-7. Above its terminal the Assistant shrugs: Claude didn't start in time, with Dismiss and Try Again beside it.

Review against the branch it came from

Mooring notes the branch each worktree it makes was made from, so the Changes tab reviews the work against that branch.

When the branch merges into the default branch, Mooring moves its task to Done, with a short summary of the work.

Shown with Skiver, a made-up team chat app for people avoiding work.

Sources

Checked 7 November 2026, from these sources. Spotted something out of date? Say so.

More guides