Isolate Parallel Work

Lesson 6 · Worktrees · ~11 minutes

Two agents should not edit the same checkout concurrently. Codex app worktrees give each task a separate filesystem while sharing Git history.

Local checkout → foreground work you supervise closely
Worktree       → isolated background task
Handoff        → move the thread and its changes safely

Use a Worktree When

You want Codex working while you continue locally.
The task may touch many files or install dependencies.
You want to compare alternatives without branch pollution.
An automation should not disturb unfinished work.

Git constraint

The same branch cannot be checked out in two worktrees. Use Handoff when bringing a task back to Local instead of checking out the same branch twice.

Ignored Local Files

Managed worktrees contain tracked files. If a task needs ignored setup files, explicitly list only those files in .worktreeinclude.

# .worktreeinclude
.env.local
config/dev-overrides.json

Choose the Worktree Lifecycle

Stage	Decision
Start	Select the exact base branch or current state the task needs
Setup	Provide deterministic environment actions and only required ignored files
Work	Keep one coherent task and one associated thread in the worktree
Verify	Run tests inside the worktree before moving changes
Integrate	Create a branch there or use Handoff to Local
Clean up	Archive disposable worktrees after preserving needed commits or patches

Account for Environment Drift

A separate checkout does not automatically contain installed dependencies, generated files, running services, or ignored configuration. If verification succeeds only in Local, the task is not independently reproducible yet.

Good background task

“Upgrade one dependency, update its direct callers, run the focused test suite, and report the diff” is isolated. “Refactor the module I am actively editing locally” is not.

Resolve Integration Deliberately

Before Handoff, inspect changed files, commits, test results, and dependencies on ignored state. Decide whether the result should become a branch, move to Local for further work, or be discarded.

Check Your Understanding

Codex should prototype while you continue editing locally. Which execution location fits?

Use an isolated worktree
Share the local checkout
Disable Git branch protection

Correct. Separate filesystems prevent concurrent-edit collisions.

Use an isolated worktree, then hand off the thread when it belongs in the foreground.

Do This Now

Start a harmless documentation task in a worktree. Record its base commit, inspect which ignored files are available, run one verification command, review the diff, then practice Handoff to Local without manually moving files.

Primary Source

Codex worktrees documents managed worktrees, Handoff, ignored files, and cleanup.

Questions? Describe two tasks you want to run together and I will identify whether they are genuinely independent.

← Previous Next →