One agent. One branch. One worktree.
If two Codex chats share the same repo folder, they share the same checked-out branch. Git worktrees give each agent its own physical folder, so one agent can switch, stage, commit, and merge without yanking the floor out from under another chat.
Why the other chat moved when one agent switched branches
A normal repo folder has one current branch
In a standard checkout, .git/HEAD points at the current branch. Every terminal,
editor, and agent using that same folder sees the same branch pointer.
Chats are not Git isolation boundaries
Codex can have separate conversations, but if both conversations run commands in the same path, they are operating on the same working tree, index, and checked-out branch.
git switch is folder-wide
When one agent runs git switch codex/foo, it changes the branch for that folder.
The other agent is not notified in a meaningful way. It just wakes up in a different branch.
Worktrees create separate checkouts
A worktree is another real folder linked to the same Git repository history. Each worktree has its own current branch and working files.
The worktree pattern
Start from the canonical repo
Keep one main checkout as your source of truth. Do not park multiple agents inside it.
cd "/Users/jonathanedwards/WORKSPACE/PROJECTS/tiny-internet-factory"
git status -sb
git fetch --pruneCreate one worktree per agent or task
The worktree folder name should say the job. The branch name should say the job too.
cd "/Users/jonathanedwards/WORKSPACE/PROJECTS"
git -C tiny-internet-factory worktree add tiny-internet-factory-audio codex/audio-widget
git -C tiny-internet-factory worktree add tiny-internet-factory-copy codex/copy-polish
git -C tiny-internet-factory worktree add tiny-internet-factory-ui codex/dashboard-dustingOpen each agent in its assigned folder
Give the path explicitly. The path is the boundary. The chat is not the boundary.
Agent A cwd:
/Users/jonathanedwards/WORKSPACE/PROJECTS/tiny-internet-factory-audio
Agent B cwd:
/Users/jonathanedwards/WORKSPACE/PROJECTS/tiny-internet-factory-copy
Agent C cwd:
/Users/jonathanedwards/WORKSPACE/PROJECTS/tiny-internet-factory-uiTell the agent the boundary in plain language
Make the first instruction boring and absolute. It prevents expensive branch confusion.
Work only in this folder:
/Users/jonathanedwards/WORKSPACE/PROJECTS/tiny-internet-factory-audio
Do not switch branches in the main repo. Do not edit sibling worktrees.
Before staging or committing, run git status --short and stage only files for this task.Have an agent install this for you
Paste this into Codex, Claude, or whatever assistant is sitting in the repo. It asks the agent to wire the habit into the project instructions without flattening the rest of the file.
Please add a short, durable worktree policy to this repo's agent instructions.
Goal:
Make it safe for multiple AI agents or assistant chats to work on this repo in parallel without sharing the same checkout, branch, index, or working files.
What to do:
1. Inspect the repo root for existing instruction files, especially `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, or project docs that clearly serve the same purpose.
2. Prefer updating the existing primary instruction file. If none exists, create `AGENTS.md` at the repo root.
3. Preserve all existing project-specific guidance. Do not rewrite the whole file.
4. Add or update a section titled `## Parallel Agent Worktrees`.
5. Include the operating rules, the assignment template shape, cleanup habit, and the common failure cases so future agents do not need this page open.
6. Keep the section concise and practical. Use language like this:
```md
## Parallel Agent Worktrees
When multiple AI agents or assistant chats work on this repo, do not put them in the same checkout.
### Setup pattern
- Treat the main repo checkout as the canonical repo for pulling, inspection, and creating worktrees.
- Create one Git worktree per active agent, task, or PR-sized workstream.
- Give each worktree a descriptive folder name and a matching branch name.
- Start every agent task by naming the exact absolute worktree path it owns.
- The assigned worktree path is the boundary. The chat is not the boundary.
### Agent assignment template
Start each parallel-agent task with:
Repository worktree:
/ABSOLUTE/PATH/TO/PROJECT-WORKTREE
Branch:
codex/SHORT-TASK-NAME
Task:
DESCRIBE THE EXACT WORK.
### Rules
- Do not switch branches in the canonical repo while another agent may be working.
- Do not edit sibling worktrees unless explicitly asked.
- Before staging or committing, run `git status --short` and stage only files that belong to the current task.
- If main or another branch changed underneath the worktree, pause before merging/rebasing unless the task explicitly says to finish the PR end to end.
- After a branch is merged and the worktree is clean, remove the finished worktree with `git worktree remove ../WORKTREE-FOLDER`.
### Quick checks
- If another chat suddenly changed branches, both chats were probably in the same working directory.
- If `git worktree add` says a branch is already checked out, create a new branch name or remove the old clean worktree.
- If cleanup fails, inspect `git status --short` and preserve uncommitted work.
```
Verification:
- Show which file you changed.
- Confirm the repo now contains exactly one `Parallel Agent Worktrees` section.
- Confirm you preserved the existing instructions around it.What good looks like
The repo has a durable rule
The instruction file contains one clear Parallel Agent Worktrees section that future agents can follow.
Each agent gets a folder
Every parallel task starts with an absolute worktree path, a branch name, and a narrow task boundary.
Cleanup is part of done
Finished branches are merged from a clean state, then their extra worktree folders are removed.