Git Worktree Parallel Development

You are halfway through a feature branch when a P0 bug report lands. You need to investigate and fix it immediately, but stashing your in-progress work risks losing context, and switching branches blows away your node_modules and build cache. Git worktrees solve this by giving you multiple independent checkouts of the same repository, and the Codex App makes worktrees a first-class workflow.

What You’ll Walk Away With

• A complete workflow for spinning up, working in, and merging worktree-based Codex threads
• Clear decision criteria for choosing “Work on the worktree” vs “Sync with local”
• Strategies for running multiple agents in parallel on the same codebase without conflicts
• Cleanup and disk-management practices that prevent worktree sprawl

How Codex Worktrees Work

When you start a Worktree thread in the Codex App, Codex creates a Git worktree under $CODEX_HOME/worktrees. The worktree starts at the HEAD commit of whatever branch you select, and it begins in a detached HEAD state — no branch pollution. Your local checkout stays untouched.

Each worktree has its own complete copy of your repository files. They share the same .git metadata (commits, branches, refs), but each has an independent working tree, index, and HEAD. This means Codex can run tests, install dependencies, and make edits in one worktree while you continue working in another.

Note

Worktrees require a Git repository. If your project is not version-controlled, automations run directly in the project directory and Worktree mode is unavailable.

The Two-Path Workflow

After Codex finishes work on a worktree, you have two options for handling the results:

Path 1: Work on the Worktree

Best when you can verify changes directly on the worktree (e.g., your local environment setup script installs all dependencies).

1. Click Create branch here in the thread header to turn the detached HEAD into a named branch.
2. Use the integrated terminal or “Open” button to launch your IDE pointed at the worktree.
3. Run tests, verify changes, and iterate with follow-up prompts.
4. Commit, push, and create a PR directly from the Codex App.
5. Optionally, “Add to sidebar” to promote the worktree to a permanent home for continued work.

Path 2: Sync with Local

Best when you need the changes in your main checkout (e.g., you can only run one instance of your dev server).

1. Click Sync with local in the thread header.
2. Choose to create a new branch or sync to an existing one.
3. Select the sync method:
   • Apply: Calculates changes since the nearest shared commit and applies them as a patch, preserving your local commit history.
   • Overwrite: Makes your local checkout match the worktree exactly, replacing local files and commit history.
4. Resolve any conflicts if your local checkout has diverged.
5. Verify the changes in your local environment.

Prompt: Split a feature across parallel worktree threads

Open three Worktree threads, each based on the same main branch:

Thread 1: “Implement the new /api/v2/users endpoint following the patterns in src/routes/v1/users.ts. Include request validation with Zod and add unit tests.”

Thread 2: “Create the database migration for the users_v2 table. Add the Drizzle schema, migration file, and seed data. Run the migration locally to verify.”

Thread 3: “Update the OpenAPI spec in docs/openapi.yaml to include the v2 users endpoints. Generate the TypeScript client with openapi-typescript.”

Then sync all three to the same feature branch using “Apply” to stack the changes.

Multiple Worktrees, One Feature Branch

A powerful pattern is syncing multiple worktree threads to the same feature branch. Each thread handles a different aspect of the work, and you apply each one sequentially:

1. Start all threads from main
2. As each completes, sync it to feature/user-v2 using “Apply”
3. If changes conflict, use “Overwrite local” to reset and cleanly apply

This effectively parallelizes feature development across multiple Codex agents.

Branch Limitations

Git enforces a one-branch-per-worktree rule. If you create feature/a on a worktree, you cannot check out feature/a in your local checkout or any other worktree simultaneously. You will see:

fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'

The fix: use “Sync with local” instead of trying to manually check out the branch. Or check out a different branch on the worktree first to free the name.

Worktree Cleanup

Each worktree copies your repository files, dependencies, and build caches. This adds up fast. Codex manages cleanup automatically with these rules:

Never cleaned up:

• Worktrees tied to pinned conversations
• Worktrees promoted to the sidebar

Eligible for cleanup:

• Older than 4 days
• When you have more than 10 worktrees

Before deleting a worktree, Codex saves a snapshot. If you reopen a thread whose worktree was cleaned up, you will see an option to restore it.

Watch your disk space

If you run frequent automations, each one creates a new worktree. Archive automation runs you no longer need, and avoid pinning runs unless you intend to keep their worktrees long-term. Monitor disk usage with du -sh ~/.codex/worktrees/ periodically.

When This Breaks

• “Branch is already used by worktree”: Another worktree has that branch checked out. Either switch that worktree to a different branch or use Sync with local instead.
• Sync conflicts: When your local checkout has diverged significantly from the worktree, “Apply” may fail. Use “Overwrite local” for a clean slate, or resolve conflicts manually in the terminal.
• Missing dependencies in worktree: The worktree is a fresh checkout. Configure a local environment setup script in the Codex App settings to auto-install dependencies when a worktree is created.
• .gitignore files not transferring: The sync process uses Git operations, so anything in .gitignore (like node_modules, .env, build artifacts) will not transfer. Run your setup script after syncing.

What’s Next

• Automations — Automations run in dedicated worktrees, so understanding worktrees is the foundation
• App Mastery — The full Codex App workflow including multi-project management
• Batch Operations — Combine worktrees with cloud tasks for large-scale changes