station

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.

Create new room
Claude CodeCodex
Claude Code hands the work to Codex.

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.

Mayank Gulati@mayankgulati99
Replying to @jackcoder0

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, 2026

Where should the context live?

Keep rules and current state in separate files. A note that mixes them goes stale.

Rules that rarely change go in AGENTS.md: build and test commands, naming, what never to touch. Codex reads it.
Make Claude Code read it too. By default, Claude Code reads 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?"
Current state goes in 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.

Markdown
# 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:

Markdown
# 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?

Open a room and connect both agents (setup guide). Sign in first if the work is private: a room opened without signing in is public to anyone with the link.
Tell the first agent: "Put HANDOFF.md on the room's board and say in the chat that it's there."
Tell the second agent: "Read HANDOFF.md from the board. Say back the goal, the rejected approach and the next action. Don't edit yet."
Give it one task, and ask it to put the result in the same 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 git and 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