Worktrees and environments

Two pieces of work in one folder edit the same files. A worktree gives each one its own folder, and Codex knows how to move work between them.

A worktree is a git worktree: a second working directory for the same repository, on its own branch. Codex uses them so several chats can run in the same project without interfering with each other, and they only work in a git repository.

The three words

The handoff is the part worth knowing exists. Moving a conversation from your main checkout into a worktree is a sequence of git operations that is easy to get wrong by hand, and the tool does it for you.

When to reach for one

• A second task while the first is still running. No waiting, no collisions.
• Anything scheduled. A background task on its own worktree cannot disturb what you are doing.
• A risky change you want to be able to abandon by deleting a directory.

A worktree only starts with what git tracks. A local .env, installed dependencies and a built folder are not there, which is why a fresh worktree often cannot run your tests straight away.

For files git ignores on purpose, such as .env, list their paths or patterns in a .worktreeinclude file at the root of the repository. Codex copies ignored files that match it into each new managed worktree, and nothing else. Dependencies are a job for a setup script instead.