Codex Worktrees — Isolated Parallel Execution Without Branch Chaos

Official References: Codex Worktrees · Subagents · Best Practices

Curriculum path

1. Codex Getting Started — Install, First Task, and Git Checkpoints — first safe loops
2. Codex Instructions — Make AGENTS.md Actually Useful — repo rules and defaults
3. Codex Sandboxing — Permissions, Approvals, and Cloud Environments — permissions and boundaries
4. Codex Task Design — Write Prompts Like Issues, Not Wishes — shape work well
5. Codex Skills — Turn Repeated Prompts into Reusable Workflows — turn repeated work into reusable assets
6. Codex Subagents — Parallel Execution and Delegation Patterns — parallel execution and delegation
7. Codex MCP — Connect External Context Instead of Copy-Pasting It — connect outside systems
8. Codex Reviews and Automations — /review, Worktrees, and Repeatable Engineering — run stable workflows repeatedly
9. Codex Worktrees — Isolated Parallel Execution Without Branch Chaos ← You are here
10. Codex Handoffs — Turning Parallel Lanes into Merge-Ready Outcomes
11. Codex Verification Loops — Prove It Works Before You Merge
12. Codex Release Readiness — Final Gates Before Production
13. Codex Safe First-Day Loop — Beginner Workflow That Avoids Early Mistakes
14. Codex Team Delivery Playbook — Intermediate Lane Operations
15. Codex High-Risk Change Governance — Advanced Controls for Critical Releases
16. Codex Operating Manual — Daily, Weekly, and Release Rhythms for Teams
17. Codex Incident Recovery Playbook — Deterministic Response Under Production Pressure
18. Codex Post-Incident Hardening Loop — From Recovery to Durable Controls
19. Codex Chaos Resilience Drills — Rehearsing Failure Before It Finds You
20. Codex Resilience Metrics and SLOs — Measuring Reliability Before It Fails
21. Codex Ralph Persistence Loops — Running Long Tasks to Verified Completion

Official docs used in this guide

• Worktree behavior in Codex and Git repos — Codex Worktrees
• How this differs from subagent parallelism — Subagents
• Task decomposition and workflow sizing — Best Practices

Why worktrees matter for Codex users

When you use Codex heavily, the bottleneck is often branch context, not coding speed.

You want to:

• keep your current task stable
• run a second task in parallel
• avoid stashing and popping changes all day

A git worktree gives you a second (or third) checkout of the same repository, each with its own branch and working directory.

Think of it as parallel doing (isolated filesystem + branch), while subagents are more about parallel thinking.

When to choose worktrees vs subagents

In practice, teams often combine both:

1. Use subagents for fast exploration.
2. Move the chosen approach into a dedicated worktree.
3. Let Codex execute and verify there.

Practical setup pattern

1) Create a task-named worktree

git fetch origin
git worktree add ../wt-auth-retry -b feat/auth-retry origin/main

Naming tip:

• Directory: wt-{topic}
• Branch: feat/{topic} or fix/{topic}

Consistent naming makes cleanup and review much easier.

2) Open Codex inside that worktree

Start Codex from the worktree directory so all edits, tests, and commits stay scoped to that task.

cd ../wt-auth-retry
codex

3) Verify before merge

In the worktree:

• run lint/typecheck/tests
• review the diff for only task-relevant files
• commit and push

Then open a PR as usual.

Lightweight operations you should memorize

# List active worktrees
git worktree list
 
# Remove a finished worktree directory
git worktree remove ../wt-auth-retry
 
# Delete the branch after merge
git branch -d feat/auth-retry

If Git says a branch is still "checked out," run git worktree list first and remove the related worktree.

Operational guardrails

Keep each worktree single-purpose

Do not mix unrelated changes. One worktree should map to one reviewable task.

Keep AGENTS.md visible in each path

Codex follows instruction files by directory scope. If your repo uses nested AGENTS.md files, verify the worktree path still inherits the intended rules.

Avoid stale long-lived trees

Old worktrees cause branch drift and merge friction. Prefer short-lived, task-focused lifecycles.

Team playbook example

• main repo: hotfix triage and release prep
• wt-feature-a: Codex handles new feature implementation
• wt-migration-b: Codex runs migration + tests
• wt-docs-c: Codex updates docs and release notes

Each lane is isolated, but all lanes share the same remote repository and review pipeline.

Common mistakes

Reusing one worktree for many tasks

This recreates the same context collisions worktrees are supposed to solve.

Forgetting cleanup

Unused worktrees accumulate quickly and confuse branch ownership.

Mixing “exploration” and “execution” in one lane

If you are still comparing options, stay in subagent mode first. Create a worktree once you commit to one path.

Prompt templates you can copy

Template A — implementation lane

Work in this task worktree only: ../wt-{topic}
 
Goal:
- Implement <feature/fix> with the smallest reviewable diff.
 
Constraints:
- Do not edit files outside <directories>.
- Run lint + tests before proposing commit.
- Summarize risks and rollback path.

Template B — verification lane

Use this verification worktree to audit branch <branch-name>.
 
Check:
- failing tests
- type and lint regressions
- security-sensitive diff segments
 
Return:
- PASS/FAIL
- concrete file/line findings
- minimal fix plan

Template C — docs/release lane

In this docs worktree, update docs and release notes only.
 
Do:
- read merged PRs since <date>
- group by user-facing impact
- produce concise release notes draft
 
Do not modify application source files.

Failure recovery playbook

When worktrees fail, the failure mode is usually operational, not technical.

Case 1: dirty worktree blocks removal

git -C ../wt-auth-retry status
git -C ../wt-auth-retry stash -u   # or commit
git worktree remove ../wt-auth-retry

Case 2: branch drift gets too large

git -C ../wt-auth-retry fetch origin
git -C ../wt-auth-retry rebase origin/main

If conflicts are heavy, open a fresh worktree and replay only the still-valid commits.

Case 3: wrong base branch used at creation

Close the worktree early. Recreate from the correct base instead of forcing a risky rebase chain.

Team metrics that prove this is working

Track worktree adoption with a few lightweight indicators:

• review lead time per PR (did isolation speed review?)
• rework rate after review (did scope isolation reduce back-and-forth?)
• context-collision incidents (stash churn, accidental cross-task edits)
• age of open worktrees (old trees usually predict merge friction)

If these metrics improve over 2–4 weeks, your worktree practice is paying off.

Naming matrix that scales

When teams exceed 3–4 concurrent worktrees, ad-hoc naming breaks discoverability. Use a compact naming matrix:

This lets people infer intent from the path alone, which improves review routing and cleanup speed.

Cross-lane handoff contract

Parallel lanes fail when handoff quality is inconsistent. Standardize what every lane must return:

• Goal status: done / partial / blocked
• Evidence: lint/test/build output (or reason omitted)
• Diff scope: which directories changed and why
• Risk note: rollback plan and unresolved edge cases
• Next owner: who should pick it up next (reviewer, verifier, release lane)

Think of this as an internal API between worktrees. Better contract, less coordination drag.

Weekly operating cadence example

A simple cadence many teams can adopt:

• Mon: open implementation and migration worktrees
• Tue–Wed: run implementation lanes + daily verification lane checks
• Thu: merge-ready review pass with branch-vs-base diff focus
• Fri: docs/release lane updates + stale worktree cleanup

The cadence matters less than consistency. Repeating the same weekly rhythm reduces context thrash.

Decision table: single lane vs subagents vs worktrees

Use this quick table when people disagree on execution style:

Sequence rule:

1. Explore with subagents if uncertainty is high.
2. Execute in worktree once one path is selected.
3. Verify in separate lane if risk or scope is medium/high.

Team policy snippet you can adopt

You can paste this into your engineering handbook or AGENTS.md companion docs:

### Worktree Policy
 
- One worktree must map to one reviewable objective.
- Worktree names must follow the approved naming matrix.
- Every handoff must include status, evidence, diff scope, and risk note.
- Every handoff must name the next owner (reviewer, verifier, or release lane).
- Worktrees older than 14 days must be reviewed for merge/cleanup.
- Verification lane is required for migrations, auth, billing, or security-sensitive changes.

This turns worktree usage from “personal preference” into a team-level operating contract.

Quick checklist

Before opening a worktree:

• Is this task likely to run longer than one focused session?
• Does it need branch isolation from your current work?
• Can you give it a clear task name and exit condition?

Before deleting a worktree:

• Is the branch merged or safely pushed?
• Are lint/tests done and evidence recorded?
• Has the related PR or issue been linked?

Use worktrees when you need clean parallel execution with strong branch boundaries. They are one of the highest-leverage habits for advanced Codex workflows.