Where to keep the plan when your agents work in worktrees
Plan files in the repo get one copy per worktree, and the copies drift apart. Keep the plan outside the repo, in one place every session reads and writes.
25 October 2026 · Rahmakyan
Keep the plan outside the repo, in one place that every agent session reads and writes, whichever worktree or branch it runs in. A plan file inside the repo is copied into every worktree, and from the first edit each agent works from its own version.
We build Hamloy, and we run Claude Code and Codex in worktrees on it every day. This post is about the files that pile up around agent work, why they drift, and the options for one plan that doesn't.
Worktrees fix the files, not the plan
A worktree gives each agent its own folder and branch, so two agents can't overwrite each other's code. That is the right first step for running agents in parallel:
git worktree add ../app-claude -b feat-search
git worktree add ../app-codex -b feat-export
But everything in the repo is copied with it, including the plan. Say you keep PLAN.md, TODO.md or a plans/ folder with a design, a review and a task list per feature. Each worktree now has its own copy. Claude ticks a task in ../app-claude/TODO.md, Codex adds two in ../app-codex/TODO.md, and neither sees the other's change until both branches are merged. Then the plan is a merge conflict.
Three ways plan files go wrong
- They fork. One copy per worktree, each edited on its own branch. The longer the branches live, the further apart the copies are.
- They multiply. A plan, a review of the plan, a review of the review, then tasks, tests and notes for each. Agents write files readily, and nobody reads the fifth one.
- They end with the branch. What an agent tried and ruled out sits in a file on a branch. Delete the branch unmerged and it's gone; merge it and it's buried in history.
Where the plan can live instead
| Where | Every worktree sees the same plan | Agents can say they're on a task | You see it without opening a terminal |
|---|---|---|---|
| A file in the repo | No, one copy per worktree | Only by editing the file | No |
A folder outside the repo, like ~/plans/app |
Yes, on that one computer | Only by editing the file | No |
| GitHub Issues | Yes | Assignees | Yes |
| A shared list the agents keep (Hamloy) | Yes, on every computer | Yes, a claim | Yes |
A folder outside the repo is the free fix and works well alone on one computer. Point every agent at it in CLAUDE.md and AGENTS.md. Two agents can still edit the same file at the same moment, and nothing tells one that the other took a task.
GitHub Issues keeps the plan out of the branches and is reachable with gh or its MCP server. Each task is an issue, which is heavy for the small steps agents make, and an issue says nothing about which session is on it right now.
A shared list is what we built Hamloy for. Every session reads and writes the same plan through its tools, whichever worktree, branch or computer it runs in. Each one claims the task it takes, notes what it tried and ruled out on the task itself, and ticks it when it's done. Hamloy follows the work through git, so a task done on a branch says "not merged yet" until it reaches main.
What to keep in the repo
The repo is still the right place for what belongs to the code: the design of a feature that lands with it, docs, and the rules for your agents (CLAUDE.md, AGENTS.md). What moves out is the part that changes every hour: who is on what, what's left, what was ruled out, and what waits on you.
That part is the plan. Keep one copy of it, outside the branches, and every worktree works from the same one.