BuildGist vs CLAUDE.md, AGENTS.md and HANDOFF.md

Kayvan Zahiri · October 16, 2026

CLAUDE.md, AGENTS.md and a HANDOFF.md note are files you write and your coding agents read. BuildGist is a Mac app that writes a plain-English explanation after each meaningful run and, when you switch agents, offers to carry the task into the new chat. The files are free, work everywhere, and are the right place for standing rules. BuildGist is for what changes every run: what the run did, and the task in progress.

What each one is

CLAUDE.md is instructions Claude Code reads at the start of every session. Claude Code's memory documentation, read on October 16, 2026, puts the project file at ./CLAUDE.md or ./.claude/CLAUDE.md, shared through version control, and suggests keeping each file under 200 lines. /init writes a first version.
AGENTS.md is the same idea in a file several agents read. Codex's documentation says Codex reads AGENTS.md before doing any work. Cursor's rules documentation calls it a plain markdown alternative to .cursor/rules. Claude Code reads AGENTS.md when the project has no CLAUDE.md, and a CLAUDE.md can pull it in with a line that says @AGENTS.md.
HANDOFF.md is not a standard. It is a note people write for the next session: the goal, what is done, what failed, and the next step. Community skills put it in different places. An agent reads it when you tell it to, usually with one line in CLAUDE.md or AGENTS.md.
BuildGist works with Claude Code, Cursor and Codex. It explains each meaningful run in plain English, flags concerns, and carries the task over when you switch agents.

What the files do well

They are free, plain text, and in your repository. Anyone on the team can read them, review a change to them, and roll it back. They need no account and nothing running beside the agent. For standing facts, such as the build command, the test command, naming rules and "never edit the generated folder", a file is the right tool. BuildGist does not replace it, and it does not read or change CLAUDE.md or AGENTS.md.

If you use one agent, on one task, over a few sessions, a rules file and a handoff note you keep honest may be all you need. That costs nothing.

Where the files fall short

A rules file says how to work in the project, not what the last run did. Writing each run into it is how it grows past the size the documentation suggests.
A handoff note is as current as the last time you wrote it. You have to remember to write it at the moment you switch, and to delete it when the task is done, or the next task starts from an old one.
A note says what you meant, not what the code did. Check it against git status and git diff --stat before you trust it.
None of them reads the diff for you. If a run left a risky change, such as a delete path that does not check who owns the record, the file does not mention it.

What BuildGist does instead

After each meaningful run, BuildGist puts an explanation in your Inbox: what changed, what it means and what to check, with concerns flagged. It works from uncommitted work. Small changes stay quiet. It is written by AI, so check important behavior against the code and tests.

When you start a new chat in another coding agent in the same project, a BuildGist card offers the earlier agent's task. Choose Continue and the new chat starts with that task's context: your own words about the task and the constraints you typed, and, when the last run's files are still as it left them, how many files it changed, whether a test failed and up to three paths. Choose Start fresh and nothing is handed over. By default the card offers a task active in the last 12 hours. Cursor's handling of the context is best effort, so keep the note habit for long breaks.

Which to use

One agent: CLAUDE.md or AGENTS.md for the rules, and a handoff note when a session is about to end.
Several agents in one repository: put the rules in AGENTS.md so Codex and Cursor read the same file, and import it from CLAUDE.md if you keep one.
You switch agents often, or you want a readable account of each run without reading every diff: that is what BuildGist is for. Keep the rules file either way.

The handoff note, with what to put in it, is in how to keep context across Claude Code, Cursor and Codex. Reading the diff yourself, and when that is enough, is in BuildGist or the git diff. Making Claude Code and Cursor read the same rules is in how to keep context when you switch from Claude Code to Cursor.

What you need

A Mac with Apple silicon and macOS 12 or later.
Claude Code, Cursor or Codex.
A Git project. No commit, push, remote or GitHub repository is needed.
A GitHub account, to sign in. BuildGist does not access your GitHub repositories.

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

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

Questions: kayvanandre@gmail.com.