Codex Parallel Worktrees skill for Codex

Parallel work is done well when every Codex chat owns its own checkout, no two chats edit the same files, each checkout can build and test on its own, and the results land as separate, reviewable branches. Two agents in one working tree is a race, not parallelism.

Decide first: parallel or sequential

Situation	Do this
Tasks touch disjoint files or packages	Parallel worktrees, one chat each
Task B needs task A’s output (API, schema, types)	Sequential: finish A, branch B from A
Two approaches to the same problem	Parallel worktrees from the same base, keep the winner
Tasks share a lockfile, migration sequence or generated file	Sequential, or one chat owns that file and the others avoid it
A quick question while a long task runs	Side chat (/side in the CLI), not a worktree

Parallel runs multiply usage: three chats consume roughly three times the tokens. Only fan out when wall-clock time matters more than spend.

Workflow

- [ ] 1. Check repo state and pick the base commit
- [ ] 2. Split the work by file ownership
- [ ] 3. Create one worktree per task
- [ ] 4. Make each worktree runnable (deps, ignored files, ports)
- [ ] 5. Start one Codex chat per worktree with a scoped prompt
- [ ] 6. Verify each branch independently
- [ ] 7. Integrate in a fixed order and clean up

1. Check repo state

git status --short            # uncommitted work will NOT follow a manual worktree
git worktree list             # existing checkouts and the branches they hold
git branch --show-current
git fetch origin && git log --oneline -1 origin/main

Commit or stash first when using manual worktrees. Codex-managed worktrees in the desktop app can carry uncommitted changes from the selected branch, but a clean base makes every later diff easier to read.

2. Split by file ownership

Write the split down before starting any chat:

| Task | Owns (may edit) | Must not touch |
|---|---|---|
| A: add rate limiter | src/middleware/**, tests/middleware/** | package.json, lockfile |
| B: CSV export | src/export/**, tests/export/** | src/middleware/** |
| Shared changes (deps, lockfile) | done once, after A and B merge | — |

If two tasks need the same file, either serialize them or give that file to one task.

3. Create worktrees

Pick the mechanism that matches the surface:

Surface	How
ChatGPT desktop app (Codex)	Select Worktree under the composer, choose the starting branch, submit
Codex CLI, interactive	/worktree (new chat or continue current chat in a worktree); /new and /fork may offer a worktree choice
Codex CLI, saved session	codex fork <SESSION_ID> --worktree (needs an explicit session id)
Codex CLI, headless	codex exec --worktree "<task>" on releases that list --worktree in codex exec --help
IDE extension	/worktree in the Codex composer
Any version, full control	Plain git worktree add, then run Codex inside it

Manual worktrees, one branch each:

git worktree add -b feat/rate-limit ../app-rate-limit origin/main
git worktree add -b feat/csv-export ../app-csv-export origin/main
codex -C ../app-rate-limit
codex -C ../app-csv-export        # second terminal

Codex-managed worktrees live under $CODEX_HOME/worktrees (default ~/.codex/worktrees; the desktop app lets you change the root in Settings > Worktrees). They start in detached HEAD so they do not create branches until you choose Create branch here.

4. Make each worktree runnable

A worktree contains tracked files only. Everything ignored is missing.

• Dependencies: run the install step in each worktree (npm ci, uv sync, bundle install). In the desktop app, put it in the project’s local environment setup script so it runs automatically when a worktree is created.
• Ignored config: list ignored files the build needs in .worktreeinclude at the repo root. Codex copies matching ignored files into managed worktrees it creates locally. It does not apply to worktrees you create with git worktree add.

# .worktreeinclude — ignored files to copy into Codex-managed worktrees
.env.local
config/dev-secrets.json

• Ports and state: give each worktree its own dev-server port, database name or container name, or the parallel test runs will collide.
• AGENTS.override.md that is git-ignored is copied into managed worktrees automatically; do not list it.

5. Start one chat per worktree

Give each chat the ownership table row and a definition of done:

You are working in a dedicated worktree for task A (rate limiter).
Only edit src/middleware/** and tests/middleware/**. Do not change package.json
or the lockfile; if a dependency is needed, stop and tell me.
Done = `npm test -- middleware` passes and `npm run lint` is clean.
Commit on this branch with a conventional commit message when done.

6. Verify each branch independently

Run the full check inside each worktree before integrating:

cd ../app-rate-limit && npm test && npm run lint && git diff --stat origin/main

Reject a branch that edited files outside its row; ask that chat to revert them.

7. Integrate and clean up

• Merge or open PRs in dependency order; rebase the later branch on the earlier one and rerun its tests after the rebase.
• For competing approaches, compare diffs and test results, keep one branch, delete the rest.
• Remove manual worktrees when done (ask before deleting anything with uncommitted work):

git worktree remove ../app-csv-export
git worktree prune
git branch -d feat/csv-export        # only after it is merged

Codex-managed worktrees are cleaned up automatically (by default the 15 most recent are kept; worktrees tied to pinned or running chats are kept). Codex snapshots a managed worktree before deleting it, and archiving a chat deletes its worktree.

Gotchas

• A branch can be checked out in only one worktree. fatal: 'feat/a' is already used by worktree at ... means another checkout holds it: switch that worktree to another branch, or in the desktop app use Hand off to move the chat to Local instead.
• In workspace-write, .git is read-only, including the resolved git directory of a worktree’s .git pointer file. Expect git commit inside a worktree to need approval; that is the sandbox working, not a bug.
• Handoff and worktree creation move tracked files only; anything ignored stays behind unless .worktreeinclude covers it.
• Long-lived worktrees drift. Rebase onto the latest base before final verification, not only before starting.
• Every worktree has its own node_modules, build cache and virtualenv: watch disk use when running many.
• Do not resume the same session in two terminals at once; fork it (/fork or codex fork) so each line of work has its own transcript.

Output contract

Report back in this shape:

## Parallel run summary
| Task | Worktree path | Branch | Status | Checks |
|---|---|---|---|---|
| A rate limiter | ../app-rate-limit | feat/rate-limit | ready | test, lint pass |
| B CSV export | ../app-csv-export | feat/csv-export | needs rebase on A | test pass |

Integration order: A, then B (B rebased on A).
Files touched outside ownership: none.
Cleanup pending: remove ../app-csv-export after merge (awaiting your go-ahead).