[FEATURE] Native Git Worktree Management for Parallel & Isolated Agent Execution

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

While Claude Code currently supports running inside an existing Git worktree, it does not manage the lifecycle of those worktrees automatically.

Currently, if I want to run a complex refactor or an experimental task without blocking my main working directory (or polluting my current git index), I have to:

1. Manually run git worktree add ... in my terminal.
2. Navigate to that directory.
3. Initialize Claude Code in that new context.
4. Manually cleanup/remove the worktree when finished.
5. Manually merge the changes back if successful.

This friction prevents me from utilizing Claude Code for parallel tasks. In tools like Cursor, the "Agent" mode automatically spins up a shadow worktree, applies context, attempts the task, and then offers a clean "Apply" button to merge back into the main branch. I want to achieve this fluid, non-blocking workflow entirely within the Claude Code CLI without manually managing git plumbing.

Proposed Solution

I propose adding a native --isolate flag (or a specific slash command like /spawn) to Claude Code that handles the creation, execution, and cleanup of git worktrees automatically.

Ideal User Experience:

1. Invocation:

I run a command like:
``bash
claude --isolate "Refactor the authentication middleware to use JWT"
`
*Or, inside an interactive session:*
`text
> /spawn Refactor authentication middleware
``

1. Automatic Setup:

Claude Code automatically:

• Creates a temporary git worktree (e.g., in .claude/worktrees/task-id).
• Copies relevant uncommitted changes from the current working directory (similar to Cursor's implementation) so the context is preserved.
• Switches to a new temporary branch.

1. Execution:

A new Claude Code session starts within that isolated environment. It performs the edits and runs tests without affecting my main terminal's file system or locking the git index.

1. Resolution:

Once the task is complete, Claude Code presents a summary in the main thread with options:

• Apply: Merges the worktree changes into the current branch (squashed or as a commit).
• Discard: Deletes the worktree and temporary branch.
• Inspect: Opens a shell in that worktree directory.

Alternative Solutions

• Manual Worktrees: Manually running git worktree add ../temp-branch, cd ../temp-branch, claude, and then cleaning up. This is high friction and prone to user error (forgetting to delete worktrees).
• Git Stashing: Stashing changes, running Claude, and popping stashes. This is risky if Claude modifies files that conflict with the stash, and it prevents parallel work.
• Using Cursor: Cursor provides this natively, but I prefer the Claude Code CLI workflow and its specific tool integrations.
• Claude Desktop App: The desktop app allows opening multiple sessions in worktrees, but this is a UI-driven approach. I need a CLI-driven, agentic approach where the tool manages the isolation logic.

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

Scenario: Hotfix while working on a Feature

1. I am deep in the middle of a feature in src/components/Dashboard.tsx on the feature/new-ui branch. My working tree is dirty with uncommitted experiments.
2. A critical bug is reported in src/utils/api.ts.
3. I do not want to stash my UI work or switch branches in my main terminal.
4. I run:

``bash
claude --isolate "Fix the retry logic in src/utils/api.ts"
``

1. Claude Code spins up a worktree in the background. It reads the file, reproduces the issue (via a test case it writes), and patches it.
2. My main terminal remains on feature/new-ui with my uncommitted UI changes untouched.
3. Claude reports: "Fix verified. Tests passed."
4. I select "Apply". Claude merges the fix into my current branch (or pushes a hotfix branch), deletes the temporary worktree, and I continue working on my UI feature without ever having context-switched my file system.

Additional Context

• Reference Implementation: Cursor's "Agent" mode. It creates a temporary worktree, brings along new/edited files from the primary tree, runs the agent in isolation, and offers an "Apply" button to merge.
• Technical Constraint: Needs to handle .gitignore and ensure node_modules or similar dependencies are linked or accessible so the isolated environment can run build/test commands without a fresh npm install.
• Feature Parity: This brings the "Parallel Agent" capabilities of GUI-based AI editors into the terminal-native ecosystem.