--- title: What is an agent handoff file? slug: what-is-an-agent-handoff-file excerpt: "An agent handoff file is a Markdown file an AI agent writes so the next session can pick up the work. What one holds and how to read it fast." quickAnswer: An agent handoff file is a Markdown file that an AI coding agent writes at the end of a piece of work. It tells the next reader, human or agent, where things stand. A useful one names the goal, what was done, what changed, what is still open, and the next step. It often starts with a short YAML header that holds a status, a date and an owner. keyTakeaways: - A handoff file is a status report in Markdown, written by an agent for whoever picks up the work next. - The useful parts are the goal, what was done, files changed, open questions and the next step. - A YAML header with status, date and owner lets you judge the file before you read the body. - Read the open questions and next step first. That is where the agent needs something from you. - Handoffs get rewritten, so review what changed since your last read instead of starting over. publishedDate: 2026-10-05 dateModified: 2026-10-05 author: Bobby Huang cluster: A role: post status: published faq: - q: Is there a standard format for agent handoff files? a: Not one that every tool follows. Most handoffs share the same parts, though. You can ask your agent to use a fixed set of headings so every handoff reads the same way. - q: What is the difference between a handoff and a plan? a: A plan says what the agent intends to do. A handoff says what happened and what is left. You review a plan before work starts and a handoff after it stops. - q: Where should handoff files live? a: Somewhere both you and the agent can find them every time. Many people use one folder per project and name each file with the date and topic. related: - how-to-review-markdown-your-ai-agents-write - read-a-claude-code-plan-file-without-an-ide - review-codex-handoff-notes-checklist --- If you work with AI coding agents for more than one session, you start to see handoff files. An agent finishes a stretch of work and writes down where things stand. The next session reads it and carries on. So do you. This page explains what a handoff file is, what a good one holds, and how to read one quickly. It is part of a series on [reviewing the Markdown your AI agents write](how-to-review-markdown-your-ai-agents-write.md). ## A simple definition A handoff file is a Markdown file that passes work from one session to the next. It is often named `HANDOFF.md`. The writer is usually an agent. The reader can be you, another agent, or the same agent in a fresh session with no memory of the last one. That last case is why handoffs matter. A new agent session starts without the context of the old one. The handoff file is the context. ## What a handoff file usually holds There is no single standard. Still, useful handoffs tend to carry the same parts: - **Goal.** One or two lines on what the work is for. - **Status.** Done, in progress, blocked, or waiting on someone. - **What was done.** A short list, not a story. - **What changed.** File paths, settings, or records the agent touched. - **Open questions.** Things the agent could not decide alone. - **Next step.** The single next action, and who owns it. - **Checks run.** Tests, builds or commands the agent ran, with their results. Here is a short, made-up example. The paths are placeholders. > **Goal:** Add a dark theme to the settings page. > > **Status:** In progress. > > **What changed:** `src/settings/theme.css`, `src/settings/page.tsx` > > **Checks run:** Unit tests pass (42 of 42). > > **Open question:** Should the theme follow the system setting by default? > > **Next step:** Jane Doe answers the open question; then the agent wires the toggle. If a handoff is missing the open questions or the next step, ask the agent to add them. Those two parts save the most time. ## The header at the top Many handoffs start with a YAML front matter block. It sits between two `---` lines at the top of the file. A typical one holds a few fields: - `status: blocked` - `date: 2026-10-05` - `owner: Jane Doe` - `next: review the migration step` Read this first. In a few seconds you know whether the file needs you now. A raw YAML block can be hard to scan, though, especially when it grows to a dozen fields. The same fields read faster as a small table of keys and values. ## How to read a handoff in two minutes 1. **Header.** Check the status and the date. A stale date may mean a newer handoff exists. 2. **Open questions.** Answer them or note that you cannot yet. 3. **Next step.** Confirm you agree with it before the agent starts. 4. **What changed.** Skim the file list. Anything surprising deserves a closer look. 5. **Checks run.** A handoff that says "done" with no checks listed is a claim, not a result. You can skip the "what was done" list on a first pass. Come back to it if something in the steps above looks off. If the handoff came from Codex, [this checklist for Codex handoff notes](review-codex-handoff-notes-checklist.md) turns these five checks into a short pass you can repeat. ## When the handoff gets rewritten Agents often update a handoff instead of writing a new one. That keeps one file per topic, which is good. It also means you may be reading a file that changed since you last looked. Rather than re-read it top to bottom, look only at what changed. If the file is in git, `git diff` on that file works. If not, keep a copy from your last read and compare it with `diff`. The guide on [reviewing agent Markdown](how-to-review-markdown-your-ai-agents-write.md) walks through both. > Ask your agent to keep the same headings in every handoff. Changes are much easier to spot when the shape of the file stays put. ## Handoffs, plans and receipts These three files often sit side by side: - A **plan** says what the agent intends to do. You review it before work starts. See [how to read a Claude Code plan file](read-a-claude-code-plan-file-without-an-ide.md). - A **handoff** says where the work stands and what is next. - A **receipt** records what was run and what came back, such as test results or ids. Same format, different jobs. Knowing which one you are reading tells you what to look for. ## Where Sashmark fits Sashmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released. Planned for v1: Live Reload that keeps your place when an agent rewrites a file, a Changes View that shows what changed since you last looked, and a Frontmatter Table that shows the YAML header as key and value rows. The app itself has no AI features. To see what Sashmark is and follow along, visit [sashmark.com](https://www.sashmark.com/).