Agent Receipts

Logs tell you something happened. Receipts prove it.

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Real World Example

I built ModQuote — a multi-tenant SaaS for automotive shops. During development, I used Claude Code extensively for auditing and fixing the codebase.

The problem: when something went wrong, I had no way to prove what input Claude received, what it changed, or whether the output matched what was expected.

With Agent Receipts, every Claude Code session now generates signed receipts:

• Input hash proves exactly what code Claude saw
• Output hash proves exactly what it produced
• Constraints catch when latency spikes or costs exceed budget
• Chains show the full sequence of a multi-step audit session

When a fix didn't work as expected, I could pull the receipt, verify the signature, and see the exact input/output hashes — no guessing, no "Claude must have misunderstood."

That's the difference between logs and receipts. Logs tell you something happened. Receipts prove it.

Quick Start: MCP Server

Add the Agent Receipts MCP server to your AI tool's config and every action gets a cryptographic receipt automatically.

Platform support: macOS, Windows, and Linux — requires Node.js 18+

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Quick Start: SDK

npm install @agent-receipts/sdk

import { AgentReceipts } from '@agent-receipts/sdk'

const ar = new AgentReceipts()

const receipt = await ar.track({
  action: 'generate_report',
  input: { query: 'Q4 revenue' },
  output: { total: 142000 },
})

console.log(receipt.receipt_id)  // rcpt_8f3k2j4n...
console.log(receipt.signature)   // ed25519 signature

Quick Start: CLI

npx @agent-receipts/cli init          # Generate signing keys
npx @agent-receipts/cli keys          # Show public key
npx @agent-receipts/cli list          # List all receipts
npx @agent-receipts/cli verify <id>   # Verify a receipt signature

How It Works

1. Agent performs an action — API call, code generation, data lookup
2. Input/output are SHA-256 hashed — raw data never leaves your machine
3. Receipt is created — action, hashes, timestamp, agent ID, metadata
4. Receipt is Ed25519-signed — with a locally generated private key
5. Anyone can verify — share your public key; recipients verify independently

MCP Tools Reference

The MCP server exposes 14 tools that AI agents can call directly:

Tool	Description	Key Parameters
track_action	Track an agent action with automatic hashing	action, input, output, constraints
create_receipt	Create a receipt with pre-computed hashes	action, input_hash, output_hash, constraints
complete_receipt	Complete a pending receipt with results	receipt_id, output, status
verify_receipt	Verify the cryptographic signature of a receipt	receipt_id
get_receipt	Retrieve a receipt by ID	receipt_id
list_receipts	List receipts with optional filtering	agent_id, status, chain_id
get_chain	Get all receipts in a chain ordered by timestamp	chain_id
get_public_key	Export the Ed25519 public key for verification	—
judge_receipt	Start AI Judge evaluation of a receipt	receipt_id, rubric
complete_judgment	Complete a pending judgment with results	receipt_id, verdict, score, criteria
get_judgments	Get all judgments for a receipt	receipt_id
cleanup	Delete expired receipts (TTL)	dry_run
generate_invoice	Generate an invoice from receipts in a date range	from, to, format, agent_id
get_started	Show a getting-started guide with usage examples	—

SDK API Reference

new AgentReceipts(config?)

const ar = new AgentReceipts({
  dataDir: '~/.agent-receipts',  // optional, defaults to ~/.agent-receipts
})

ar.track(params) — Track a completed action

const receipt = await ar.track({
  action: 'analyze_data',
  input: { dataset: 'sales_2024' },
  output: { summary: 'Revenue up 12%' },
  agent_id: 'analyst-v2',
  chain_id: 'chain_abc',              // optional, auto-generated if omitted
  parent_receipt_id: 'rcpt_prev',     // optional, links to parent receipt
})

ar.start(params) — Start a pending receipt

const receipt = await ar.start({
  action: 'long_running_task',
  input: { job_id: '12345' },
})

ar.complete(receiptId, params) — Complete a pending receipt

const completed = await ar.complete(receipt.receipt_id, {
  output: { result: 'done' },
  status: 'completed',
})

ar.verify(receiptId) — Verify a receipt signature

const { verified, receipt } = await ar.verify('rcpt_8f3k2j4n')
// verified: true | false

ar.get(receiptId) — Get a receipt by ID

const receipt = await ar.get('rcpt_8f3k2j4n')

ar.list(filter?) — List receipts

const result = await ar.list({ agent_id: 'my-agent', status: 'completed' })
// result.data: ActionReceipt[]
// result.pagination: { page, limit, total, total_pages, has_next, has_prev }

ar.getPublicKey() — Get the signing public key

const publicKey = await ar.getPublicKey()
// 64-char hex string (Ed25519 public key)

ar.track() with Constraints

const receipt = await ar.track({
  action: 'generate_summary',
  input: { document_id: 'doc-q4-2024' },
  output: { summary: 'Revenue grew 12% YoY...' },
  latency_ms: 1200,
  cost_usd: 0.005,
  constraints: [
    { type: 'max_latency_ms', value: 5000 },
    { type: 'max_cost_usd', value: 0.01 },
    { type: 'min_confidence', value: 0.8 },
  ],
})
// receipt.constraint_result.passed → true/false

ar.getJudgments(receiptId) — Get judgments

const judgments = await ar.getJudgments('rcpt_8f3k2j4n')

ar.cleanup() — Delete expired receipts

const { deleted, remaining } = await ar.cleanup()

ar.generateInvoice(params) — Generate invoice from receipts

const invoice = await ar.generateInvoice({
  from: '2026-01-01',
  to: '2026-01-31',
  agent_id: 'my-agent',       // optional filter
  group_by: 'agent',          // optional: agent | action | day
})

CLI Reference

Command	Description
init	Create data directory and generate signing keys
keys	Display the public key
keys --export	Export public key as JSON
keys --import <hex>	Import a private key (64 hex chars)
inspect <id|file>	Pretty-print a receipt
verify <id|file>	Verify a receipt signature
verify <id|file> --key <hex>	Verify with an external public key
list	List receipts (default: 50)
list --agent <id> --status <s>	Filter by agent or status
list --json	Output as JSON
chain <chain_id>	Show all receipts in a chain
chain <chain_id> --tree	Show chain as visual tree
stats	Show aggregate receipt statistics
judgments <id>	List judgments for a receipt
cleanup	Delete expired receipts
cleanup --dry-run	Preview what would be deleted
export <id>	Export a single receipt as JSON
export --all	Export all receipts as compact JSON
export --all --pretty	Export all receipts as formatted JSON
invoice --from <date> --to <date>	Generate invoice from receipts in date range
invoice --format <fmt>	Output as json, csv, md, or html
seed --demo	Seed demo data for testing
seed --demo --count <n>	Seed a custom number of demo receipts
seed --demo --clean	Delete all receipts before seeding
watch	Watch for new receipts in real-time
watch --agent <id>	Watch filtered by agent, action, or status

Receipt Format

{
  "receipt_id": "rcpt_8f3k2j4n",
  "chain_id": "chain_x9f2k",
  "parent_receipt_id": null,
  "receipt_type": "action",
  "agent_id": "my-agent",
  "org_id": "my-org",
  "action": "generate_report",
  "status": "completed",
  "input_hash": "sha256:abc123...",
  "output_hash": "sha256:def456...",
  "output_summary": "Generated Q4 report",
  "model": "claude-sonnet-4-20250514",
  "timestamp": "2026-02-07T14:32:01.442Z",
  "completed_at": "2026-02-07T14:32:02.100Z",
  "latency_ms": 658,
  "cost_usd": 0.003,
  "signature": "ed25519:<hex>"
}

Input and output are hashed client-side with SHA-256. Raw data never leaves your environment. Only hashes are stored in the receipt.

Verification

Share your public key with anyone who needs to verify your receipts:

# Export your public key
npx @agent-receipts/cli keys --export

# Verify a receipt with an external public key
npx @agent-receipts/cli verify receipt.json --key <public-key-hex>

Verification re-computes the Ed25519 signature over the receipt's deterministic fields and confirms it matches the stored signature. No network requests — fully offline.

Configuration

Environment Variable	Description	Default
AGENT_RECEIPTS_DATA_DIR	Data directory path	~/.agent-receipts
AGENT_RECEIPTS_AGENT_ID	Default agent ID	local-agent
AGENT_RECEIPTS_ORG_ID	Organization ID	local-org
AGENT_RECEIPTS_ENVIRONMENT	Environment label (development, production, staging, test)	production
RECEIPT_SIGNING_PRIVATE_KEY	Ed25519 private key (hex)	Auto-generated

Storage

All data is stored locally in the data directory:

~/.agent-receipts/
├── keys/
│   ├── private.key          # Ed25519 private key (mode 0600)
│   └── public.key           # Ed25519 public key
├── receipts/
│   └── *.json               # Legacy JSON files (auto-migrated)
├── receipts.db              # SQLite database (primary storage)
└── config.json              # Agent and org configuration

As of v0.2.7, receipts are stored in SQLite with indexed queries for fast filtering and pagination. Existing JSON receipt files are automatically migrated on first startup.

Architecture

┌─────────────────────────────────────────────┐
│                  CLI                         │
│           @agent-receipts/cli                 │
├─────────────────────────────────────────────┤
│           SDK            │   MCP Server      │
│   @agent-receipts/sdk     │ @agent-receipts/   │
│                          │   mcp-server      │
├──────────────────────────┴──────────────────┤
│              Crypto + Schema                 │
│   @agent-receipts/crypto  @agent-receipts/     │
│                            schema            │
└─────────────────────────────────────────────┘

• schema — Zod schemas, TypeScript types, JSON Schema for the Action Receipt Protocol
• crypto — Ed25519 key generation, signing, verification, canonical serialization
• mcp-server — MCP protocol server with receipt engine, storage, and key management
• sdk — High-level Node.js SDK wrapping the engine
• cli — Command-line tool for inspecting, verifying, and managing receipts
• dashboard — Mission Control web UI for visualizing and managing receipts

Dashboard (Mission Control)

Visualize every receipt, chain, agent, constraint, and judgment in your system.

npx @agent-receipts/dashboard

Opens Mission Control at http://localhost:3274 — visualize, verify, and manage all receipts.

Features: real-time receipt feed, chain visualization, constraint health monitoring, judgment scores, signature verification, invoice generation, dark mode, global search.

13 pages: Overview, Receipts, Receipt Detail, Chains, Chain Detail, Agents, Agent Detail, Constraints, Judgments, Invoices, Verify, Settings, How It Works.

Examples

Example	Description
examples/basic	Simple action tracking with verification
examples/chained	Multi-step pipeline with parent/child receipt linking
examples/pipeline	Document analysis pipeline with chained receipts
examples/constraints	Constraint verification with pass/fail rules
examples/judge	AI Judge evaluation with rubrics
examples/ttl	Receipt TTL and cleanup

Packages

Package	Description
@agent-receipts/schema	Zod schemas and TypeScript types for the Action Receipt Protocol
@agent-receipts/crypto	Ed25519 signing, verification, and key management
@agent-receipts/mcp-server	MCP protocol server with receipt engine and storage
@agent-receipts/sdk	High-level Node.js SDK for tracking and verifying receipts
@agent-receipts/cli	Command-line tool for managing receipts
@agent-receipts/dashboard	Mission Control web UI — npx @agent-receipts/dashboard

Roadmap

• Local-first receipt storage (SQLite with indexed queries)
• Ed25519 signing and verification
• MCP server with 14 tools
• Node.js SDK
• CLI with full command set
• Constraint verification (6 built-in types)
• AI Judge with rubric-based evaluation
• Output schema validation (JSON Schema)
• Receipt TTL and cleanup
• Invoice generation (JSON, CSV, Markdown, HTML)
• Mission Control dashboard (13 pages, dark mode, search)
• Dashboard npm package — npx @agent-receipts/dashboard
• Live demo at agent-receipts-web.vercel.app
• Receipt anchoring to blockchain/timestamping services
• Multi-agent receipt sharing protocol
• Receipt compression and archival
• Hosted tier with cloud database

Development

pnpm install
pnpm build
pnpm test
pnpm dev

License

MIT — see LICENSE