agent-receipt

Automatic receipts for every Claude Code session. Track intent, tool calls, cost, side effects, and outcome quality — without Claude's cooperation.

Install

npx agent-receipt init

That's it. This adds Claude Code hooks and an MCP server to your project. Every session automatically gets a receipt.

What's in a receipt?

| Field | Description | |---|---| | Intent | What the session set out to do | | Outcome | What actually happened | | Intent Score | 0.0–1.0 alignment score (via Haiku) | | Cost | Token counts and USD estimate by model | | Tool Calls | Every tool invocation with input/output | | Side Effects | File writes, deletes, git pushes, API calls | | Duration | Wall clock time |

How it works

Claude Code hooks fire on lifecycle events — no prompting required:

| Hook | What happens | |---|---| | SessionStart | Creates a session row in local SQLite | | PostToolUse | Logs each tool call (name, input, response) | | PostToolUseFailure | Logs failed tool calls with error | | SessionEnd | Finalizes the receipt: aggregates calls, detects side effects, calculates cost |

Receipts are stored locally at ~/.agent-receipt/receipts.db.

Commands

agent-receipt init              # Set up hooks + MCP in current project
agent-receipt init --dry-run    # Preview without writing files
agent-receipt setup             # Install hooks globally (~/.claude/settings.json)
agent-receipt setup --local     # Install hooks in current project only

MCP tools

The MCP server exposes tools for explicit overrides on top of automatic hook tracking:

• receipt_start — Set intent, tags, and budget for the current session
• receipt_log_tool_call — Log a tool call manually
• receipt_end — End session and generate receipt with optional outcome
• receipt_score — Submit intent score after evaluating the scoring prompt

Receipt format

Receipts export as Markdown for pasting in PRs:

## Agent Receipt `rec_a1b2c3d4`

**Intent:** Add user authentication
**Outcome:** Executed 12 tool call(s): wrote auth middleware, added tests...
**Intent Score:** 0.85 (via host)

**Cost:** $0.42 · 28,400 tokens · 3m 12s

**Side Effects:**
- File writes: src/auth.ts, src/middleware.ts, tests/auth.test.ts
- Bash: npm install jsonwebtoken
- Git: committed changes

Storage

Local SQLite database at ~/.agent-receipt/receipts.db. No data leaves your machine.

License

MIT