Reviewing Codex handoff notes: a checklist

Codex can work for a long stretch and then stop. When it does, you want to know three things fast: is it done, can you trust that, and what happens next. A handoff note answers all three, if you read it the right way.

This checklist is for reviewing a handoff note that Codex wrote. It is part of a series on reviewing the Markdown your AI agents write. If you are new to the idea, start with what an agent handoff file is.

First, find the note

The Codex CLI docs describe saved sessions that you can reopen with codex resume, and instruction files named AGENTS.md that Codex reads when a session starts. They do not name a standard handoff file (checked October 2026). So a handoff note lives wherever you, or your project's instructions, told Codex to put it.

Common choices:

• A HANDOFF.md at the project root, rewritten at the end of each task.
• A handoffs/ folder with one file per task, named with the date and topic.

If Codex does not tell you the path, ask: "What is the absolute path of the handoff note you just wrote? Confirm that it exists." Open that exact file.

The checklist

Work through these in order. The first four tell you whether the note needs you right now. The last four tell you whether to trust it.

1. Date and status

If the note starts with a YAML header between --- lines, read it first. Check the status (done, in progress, blocked) and the date. A date older than the work you remember may mean you are reading the wrong file, or a newer note exists.

2. Goal

Does the goal match what you asked for? Agents sometimes restate a task in a narrower or wider way than you meant. If the goal is wrong, the rest of the note is about the wrong work. Stop and correct it.

3. Open questions

These are the things Codex could not decide alone. Answer each one, or write down that you cannot yet. An open question you skip tends to come back as a step you have to undo.

4. Next step

There should be one clear next action and an owner. "Continue the work" is not a next step. "Jane Doe approves the schema change, then Codex runs the migration" is.

5. Checks run

This is the line that matters most. Look for the commands Codex ran to prove the work, such as tests, a build or a linter, and what each one returned.

A note that says "done" with no checks listed is a claim, not a result. Ask Codex which commands it ran and what they printed.

Watch for checks that were planned but not run, and for a pass count with no total. "Tests pass" tells you less than "42 of 42 tests pass".

6. Files changed

The note should list the files it touched. Compare that list with what really changed:

• In a git project, before the session, note the commit you started from (git rev-parse HEAD) and save the output of git status --short, so you can tell your own earlier changes from the agent's. Afterwards, git diff <that-commit> --stat lists every tracked file that changed, committed or not. git status --short adds new files git does not track yet.
• Without git, compare against your own copy from before the session.

A file that changed but is not in the note is worth a question. So is a file in the note that did not change.

7. Anything deleted, overwritten or reset

Search the note for words like delete, remove, overwrite, reset, drop and migrate. Each one needs a reason and a way back. If the note is silent and the diff shows a deleted file, ask before you start the next session.

8. What it skipped

Good notes say what was left out on purpose, such as a test that was skipped or an edge case left for later. If the note has no "skipped" or "not done" part, ask. Silence here does not mean nothing was skipped.

A short example

Here is a made-up note that passes the checklist. The paths and names are placeholders.

Status: Done, 2026-10-06.

Goal: Add CSV export to the reports page.

Open questions: None.

Next step: Jane Doe reviews the pull request.

Checks run: npm test: 42 of 42 passed. npm run build: passed.

Files changed: src/reports/export.ts, src/reports/page.tsx, tests/export.test.ts

Deleted: Nothing.

Skipped: Excel export. Left for a later task.

Every line gives you something to check.

Ask for notes that pass

You do not have to fix weak notes one at a time. Codex reads AGENTS.md files when a session starts: one in your Codex home folder (~/.codex by default) and any along the path from the project root to the folder you are working in (per the Codex AGENTS.md docs, checked October 2026). Put the headings you want there once.

For example, a project AGENTS.md could say:

• End every task with a handoff note at HANDOFF.md.
• Use these headings: Status, Goal, Open questions, Next step, Checks run, Files changed, Deleted, Skipped.
• Under Checks run, list each command and its result.

When every note has the same shape, you know where to look, and gaps stand out.

When the note gets rewritten

If Codex rewrites the same HANDOFF.md at the end of each task, you only need to read what changed. The simplest way: when you finish reading, save a copy, such as cp HANDOFF.md HANDOFF.read.md. After the rewrite, run diff HANDOFF.read.md HANDOFF.md. If the note is in git, git diff <commit> -- HANDOFF.md compares it with the version at the commit you last read. The review guide covers both ways, and the same habit works for Claude Code plan files.

Where Skimmark fits

Skimmark 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 updates the page when an agent rewrites the note, and keeps your Reading Position.
• A Changes View that shows what changed since you last marked the file as seen, with no git needed.
• A Frontmatter Table that shows the YAML header as key and value rows.

The app itself has no AI features. Codex writes the note. Skimmark is planned as the place you read it.

See what Skimmark is and follow along at skimmark.com.