BuildGist

When I switch coding agents, how do I keep the “why” and the dead ends?

Kayvan Zahiri ·

The new agent gets your code, but not the reasons behind it or the approaches that already failed, so it can try them again. Before you switch, have the outgoing agent write a short Tried and ruled out list and a one-line reason for each decision into a file in the repo, and tell the new agent to read it first. Keep it to what the next agent would otherwise repeat. With BuildGist, Continue carries the task itself into the new chat, and the file holds the dead ends.

BuildGist is a Mac app for Claude Code, Cursor and Codex. Download for Mac.

Why the reasoning gets lost

Claude Code, Codex and Cursor can all work in the same project folder, and each keeps its own chat history. A new Claude Code session begins with a fresh context window. The new agent reads the files and the diff, and the diff shows what changed. It does not show the three approaches you rejected, the test that only fails on CI, or why you picked one library over another. That lives in the old chat.

Codex can bring some of it across: /import in a local Codex CLI session imports up to 50 recent chats from Claude Code or Cursor (see switching from Cursor to Codex). A whole chat is long, though, and the few lines that matter sit somewhere inside it.

The dead ends people hit after a switch

A file that holds it

Add a section like this to the handoff file your agents already read, or to a HANDOFF.md at the project root:

## Tried and ruled out
- Caching the session in localStorage: lost in Safari private mode. Don't retry.
- Upgrading the auth library to v5: needs Node 20, prod is on 18.

## Decisions (and why)
- Tokens expire after 7 days: product asked for it; keep it.
- Kept the old /api/login route: the mobile app still calls it.

## Still open
- Test test_share_expiry fails only on CI; cause unknown.

Three rules keep it useful:

  1. One line per item, with the reason. “Didn't work” without a reason gets retried.
  2. Write it before you switch, while the old agent still has the context.
  3. Delete items once they stop mattering, so the file stays short enough to read every time.

So the file always gets read, add one line to AGENTS.md (and to CLAUDE.md if you keep one, or put @AGENTS.md at its top):

If HANDOFF.md exists, read it first. Don't retry anything under Tried and ruled out unless I ask.

Make the outgoing agent write it

Paste this into the old chat before you switch:

Before I hand this task to another agent, add to HANDOFF.md: every approach you tried
that failed or I rejected, with the reason; every decision we made, with the reason;
and anything still unresolved. One line each. Leave out what is obvious from the code.

Then start the new chat with: “Read HANDOFF.md first and tell me the next step before you edit.” Check what the old agent wrote against the chat and the diff, because it records what the agent believes it did. Add anything you remember that it left out.

Or choose Continue

When you start a new chat in another coding agent in the same project, a BuildGist card at the bottom right offers the earlier agent's task, if it was active in the last 12 hours. Choose Continue and the new chat starts with that task's context, so you don't explain the task again. Choose Start fresh and nothing is handed over.

The context is your own words: what you asked for, and constraints you typed while the task was underway. If you told the old agent “don't use localStorage,” that comes along. A dead end the agent found on its own and never wrote down is not in your words, so keep those in the file. Claude Code and Codex take the context on a new session, not a chat you are in the middle of. In Cursor the handoff is best effort: if the new chat does not show the task, paste the note.

BuildGist also explains each meaningful run in plain English, so you can read what the last agent did before the next one builds on it. The full layout (AGENTS.md, CLAUDE.md, HANDOFF.md, a branch per agent) is in how to keep context across Claude Code, Codex and Cursor.

Questions

Should the dead ends go in AGENTS.md?

Usually not. AGENTS.md is for rules that hold for every task. Dead ends belong to one task, so put them in the handoff file and clear them when the task is done. Move a decision into AGENTS.md once it applies to the whole project.

What if two agents work at the same time?

Give each its own branch or git worktree and its own handoff section, so one agent's dead ends don't get mixed into the other's task.

Sources

What you need

Codex needs you to approve BuildGist once, in Codex. BuildGist shows the steps. Setup is in Getting started.

To explain a run, your computer sends BuildGist what that run needs, and BuildGist passes it to Anthropic. BuildGist does not keep this material. It does not send your whole repository, files the run did not change, or files named like secrets, such as .env files and keys. It keeps the explanation and short cited excerpts of changed code, at most 12 lines each. Secret masking is best-effort. Privacy has the full list.

Every account gets 7 days of BuildGist Pro free, with no card. The 7 days start at your first explanation or Continue handoff. Nobody is charged when the trial ends. After that, BuildGist Pro is $12 per month, plus any applicable tax shown at checkout. See pricing.

Try BuildGist Download for Mac

Apple silicon, macOS 12 or later. United States, 18 or older.

Related

Questions: kayvanandre@gmail.com.