--- title: What is an agent receipt and what should it contain? slug: what-is-an-agent-receipt excerpt: "An agent receipt is a Markdown record of what an AI agent ran and what came back. The seven lines it should hold and how to check one fast." quickAnswer: "An agent receipt is a short Markdown file an AI coding agent writes after it runs something. It records what ran, the exact command, the result or exit code, counts with a total, any ids or hashes, what was skipped, and when it ran. A plan says what the agent will do. A handoff says where the work stands. A receipt is the proof behind both. If a line you need is missing, ask the agent to add it before you trust the result." keyTakeaways: - A receipt records what an agent ran and what came back. It is the proof a handoff points to. - A good receipt holds seven lines. They are what ran, the command, the result, counts with a total, ids, skips and a timestamp. - A count with no total is an easy gap to miss. "12 passed" tells you less than "12 of 14 passed". - Check the skipped line on purpose. A receipt that skips nothing out loud may still have skipped something. - Sashmark is a Markdown reader in development for files like these. Its features are planned for v1. publishedDate: 2026-10-20 dateModified: 2026-10-20 author: Bobby Huang cluster: A role: post status: published faq: - q: Is a receipt the same as a log file? a: No. A log is the full raw output of a run, often thousands of lines. A receipt is a short summary that points into that output. It names the command, the result and the numbers that matter, and it says where the full log lives if you need it. - q: Should the agent write a new receipt each time or update one file? a: Either works. A new file per run, named with the date and task, keeps a clean history. One file that the agent rewrites keeps things tidy but hides old results. If the agent rewrites one file, compare it with your last copy so you see what changed. - q: How do I get my agent to write receipts that pass this check? a: Put the seven lines in your project's instruction file as required headings. Claude Code reads CLAUDE.md files and Codex reads AGENTS.md files when a session starts. Write the rule there once, for example "after every command that proves the work, write a receipt with these headings", and each new session starts with it. related: - what-is-an-agent-handoff-file - review-codex-handoff-notes-checklist - how-to-review-markdown-your-ai-agents-write --- Your agent says the tests pass. You have two choices. You can take its word for it, or you can look at the record of what it ran. That record is a receipt. Below: what a receipt is for, the seven lines it should hold, and a short check you can run on one. It is part of a series on [reviewing the Markdown your AI agents write](how-to-review-markdown-your-ai-agents-write.md). The post on [agent handoff files](what-is-an-agent-handoff-file.md) defines a receipt in one line. This page fills in the rest. ## A simple definition An agent receipt is a short Markdown file that records what an agent ran and what came back. Most often the agent writes it right after a command finishes, while the output is still in front of it. A receipt answers two questions. Did this really happen, and what was the result? It does not explain the plan or argue for a choice. It just writes down the facts of a run so someone else can check them. Your project may use another name for it. The name matters less than the job. ## Receipt, plan and handoff You will often find all three in one project folder. Each one has its own job. - A **plan** says what the agent intends to do. You read 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 comes next. You read it when a session stops. - A **receipt** says what was run and what it returned. You read it when you need to trust a claim. A handoff often says "checks run: tests pass." The receipt is where that claim gets its proof. If the handoff points to a receipt, open it. If a handoff says "done" and no receipt exists, you only have the agent's summary. ## What a receipt should contain Nobody has set a format for receipts. These seven lines cover what you need to check. 1. **What ran.** A plain name for the step, such as "unit tests" or "database backup". 2. **The exact command.** The full command line, copied, not paraphrased. "Ran the tests" is not a command. `npm test` is. 3. **The result.** Pass or fail, plus the exit code if there is one. On most systems an exit code of 0 means success and anything else means something went wrong. 4. **Counts with a total.** Any number needs its denominator. "40 of 42 tests passed" is a result. "40 passed" leaves you guessing about the other two. 5. **Ids or hashes.** Whatever helps you find the exact thing later. That might be a commit id, a record id, a file hash or a log path. 6. **What was skipped.** Tests marked skip, files left out, steps not run. Say so even when the answer is "nothing". 7. **When it ran.** A timestamp with a date and time. This tells you whether the receipt matches the current state of the work. The first three lines show that something ran. The last four show how much you can trust it. > A count with no total is an easy gap to miss. When a receipt says "12 passed", ask "12 of how many?" ## A short example Here is a made-up receipt. The paths, ids and names are placeholders. > **What ran:** Unit tests for the export feature. > > **Command:** `npm test -- tests/export` > > **Result:** Failed. Exit code 1. > > **Counts:** 42 tests ran. 40 passed and 2 failed. > > **Ids:** Commit `a1b2c3d`. Full log at `logs/test-run-1020.txt`. > > **Skipped:** 1 more test was marked skip and did not run: `exports very large files`. > > **When:** 2026-10-20 14:32 local time. Notice that this receipt reports a failure. That is fine. A receipt's job is to report the result honestly, good or bad. The 40 and the 2 add up to the 42 that ran, the skipped test is named, and the receipt says where the full log is. Now picture the same run written badly: "Tests mostly pass. One skipped." There is no command, no total, no exit code, no time. You cannot check any of it. ## How to check a receipt in two minutes 1. **Match the command to the claim.** Does the command actually test what the handoff says it tested? A command for one folder does not prove the whole project. 2. **Read the result and exit code.** A "pass" with a non-zero exit code is a red flag. Ask the agent which one is right. 3. **Find the total for every count.** Put a finger on each number. If it has no "of N", note it as a missing proof line. 4. **Check the ids.** If there is a commit id, compare it with the commit you expect. In git, `git rev-parse HEAD` prints the current one. A different id means the receipt may be about other code. Also ask whether any changes were not committed yet. 5. **Read the skipped line.** If it is missing, ask. If it lists something important, decide whether that skip is acceptable. 6. **Check the time.** A receipt from before the latest change does not prove the latest change. If any step turns up a gap, send the agent one short request. For example: "Add the total test count and the exit code to the receipt." Most gaps take one line to fix. ## When a newer run replaces the receipt A receipt file is sometimes overwritten by the next run of the same task. The numbers you checked an hour ago may be gone. Check the timestamp line first. If it is newer than your last read, the receipt describes a different run. To see what the new run reported, compare the file with the version you read. In git, `git diff -- receipts/export.md` does that, where `` is the one you last checked. Without git, keep the copy you checked and run `diff` against it next time. The [review guide](how-to-review-markdown-your-ai-agents-write.md) covers both ways. ## Ask for receipts that pass You can fix weak receipts one at a time, but it is faster to fix the instructions once. Put the seven headings in the instruction file your agent reads at the start of a session. For Codex, that is `AGENTS.md`. For Claude Code, that is `CLAUDE.md`. The [Codex handoff checklist](review-codex-handoff-notes-checklist.md) shows the same idea for handoff notes. A short version you can paste: - After every command that proves the work, write a receipt. - Use these headings: What ran, Command, Result, Counts, Ids, Skipped, When. - Every count includes its total. ## 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: a Changes View that shows what changed since you last looked, so a rewritten receipt is quick to recheck, and a Frontmatter Table that shows a YAML header as key and value rows. The app itself has no AI features. See the [planned features](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands. To see what Sashmark is and follow along, visit [sashmark.com](https://www.sashmark.com/).