Claude Code worktrees isolate each session’s checkout

Parallel sessions collide over tasks, files and unfinished work

Two Claude Code sessions can each pick the same issue and build the same fix on separate branches.

In a shared checkout, one session’s edits land on top of the other’s in the same files. A worktree gives each session its own checkout and branch.

A stopped session leaves a different problem. The next agent needs to know what changed, what remains and which details could trip it up. A branch alone does not contain that handoff, and an unfinished task still needs an owner who can pick it up without reconstructing the stopped session’s decisions.

claude --continue reopens the most recent session in the current directory, while claude --resume opens one by id or name. Claude Code stores those sessions in ~/.claude/projects/ and deletes them after cleanupPeriodDays, which defaults to 30 days. The session docs also state that running the same session in two terminals interleaves messages from both into one transcript. A resumed session or a second terminal reopens a conversation. That does not hand the work between agents.

The --worktree flag creates a checkout with its own branch

Added in v2.1.49 on February 19, 2026, claude --worktree <name>, also available as -w, creates .claude/worktrees/<name>/ at the repo root. Its new branch is worktree-<name>. Without a name, Claude generates one such as bright-running-fox, while reusing a name opens the existing worktree.

By default, the branch starts from the remote default branch because worktree.baseRef is "fresh". Setting it to "head" starts from your local HEAD instead. You cannot put an arbitrary branch name in worktree.baseRef, as the worktree docs explain.

claude --worktree "#1234" creates a PR worktree under .claude/worktrees/pr-<number>. A .worktreeinclude file copies gitignored files such as .env into each new worktree.

On interactive exit, Claude removes a clean unnamed worktree and its branch, prompts first for a named one, and asks whether to keep worktrees containing work. Runs with -p have no exit prompt and receive no worktree cleanup. Isolation also does not track shell writes, so cp or a shell redirect into the main checkout without running git there is not refused.

Claude Code offers several forms of parallel work

Agent view, available through claude agents and claude --bg, is a research preview introduced in v2.1.139 on May 11, 2026. Before editing, it moves the session into an isolated worktree under .claude/worktrees/. It commits, pushes and opens a draft PR, but never pushes to main or master, force-pushes or merges.

/batch splits a large change into 5 to 30 worktree-isolated subagents. A custom subagent can use isolation: worktree in its frontmatter to get a temporary worktree branched from the default branch, removed if it makes no changes. By default, spawning another subagent when 20 are running fails with Concurrent subagent limit reached, and CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes that ceiling.

Agent teams use CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and do not isolate teammates in worktrees, so the docs say to partition work to avoid same-file overwrites. A teammate loads the same project context as a regular session, including its MCP servers. Independent instances can share a task list in ~/.claude/tasks/ by setting the same CLAUDE_CODE_TASK_LIST_ID. This needs the Task tools, which are on by default only on Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier models.

ListAgents and SendMessage, added in v2.1.224 on August 7, 2026, let sessions on the same machine exchange plain-text cross-session messages, including notices about what landed in another worktree. Claude Code documents no lock or claim between independent sessions. Retasc enforces an exclusive issue claim with an expiring lease so stopped work can return to the queue.

Each session claims its next unblocked issue

One command connects this folder’s agent to the queue. Run npx @retasc/cli@latest bind in the folder you want to connect. It asks for browser approval once if you are not signed in. It gives the folder an agent key, then wires the MCP server at https://mcp.retasc.com/mcp over streamable HTTP. Then start or restart your agent in that folder. Setup wires Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Grok and Pi on the machine in one step.

Each session calls next_issue to claim the highest effective-priority issue that is unblocked and unclaimed. A claim is one server transaction. Two agents can never hold the same issue.

The response carries the issue’s own branch, its body and its last checkpoint, giving the agent the assignment and handoff together. The activeClaims field reports how many other issues have a live lease at that moment. Before the first edit, the server tells the agent to create a worktree from the returned branch and never work in the shared checkout.

That separates task assignment from the terminal you happen to open. Each independent session asks the server for work instead of choosing from a markdown todo file or waiting for you to dispatch it. The claim is a 30-minute lease, renewed by a heartbeat or checkpoint.

Retasc creates a worktree on the issue’s branch

retasc claim, also available as retasc next, claims an issue and creates a git worktree beside the main checkout. The folder is named <repo>-<issue id>. It uses the issue’s own branch, so the checkout has an issue identity before the agent starts editing.

The server computes that branch from the lowercase issue id and a slug of the title. An issue can therefore use a branch such as acme-27/retry-failed-webhooks. Every runtime gets the same branch for that issue instead of deriving a branch from its session’s name.

Add --shell to spawn a subshell inside the worktree. Use --print-path when you need only its path.

claude --worktree chooses .claude/worktrees/<name>/ and worktree-<name> from the supplied or generated name. retasc claim chooses the sibling folder and issue branch from the claimed issue. Claude’s flag provides session isolation, while Retasc connects that isolation to the issue the session owns.

Unclaimed work gets a temporary hold

An agent can start editing an issue’s branch before it claims the issue. The CLI reports a dirty worktree or a commit on that branch within the last 24 hours. Retasc then holds the issue back from dispatch for 60 minutes so another agent does not start the same work.

Calling claim_issue on the held issue turns the hold into a claim. The session then owns a 30-minute lease that a heartbeat or checkpoint renews.

When nothing is ready, Retasc reports how many issues are held. It also reports how many are blocked, claimed, waiting for sign-off or in other people’s lanes. The response explains why no work is ready for that agent.

retasc release hands a claimed issue back to the queue and leaves its worktree and branch alone. The Dash lists every agent with its runtime, the issue it holds and the minutes left on its lease.

Agents must declare dependencies before adding work

Every issue an agent creates must declare its blockers or state in one line why it depends on nothing. Retasc refuses a create with no dependency declaration and suggests similar or mentioned open issues to link. The server also refuses any blocking link that would form a dependency cycle, so an issue cannot end up blocking itself through its dependents.

Blocked work is never handed out. Close a blocker and its dependents join the queue.

A blocker inherits the urgency of the work it holds up, so a chore blocking an urgent feature jumps the queue. Retasc also compares a proposed issue with mentioned open issue ids and titles sharing rare words, refusing a look-alike until the agent names the existing issues it read. The agent can comment on or claim the existing issue, or re-file after naming those issues.

For a wave of subagents, an orchestrator calls next_batch for up to N issues that do not depend on each other. It can peek without claiming. Each claim hands over the issue’s last checkpoint. Subagents inherit the main conversation’s MCP tools. Read the guide for more on running subagents with Retasc.

A stopped session hands its work on through the lease

The Retasc CLI runs beside the agent and renews its leases every 10 minutes without the model doing anything. A long build therefore keeps its claim while the process lives. If the process dies, the laptop closes or the terminal is killed, renewals stop and the 30-minute lease lapses.

The reclaimer returns the issue to the queue in its owner’s lane, where that person’s agents are offered it first. The next agent of the same person can resume on any runtime. If nobody comes back for 7 days, the issue returns to the shared pool.

An agent records a checkpoint with what is done, what is next and the gotchas. Whoever claims the issue receives that checkpoint, including its author and time after a lapse, plus the reclaim count. The handoff stays on the issue instead of depending on the stopped session’s transcript, so changing the runtime does not discard the recorded progress.

After a restart or /resume, the agent re-claims the issue with its claim token, moving the live lease to the new session without changing its status or checkpoint. After /clear, Claude Code is told which issues its window still holds so it can continue or release them. The Dash shows the command to reopen the agent session that worked the issue, such as claude --resume, codex resume or gemini --resume.

Retasc carries each issue through review and cleanup

retasc gate install installs a commit-msg hook and a check-commit-message GitHub Action for the project’s issue prefix.

Closing an issue removes its worktree and merged branch. Run retasc tidy to reconcile the repo’s issue branches against issue status, adding --prune to delete branches and worktrees whose issues are done and merged. Without --prune, it reports the state without deleting those branches or worktrees, so you can inspect the cleanup before running it.

Review goes to a different person’s agent. The server refuses to let whoever sent the work to review claim or accept that review. An agent cannot move work to review without saying where it is (a branch, PR or commit) unless it already left a checkpoint. The reviewer is handed that note. Work waiting for review sorts at least High as soon as it enters review. That review reaches Urgent after 21.6 hours. After 24 hours, it sorts above everything else waiting in the queue.

Retasc cannot tell when two different issues touch the same files. A person still needs to split that work.

Questions about parallel agents

Run the command in your repo, then start each Claude Code session there to claim its own issue and work in that issue’s worktree. A new org gets $10 of usage at signup, no card.