BuildGist

What should a handoff note say before I start a fresh Claude Code session?

Kayvan Zahiri ·

Five things: the goal, what is done, where you got stuck, what you ruled out and why, and the very next step. A fresh Claude Code session starts with a new context window. It can read the files and the diff, and the diff shows what changed. It does not show why, or which attempts already failed. Put those five lines in a short file in the repo and have the new session read it first.

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

Why a fresh session needs a note

Each Claude Code session begins with a fresh context window. What carries across is what is on disk: CLAUDE.md (or AGENTS.md when the project has no CLAUDE.md), auto memory, and the project files. What you only said in the old chat does not come along: the error you pasted, the approach you rejected, the reason behind a choice. A new session that reads only the diff can try a rejected approach again or redo a piece that already works.

Starting fresh is often the right call. Claude Code's cost guide suggests /clear when you move to unrelated work, because stale context is sent again with every message. A long session is also compacted near its limit, and the summary can drop details (see Claude Code lost context after compacting). The note is what makes a fresh start cheap.

The five lines

Goal: Google sign-in on the notes app; only a note's owner can delete it.
Done: sign-in works locally; callback route added (see the diff).
Stuck on: the delete check passes locally, fails on CI.
Ruled out: keeping the session in localStorage (lost in Safari private mode).
Next: compare the CI environment variables with .env.example.

Keep it short enough that the new session reads every line.

Have the old session write it

Before you close the old chat, paste this:

Write HANDOFF.md at the project root with five lines: goal, done, stuck on,
ruled out (with the reason for each), next step. Skip anything obvious from the code.

Then check what it wrote against the chat and the diff, because it records what the agent believes it did. Add anything you remember that it left out, especially attempts that failed.

Start the new session with /clear, or run claude again in the folder, and open with: “Read HANDOFF.md first and tell me the next step before you edit anything.” Running /rename before /clear gives the old session a name, so /resume can find it if you need it again.

Make every new session read it

CLAUDE.md is loaded at the start of every session, and it can import other files with @path syntax. While the task is open, add this line to it:

@HANDOFF.md

The imported file then loads with CLAUDE.md in each new session. Remove the line, or the file, when the task is done, so a finished task's note does not steer the next one. If your project uses AGENTS.md, which Codex and Cursor also read, a plain sentence there works too: “If HANDOFF.md exists, read it first.”

Fresh session or resume?

If the old session was on track and you only stepped away, claude --continue reopens the most recent conversation in the folder, and claude --resume lets you pick one. Resuming keeps the whole conversation, including the parts that confused it. Resume when the session was going well; start fresh with the note when it had drifted. Where the old transcripts live is in Claude Code session history.

The same note works in another agent

The note is a plain file in the repo, so Cursor or Codex can read it as well. If you are moving the task to another agent rather than to a fresh Claude Code session, the longer version, with a Tried and ruled out list and decisions with their reasons, is in keep the dead ends when you switch agents.

Where BuildGist fits

BuildGist explains each meaningful run in plain English in its Inbox, uncommitted work included: what the agent changed and what to check. It records the request you typed, the files changed with line counts, and the tests that ran with their result. So your note can spend its lines on the why. When you start a new chat in another coding agent in the same project, a BuildGist card offers the earlier task, and Continue carries your own words about it into the new chat. The explanation is written by AI, so check it against the code.

Questions

How long should a handoff note be?

One or two lines for each of the five items. If it grows past a screen, cut what the code or the diff already shows and keep the reasons and the dead ends.

Should the handoff note go in CLAUDE.md?

Not the note itself. CLAUDE.md holds rules for every session, and a handoff note belongs to one task. Import it with @HANDOFF.md while the task is open, then remove the import.

Can't the new session just read the old transcript?

It can, but a whole transcript takes up the new session's context and buries the few lines that matter. Five lines with the reasons are smaller and easier to follow.

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.