Diff Checkpoints

Diff Checkpoints

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

---

Two baselines

Diff 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 diff — records the most recent snapshot emitted by show_diff when advance=true (the default), so the next default diff is incremental.

Using show_diff

It accepts:

Argument	Values	Meaning
since	"last_diff" | "project_open"	Which baseline to compare against. Defaults to "last_diff".
advance	true (default) / false	Whether to record the emitted snapshot as the next incremental baseline. This changes only Codexify's private diff cursor.
include_patch	boolean	Whether to include the unified patch body.

The model-visible result is a concise text summary with aggregate counts, checkpoint status, and warnings — deliberately no structuredContent. The complete payload (bounded file records, rename sources, binary markers, warnings, and a complete unified binary patch) is attached to component-only result _meta, which ChatGPT forwards to the diff widget without adding the diff to model context. The patch is included when it fits diff.maxPatchBytes (default 4 MiB, regression-tested with 10,000 changed code lines); an oversized patch is omitted explicitly rather than returned as invalid partial hunks — metadata and stats remain available. Set diff.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. Codexify 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/codexify/diff/<project-hash>/<conversation-hash>/project-open
refs/codexify/diff/<project-hash>/<conversation-hash>/last-diff

The raw conversation identifier is never written. The refs survive MCP reconnects and Codexify 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. Existing refs/codexify/review/.../project-open and .../last-review refs are copied lazily into the diff namespace and retained for compatibility with installations that used the former review-named surface.

To inspect or remove old refs manually:

git for-each-ref refs/codexify/diff/
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_diff are serialized for the same owner/project through tool completion, so the incremental cursor can't advance over a partially completed write. A resident exec_command process may keep changing files after its initiating call returns, so every diff 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 diff card

Codexify advertises the standard MCP Apps extension and serves the current self-contained resource at ui://codexify/diff/v3/mcp-app.html. Compatible ChatGPT developer connectors render show_diff as a GitHub-style file/statistic/patch card from component-only result metadata — no separate web service or public app publication needed. Clients that ignore MCP Apps metadata receive only the concise ordinary text result. Legacy review metadata and the v3, v2, and unversioned ui://codexify/review/... resources remain readable so existing cards can remount, but current show_diff results emit the diff-named metadata. Widget disclosure state persists across remounts. Cursor advancement completes before the result is returned and never waits for widget interaction; the card updates at the show_diff tool-call boundary and is not a continuous filesystem watcher.

---

See also

• Tools Reference — show_diff, git_commit, git_push.
• Configuration — the diff block.