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:

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

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

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

Packages

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