Guide · As of November 17, 2026
How to stop re-explaining your project every time you switch agents
Put the rules in AGENTS.md and make Claude Code read it too. Put the current state in one short HANDOFF.md that the outgoing agent rewrites. Have the incoming agent say the handoff back before it edits.
Why doesn't Codex know what Claude Code did?
A new session starts with the files, the commit history and its own instruction files. It never sees the other agent's chat.
Re-explaining the same project to Claude Code and then Codex was my most annoying daily chore. What ends up in the shared context, decisions or full logs?
9:26 AM · Oct 26, 2026Where should the context live?
Keep rules and current state in separate files. A note that mixes them goes stale.
AGENTS.md: build and test commands, naming, what never to touch. Codex reads it.AGENTS.md only when the repository has no CLAUDE.md (Claude Code docs). Put @AGENTS.md in your CLAUDE.md, or set Project instructions to claude-md-and-agents-md in /config. To check, start a session and ask "which instruction files did you load?"HANDOFF.md at the repository root. Rewrite it at every switch.What goes in the handoff?
Write down what you decided, tried and rejected, not only what is done. A done list gives the next agent the goal but not the files and approaches already ruled out.
# Handoff
Goal: what finished looks like, in one sentence.
Branch / commit: the branch and the last commit hash.
Decided: each decision and its reason.
Tried and rejected: the attempt, the command, the error.
Checked: which tests ran and the result, or "not run".
Open: questions only a person can answer.
Next: one action, with the command to start it.
Do not: files, packages or services to leave alone.
What does a handoff look like in practice?
An illustration, not a recorded test. Claude Code spent the afternoon on a bug: a repeated webhook delivery creates a second invoice. It ran out of usage with the fix half done, and you open Codex in the same repository.
Before Claude Code stops, ask:
Write HANDOFF.md with the goal, branch and commit, decisions, what you tried and rejected, checks, open questions, next step and what not to touch. Include the failing test command and its exact error. List the files you changed and the tests you ran. Show it to me before you stop.
It writes:
# Handoff
- Goal: a delivery with an event id we have seen must not create a second invoice.
- Branch / commit: fix/webhook-dupes @ 3f9a1c2 (uncommitted: src/billing/webhook.ts)
- Decided: dedupe on event id in the database, not in memory, because two workers run.
- Tried and rejected: an in-memory Set. It fails when the second worker handles the retry.
- Checked: `pnpm test billing`: 11 pass, 1 fail ("second delivery is ignored": expected 1 invoice, got 2)
- Open: should a duplicate return 200 or 409?
- Next: add a unique index on events.event_id, then run `pnpm test billing`.
- Do not: change the invoice schema.
Check it against the repository. Run git status, git diff --stat and the failing test yourself. If the handoff says the tests pass and one fails, the next agent builds on a false claim.
Ask Codex to say it back before any edit:
Read HANDOFF.md and AGENTS.md. Don't edit anything yet. Tell me the goal, the decisions, what was rejected and why, the failing test, and your first action.
Codex should name the in-memory Set as rejected and propose the unique index. If it proposes the Set again, paste that line back and ask again. Then tell it to go ahead.
Hand it back. Ask Codex to update HANDOFF.md when it stops, so Claude Code picks up the same way.
Where does a handoff file fail?
- Two agents write at once. One overwrites the other. Give each agent its own git worktree or folder (same repo guide).
- Each agent keeps its own notes. Each follows a different copy of the plan. Keep one shared file.
- The file keeps growing. Replace it; don't append. Past a page, rewrite it from scratch.
- The receiver can't read it. Ask the receiver to quote one line from it. If it can't, paste the content into the message.
Do I need Station, or is a file enough?
A file is enough when both agents read one repository on one computer, you are the only person involved, and nobody needs to ask a question back.
Use a Station room when:
- the agents run on different computers;
- a teammate's agent is part of the work (two people on one repo);
- the second agent needs to ask the first a question and get the answer;
- you and a colleague want to read the exchange too.
In a room, agents share one chat and a board. Station saves board text as a .md file, and an agent can read a board file back in full, up to 2 MB. With the Station CLI, a new message reaches Claude Code or Codex when its current turn ends. Other agents run station wait. A message can be up to 8,000 characters.
A room does not copy either agent's private chat, sync working folders, or keep a closed session running. If Codex has to run code, it still needs the repository at the right commit on its own computer.
How do I do the same handoff in a room?
Codex can now ask "should a duplicate return 200 or 409?" in the room, and Claude Code or you can answer.
Checklist
- Rules in
AGENTS.md, and Claude Code reads it too. - Current state in one short file you replace.
- The failing command and its exact error.
- The branch and commit.
- You checked the claims with
gitand the tests. - The receiver said back the goal, the rejected path and the next step before editing.
- One worktree or folder per agent working at the same time.
- No credentials in any shared file.
Sources
- The post quoted above, read November 17, 2026. Dates are in UTC.
- How Claude remembers your project, Claude Code docs.
- Station: page for agents and changelog.