ShipReceipt

A receipt for every “done.” ShipReceipt turns a delivery claim into fresh, machine-checkable local evidence: the claim, safe deterministic probes, captured output, exit codes, relevant file hashes, and a portable report.

Tests tell you what ran. ShipReceipt tells a reviewer which exact completion claim those tests support—and when later changes mean that proof is no longer fresh.

Why it exists

Coding agents are good at confident summaries. Reviewers need a tighter contract:

“The release marker is valid.”
       ↓
claim + files + executable argv + captured evidence + file hashes
       ↓
verified / contradicted / unverified / stale

If a relevant file changes after a probe runs, ShipReceipt marks the claim stale. It does not leave yesterday’s green check pretending to prove today’s tree.

Related MCP server: Agent Trust Stack MCP Server

Quickstart

Requires Node 20+ and npm.

npm install
npm run build

# Create a receipt in the current repository
node packages/cli/dist/index.js init

# Record a narrow claim. Everything after -- is executable plus argv, never a shell string.
node packages/cli/dist/index.js claim "The unit suite passes." \
  --file packages/core/src/core.ts -- node --test

# Direct CLI execution needs an explicit approval flag; previously allowlisted contracts can re-run without it.
node packages/cli/dist/index.js run clm_yourclaim --approve
node packages/cli/dist/index.js status
node packages/cli/dist/index.js export --format html --out shipreceipt-report.html

See the full state machine in 10 seconds

npm run smoke

The smoke fixture creates a passing claim, a failing claim, then modifies the passing claim’s tracked file. Its final status contains stale and contradicted; it also exports a static HTML report.

For the browser demo:

npm run build --workspace=@shipreceipt/web
npx serve packages/web/dist -l 4173

The dashboard’s buttons run an in-browser fixture only. To use the same UI against a real local receipt, start its local-only reader after building:

npm run live --workspace=@shipreceipt/web -- --root /path/to/repository

It serves packages/web/dist and a local /receipt.json status endpoint; it never executes probes. The hosted static demo never executes commands or reads a visitor’s filesystem.

CLI

--root is supported on every command. A probe’s command is stored as an executable and argv array. There is no shell interpolation or shell: true path. run needs an explicit --approve, unless the full probe contract (argv, cwd, timeout, expected exit, files, and allowed environment names) was previously recorded with allow.

Receipt states

Codex plugin and MCP

The repository includes a repo-local marketplace at .agents/plugins/marketplace.json and an installable plugin in plugins/shipreceipt.

Build first, then add the repository marketplace and install the plugin:

codex plugin marketplace add /path/to/shipreceipt
codex plugin add shipreceipt@shipreceipt-marketplace

The plugin carries a self-contained bundled stdio MCP server and exposes five deterministic tools:

• shipreceipt_init

• shipreceipt_claim

• shipreceipt_run (runs only contracts already allowlisted through the local CLI)

• shipreceipt_status

• shipreceipt_report

The skill at plugins/shipreceipt/skills/shipreceipt/SKILL.md instructs Codex to use narrow claims, explain intended execution, and cite a receipt ID/status rather than claim success from prose. MCP callers cannot self-approve execution: after a claim is recorded, the user must inspect and allowlist its full probe contract through the local shipreceipt allow <id> CLI command before shipreceipt_run can execute it. npm run build refreshes the plugin-local MCP bundle before installation.

You can smoke the server directly using newline-delimited JSON-RPC:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | node packages/mcp/dist/index.js

Architecture

Codex skill / CLI / MCP
          │
          ▼
  @shipreceipt/core
  schemas · safe runner · hash snapshots · receipt store
          │
          ▼
 .shipreceipt/receipt.json ──► status / HTML report / local dashboard

The core library owns schemas, hashing, persistence, status calculation, redaction, and command execution. The CLI and MCP server are thin adapters. The web dashboard is static and uses a bundled demo state; it can be hosted without credentials. See architecture notes and decisions.

Safety and threat model

ShipReceipt is local-first, but running a probe is still code execution. The runner:

• requires explicit approval in the CLI and MCP interface;

• stores commands as executable plus argv and sets shell: false;

• restricts probe working directories to the receipt root;

• uses a default 30-second timeout capped at two minutes;

• caps each stdout/stderr stream at 64 KiB;

• forwards no environment variables unless named in the probe allowlist, except the minimal inherited PATH needed to locate an executable;

• applies best-effort redaction to common token/key, authorization, cookie, URL-credential, cloud-key, and private-key forms before storing output.

The receipt’s hashes and chain are tamper-evident only within a documented threat model. Before status, export, or execution, ShipReceipt verifies event linkage, every current claim/evidence binding, evidence hashes, and probe contracts; an integrity failure fails closed rather than reporting a green claim. Someone who can rewrite the receipt and all local files can still rewrite its history. Hashes prove consistency of what ShipReceipt recorded; they do not establish identity, remote provenance, or a secure audit trail. Do not put secrets in commands, claims, or files. See security notes.

Deployment

vercel.json builds and serves packages/web/dist as a static site. It has no server code and no command-execution endpoint. For another static host, run npm run build --workspace=@shipreceipt/web and publish that same directory.

Development and verification

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm run smoke
npm run plugin:check

Build Week / Codex disclosure

This is an OpenAI Build Week 2026 submission. GPT-5.6 in a persistent Codex session accelerated implementation: workspace setup, TypeScript core/CLI/MCP/dashboard code, tests, fixture, documentation drafts, and verification iteration. Human product decisions defined the problem, local-first evidence model, safety boundaries, visual direction, project scope, and final review criteria. No OpenAI API key is required: GPT-5.6 runs in the authenticated Codex host, while ShipReceipt itself is deterministic local tooling. See the public Codex build trace.

License

MIT. See LICENSE.