When to use this / when not to use this
Use this when
- A reviewer or successor agent needs to reconstruct why a patch exists and which evidence supports it.
- The complete session record is too large for a useful handoff but must remain independently inspectable.
Do not use this when
- You require byte-for-byte re-execution of nondeterministic models or mutable external services.
- The replay can only work with hidden process memory, the original provider account, or an unversioned transcript.
Define replay as evidence reconstruction
Coding agents are nondeterministic and their surrounding tools change. Asking a model to emit the same tokens twice is rarely the useful goal. A replay should instead recover the starting repository state, the instructions in force, the material actions, the observations returned by tools, the resulting patch, and the validation that followed. Sources: OpenAI Codex agent loop, AgentReceipt replay contract.
That definition gives replay a testable boundary. A consumer can answer why a file changed, which command produced an artifact, whether a retry replaced an earlier attempt, and which checks covered the final patch. When an input cannot be recovered, the replay says unavailable rather than silently omitting it.
Replayable does not mean
- The model will generate identical text from the same prompt.
- Every shell command can safely be executed again.
- External APIs still expose the same state.
- A passing historical check proves the current checkout passes.
- A complete record is automatically a concise review surface.
Build an artifact graph, not a transcript archive
Store events as small typed nodes and place large outputs, patches, snapshots, and reports in a content-addressed artifact store. Events refer to artifacts by digest and media type. This keeps the event stream inspectable while making deduplication, redaction, and integrity verification straightforward. Sources: OCI Content Descriptor specification, in-toto Statement v1.
Relationships matter more than timestamps. A command event should point to the instruction or task it served, its output artifact, the files observed afterward, and any validation event that consumed the result. Timestamps help humans orient themselves, but parent and dependency edges explain causality without relying on clock precision.
Graph invariants
- Every referenced artifact exists and matches its recorded digest.
- Every event belongs to exactly one session and has a stable sequence number.
- Parent references never point forward or across unrelated sessions.
- Redacted artifacts retain a digest, reason, and access classification.
- Schema migrations preserve the meaning of older evidence instead of rewriting it in place.
The immutable receipt remains complete; replay and focus are deterministic projections for different consumers.
Source: AgentReceipt replay specification- 01EventsTyped, hash-linked observations
- 02ArtifactsPatches, logs, snapshots, gates
- 03ReceiptSigned graph manifest
- 04ReplayChronology + evidence references
- 05FocusRanked, verifiable next actions
Derive replay and focus views from the same evidence
A complete replay can contain hundreds of events. A coding agent taking over the work needs a smaller answer: what changed, what remains risky, which checks failed or did not run, and which files deserve inspection first. Derive that focus queue from the evidence graph rather than asking a model to summarize its own performance from memory.
Keep derivation deterministic. Rank tasks from explicit signals such as changed-file risk, failed gates, missing instruction coverage, patch-verification mismatches, and unresolved user decisions. Each task should link back to the events and artifacts that justified it so a reviewer can challenge the ranking. Sources: AgentReceipt replay and focus specification.
A useful focus item contains
- A stable identifier and machine-readable reason code.
- The affected files or repository region.
- Priority derived from named evidence, not a free-form confidence score.
- References to the patch, check, instruction, or event that created the task.
- A completion condition another agent can verify.
Test the replay contract under partial evidence
Happy-path snapshots prove very little. Test interrupted sessions, duplicate events, missing artifacts, truncated provider logs, clock skew, post-session workspace changes, and schema versions the current reader no longer emits. A replay reader should remain useful when optional evidence disappears and uncompromising when integrity evidence fails.
Use golden fixtures for canonical JSON and property tests for ordering, hash linking, and path confinement. Then test the consumer with no access to the recorder process. If replay needs hidden in-memory state or the original provider account, it is an internal debug feature rather than a portable evidence contract. Sources: JSON Schema Draft 2020-12, fast-check property-testing framework.
Acceptance tests
- The same receipt produces byte-identical replay JSON across repeated reads.
- Removing one artifact yields a precise missing-artifact error.
- Reordering two events fails chain verification.
- A redacted provider payload still leaves git and gate evidence navigable.
- An older schema either migrates deterministically or fails with a supported-version message.
Download a deliberately incomplete replay fixture
This synthetic fixture stays valid while declaring one evidence gap. It is small enough for a parser test and realistic enough to exercise ordering, artifact references, risk normalization, and verifier-task generation.
{
"schema_version": 1,
"kind": "agentreceipt.session_replay",
"verification": { "valid": true },
"summary": { "changed_file_count": 1, "final_risk": "medium" },
"gaps": [{ "code": "provider_trace_unavailable" }],
"verifier_tasks": [{ "code": "confirm_tests_for_code_changes" }]
}- Parse and reject unknown schema versions before consuming nested fields.
- Preserve timeline sequence and stable evidence references during transformation.
- Treat gaps as data: this fixture is usable even without a provider trace.
- Resolve artifact paths relative to a receipt root, never the current process directory.
Implementation examples
Concrete commands and data shapes you can adapt.
{
"schema_version": "replay/v1",
"session_id": "01J...",
"baseline": { "commit": "8b7f...", "dirty": true },
"events": [{ "sequence": 1, "ref": "events/0001.json" }],
"artifacts": [{ "sha256": "c14a...", "media_type": "text/x-diff" }],
"coverage": { "git": "complete", "provider": "partial" },
"unavailable": ["provider.raw_prompt"]
}agentreceipt focus --session <id> --json | jq '.tasks[] | {priority, reason, files}'
agentreceipt replay --session <id> --event 42 --jsonDecision log
The choices that shape the design—and what each choice costs.
- Define replay as reconstruction, not re-execution
It remains meaningful across nondeterministic models and changing external services.
Tradeoff: The word replay needs explicit documentation because some users expect commands to run again. - Keep evidence complete and views derived
Different consumers can obtain a timeline, a focus queue, or a report without creating competing sources of truth.
Tradeoff: Readers must understand schema versions for both the receipt and each projection. - Make missing evidence first-class
Availability and capture confidence are facts that downstream automation needs to reason about.
Tradeoff: Consumers cannot treat every field as present and must implement explicit degraded paths.
Failure cases
What breaks, how it presents, and the recovery boundary.
- Replay becomes a transcript dump
- Signal
Reviewers must read thousands of tokens before finding the patch or failed gate.
- Response
Keep the complete graph but derive an indexed chronology and evidence-backed focus queue.
- Artifact references escape the receipt
- Signal
A relative path resolves through a symlink or parent segment to an arbitrary local file.
- Response
Resolve inside a fixed receipt root, reject traversal and symlink escapes, then verify the digest.
- A schema upgrade rewrites history
- Signal
Opening an old receipt mutates its signed bytes or replaces unknown fields.
- Response
Leave the receipt immutable and emit a separately versioned derived view or migration artifact.
Repositories and primary references
Read the implementation, specifications, and tool documentation behind the article.
- AgentReceipt replay specificationThe replay, focus, reviewability, and unavailable-evidence contracts.
- AgentReceipt sourceGo implementation of session capture and deterministic replay surfaces.
- GitHub PR workflow designHow local receipts can connect to pull-request review without becoming the policy authority.
Related projects
Inspect the systems that ground this guide in implementation work.
- Go · CLI · AI ToolingAgentReceiptLocal-first Go CLI for recording AI coding sessions and producing verifier-ready replay evidence.
- TypeScript · CLI · AI WorkflowsRitualAITypeScript CLI that scans local Claude/Codex prompt history and turns repeated workflows into reusable skills.
- TypeScript · CLI · AI ToolingSkills DoctorTypeScript CLI for auditing Claude/Codex Agent Skills for quality, structure, scoring, and repair readiness.
Last updated: