Review Checkpoints

Review Checkpoints

show_changes lets ChatGPT show you exactly what it touched — either the full task diff or only the changes since the last review. On compatible ChatGPT connectors it renders as an interactive review card.

---

Two baselines

Review state is initialized immediately before the first project-scoped tool call for a conversation — capturing the checkout as the agent first sees it, before any write, formatter, generator, or shell command can change it. Two baselines are maintained:

• project open — immutable; shows the complete task diff.
• last review — advances only when show_changes is called with advance=true (the default), so the next review is incremental.

Using show_changes

It accepts:

Argument	Values	Meaning
since	"last_review" | "project_open"	Which baseline to compare against.
advance	true (default) / false	Whether to move the last_review baseline forward. Use false for a read-only inspection.
include_patch	boolean	Whether to include the unified patch body.

The result contains a concise text summary, structured aggregate counts, bounded file records, rename sources, binary markers, warnings, and a complete unified binary patch when it fits review.maxPatchBytes (default 512 KiB). An oversized patch is omitted explicitly rather than returned as invalid partial hunks — metadata and stats remain available. Set review.maxPatchBytes to 0 to disable patch bodies entirely.

What it does — and doesn't — touch

Snapshots use Git objects but do not touch the real index or working tree. Codex Free builds a private temporary index containing only the logical project root, then carries the same literal pathspec through every comparison. If the selected project is packages/app inside a monorepo, sibling changes under packages/other cannot enter its checkpoint or diff. Paths returned to the model and UI are relative to the selected project, not the repository root.

Where checkpoints are stored

With ChatGPT's stable conversation identifier, each conversation/project scope stores exactly two namespaced refs:

refs/codex-free/review/<project-hash>/<conversation-hash>/project-open
refs/codex-free/review/<project-hash>/<conversation-hash>/last-review

The raw conversation identifier is never written. The refs survive MCP reconnects and Codex Free restarts. Generic MCP clients get transport-local in-memory checkpoints instead. Each conversation/project pair keeps only its current two snapshots; superseded synthetic commits are ordinary Git-GC candidates.

To inspect or remove old refs manually:

git for-each-ref refs/codex-free/review/
git update-ref -d <ref>

Removing both refs resets that owner to the current scoped state on its next project call.

Serialization and timing

Mutating tool calls and show_changes are serialized for the same owner/project through tool completion, so a review can't advance over a partially completed write. A resident exec_command process may keep changing files after its initiating call returns, so every review is a point-in-time snapshot. Non-Git projects remain usable; inside a Git worktree, a snapshot failure blocks mutating tools rather than silently losing the baseline.

The review card

Codex Free advertises the standard MCP Apps extension and serves a self-contained resource at ui://codex-free/review/mcp-app.html. Compatible ChatGPT developer connectors render show_changes as a file/statistic/patch card — no separate web service or public app publication needed. Clients that ignore MCP Apps metadata still get the same ordinary MCP result. The card updates at the show_changes tool-call boundary; it is not a continuous filesystem watcher.

---

See also

• Tools Reference — show_changes, git_commit, git_push.
• Configuration — the review block.