Git worktrees for parallel coding agents: Claude Code and Codex

A Git worktree is a separate working folder for the same repository. It has its own files and branch but shares your main checkout's history and .git directory. Claude Code and OpenAI Codex can both start a session in its own worktree with a --worktree flag, so parallel agents stop editing the same files. The main difference: Claude Code creates worktrees inside your repository on a new branch, while Codex keeps them under $CODEX_HOME/worktrees in a detached HEAD. Both copy gitignored files such as .env through a .worktreeinclude file. Orbtile shows each parallel session on a Logitech MX Creative Keypad or an Android phone, so you can see which one needs you.

How Claude Code and Codex manage Git worktrees

Two agents in one checkout edit the same files and fight over the same branch. A worktree gives each session its own copy of the files to work on.

Start and manage Claude Code worktrees

Pass --worktree or -w with a name. Claude Code creates the worktree under .claude/worktrees/feature-auth/ on a new branch, worktree-feature-auth:

claude --worktree feature-auth

Rules for starting and reusing Claude Code worktrees:

• Names and .gitignore: if you leave out the name, Claude picks one such as bright-running-fox. Add .claude/worktrees/ to .gitignore so worktrees do not show up as untracked files.
• Workspace trust: interactive --worktree runs need workspace trust in that directory first. Run claude there once to accept it. claude -p --worktree skips this check.
• Pull or merge requests: pass a quoted #<number> (claude --worktree "#1234"), a GitHub pull request URL or a GitLab merge request URL. Claude Code fetches that change's head commit from origin into .claude/worktrees/pr-<number>. The fetch never waits for input in your terminal.
• Base branch: by default ("fresh") worktrees branch from your remote default branch. If the repository has not been fetched in 24 hours, Claude Code fetches it, capped at five seconds, and uses the cached ref if that fails. With no remote, it falls back to your local HEAD. To branch from local HEAD, unpushed commits included, set worktree.baseRef to "head":

{
  "worktree": {
    "baseRef": "head"
  }
}

• Reusing names: passing an existing name reopens that worktree. Under "fresh", Claude Code resets it to the default branch only when it has no uncommitted or untracked files, is still on its own branch, and has no commits of its own (or its pull request was merged and the remote branch deleted). Otherwise it reopens at its old tip.
• Mid-session worktrees: ask Claude to "work in a worktree" and it uses the EnterWorktree tool. If permissions.blockWritesOutsideWorkingDirectories is on, Claude Code removes EnterWorktree and ExitWorktree. Start with claude --worktree or claude --bg --worktree instead.

How Claude Code enforces isolation and shares state

Claude Code applies four checks so a worktree session does not change your main checkout:

• File edits: blocks Edit, Write and NotebookEdit calls that target the main checkout.
• Working directory: blocks Bash, PowerShell and Monitor commands that run in the main checkout, or whose directory it cannot verify.
• Git redirects: blocks Bash and Monitor commands that point git at the main checkout through git -C, --git-dir, GIT_DIR, GIT_WORK_TREE or cd.
• Command shape: blocks Bash and Monitor commands when it cannot tell from the text where git will run, such as a command name computed at runtime. PowerShell gets only the working-directory check.

A worktree still shares some state with the main checkout:

• .git and plugins: Git writes go to the shared .git directory. Plugins installed at project scope load in every worktree. If the worktree has no .claude/skills, .claude/agents or .claude/commands of its own, Claude Code reads the main checkout's copies.
• Permissions and hooks: "Yes, and don't ask again" Bash rules save to the main checkout's .claude/settings.local.json. On Windows, and in other cases where Claude Code does not use the repository root, the rule stays with the worktree. ${CLAUDE_PROJECT_DIR} keeps pointing at the starting project root, while cwd in hook input JSON follows the worktree. See Claude Code hooks: events, matchers, settings and handlers.

Cleaning up and resuming Claude Code worktrees

When you exit an interactive session, Claude Code checks the worktree for changed or untracked files, uncommitted work in submodules and new commits:

• Clean unnamed worktrees: removed automatically, along with their branch.
• Named or changed worktrees: Claude asks whether to keep or remove them. Resume a kept one with claude --worktree <name> --resume.
• Non-interactive -p runs: have no exit prompt, so the worktree stays. Its lock stays until a later stale-lock sweep. To remove it yourself, run git worktree unlock and then git worktree remove.

Isolate Claude Code subagents and non-git hooks

Ask Claude to "use worktrees for your agents", or add isolation: worktree to a subagent's frontmatter in .claude/agents/ or ~/.claude/agents/:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

• Isolation and instructions: the subagent runs its Bash and PowerShell commands inside its worktree. Bash commands get the same git checks as above, while PowerShell gets only the working-directory check. Subagent worktrees use the same worktree.baseRef. They take their instructions from the main conversation, and skip the CLAUDE.md and .claude/rules/ inside .claude/worktrees/.
• Locks and cleanup: while a subagent or a backgrounded --worktree session runs, Claude Code holds a git worktree lock on its worktree. A subagent worktree with no changes is removed when the subagent finishes. One with changes stays until the cleanupPeriodDays sweep can remove it without losing work.

For SVN, Perforce, Mercurial or custom paths, configure WorktreeCreate and WorktreeRemove hooks in settings.json. The hook replaces the git logic, so .worktreeinclude is not processed. WorktreeCreate reads .name from stdin and prints the new path on stdout:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Run parallel worktrees in OpenAI Codex

OpenAI Codex supports Git worktrees in the CLI and in the ChatGPT desktop app, which codex app opens on macOS and Windows.

Codex CLI worktree and directory flags

Pass --worktree to start a CLI session in a new managed worktree:

codex --worktree "implement the billing webhook handler"
codex exec --worktree "run the migration and fix failing tests"
codex exec fork <SESSION_ID> --worktree "try an alternative caching approach"

• --worktree: works with new codex sessions, codex fork <SESSION_ID>, codex exec and codex exec fork. It needs local execution. You cannot combine it with resume, review, --ephemeral or --ignore-user-config.
• --cd (-C <path>) and --add-dir <path>: --cd sets the agent's working directory, such as a worktree you made yourself. --add-dir gives write access to extra directories, and you can repeat it.

See OpenAI Codex CLI: install, commands, config.toml and codex exec for all flags and config.toml options.

ChatGPT desktop app worktrees, detached HEAD and Handoff

In the ChatGPT desktop app, pick Worktree and a base branch for a new chat. The ChatGPT mobile app can control Codex on a connected computer, worktree chats included. In Git repositories, scheduled tasks run on their own background worktrees.

• Detached HEAD in $CODEX_HOME/worktrees: worktrees live under $CODEX_HOME/worktrees, and you can change the root in Settings > Worktrees. Each starts at the selected branch's HEAD, with that branch's uncommitted changes applied. Worktrees start in a detached HEAD, so they are not checked out as branches.
• Branching on the worktree: click Create branch here to turn the worktree into a branch. The branch name gets a codex/ prefix by default. Git lets a branch be checked out in only one place, so checking it out in your main checkout then fails (fatal: 'feature/a' is already used by worktree).
• Moving work with Handoff: click Hand off in the chat header to move a chat and its code between Local (the foreground checkout) and Worktree (the background one). Codex runs the Git steps, and a chat handed back returns to the same worktree.

Local environment setup scripts and worktree cleanup

Local environments live in the .codex folder at your project root:

• Setup scripts and actions: setup scripts such as npm install and npm run build run automatically when Codex creates a new worktree. You can add separate scripts for macOS, Windows or Linux. Actions such as npm start appear in the app's top bar and run in its integrated terminal. In the diff pane you can stage or revert changes, leave inline comments, commit and push a branch.
• Cleanup and snapshots: by default the app keeps the 15 most recent managed worktrees. It never deletes worktrees for pinned or in-progress chats. Before it deletes one, after archiving or when over the limit, it saves a snapshot you can restore by reopening the chat.

Copy gitignored files with .worktreeinclude and manage manual worktrees

Both Claude Code and OpenAI Codex (for local ChatGPT desktop app managed worktrees) read .worktreeinclude at the repository root. It uses .gitignore syntax:

.env
.env.local
config/secrets.json

• Ignored files only: a file is copied only if it matches a pattern and is also gitignored, so tracked files are never duplicated.
• Agent rules: Claude Code applies .worktreeinclude to --worktree sessions, subagents and parallel Claude desktop sessions. With a WorktreeCreate hook, copy the files in your script instead. Codex applies it to local desktop app worktrees only. It skips symlinks, never overwrites existing files, and copies an ignored AGENTS.override.md automatically. See Share context between Claude Code and Codex.
• Manual worktrees: to check out an existing branch or use a folder outside the repository, run git worktree yourself. Then start claude inside it, or pass codex --cd ../project-feature-a:

git worktree add ../project-feature-a -b feature-a
git worktree remove ../project-feature-a

Watch parallel worktree sessions on a keypad or phone with Orbtile

Worktrees keep file edits apart, but parallel sessions still stop in separate windows to ask for approvals or answers.

Logitech's MX Keypad works with Logi Options+ to run prompt macros across tools such as Claude Code and OpenAI Codex, with native integrations for VS Code and IntelliJ. Without Options+, Orbtile drives the keypad's nine LCD keys and two page buttons over USB. It can also use an Android phone (Android 8.0 or later) running Orbtile Mobile. Orbtile runs on a computer with macOS 14.0 or later on Apple silicon, or Windows 11 (x64).

• One key per session: shows Claude Code sessions (terminal, desktop app, SSH, and background sessions when Show background sessions is on) and Codex sessions (desktop app, terminal codex, codex exec and SSH). Each key shows the session name, its state (Thinking, Tool, Streaming, Permission, Question or Done) and its latest words over an amber gold (Claude Code) or cool blue (Codex) orb.
• Group by Project, Agent or Host: set Group by in Settings > Keypad. Hold key 9 for 0.6 seconds to open the topic picker, or tap it to focus the first waiting session.
• Inspect isolated subagents: hold a session key for 0.6 seconds to open Focus mode, then press key 2 to see its subagents. Keys 1 to 8 show one subagent each, with its state, tool, text and elapsed time, eight per page.
• Answer prompts from the keys: waiting sessions move to the front. For local Claude Code sessions and compatible Codex desktop chats, press Deny (key 7) or hold Allow (key 9) for 0.6 seconds in Focus mode. You can also pick options on keys 1, 2, 3 and 7 and hold Send on key 9. Terminal Codex approvals offer Allow only, so decline those in the terminal.

See Run several Claude Code sessions and see which one needs you, Approve agent tool calls without switching windows and The Logitech MX Keypad for developers, with and without Options+.