|
4 | 4 |
|
5 | 5 | **Cryptographically signed audit trails for AI agent actions** |
6 | 6 |
|
7 | | -[](https://github.com/agent-receipts/ar/actions/workflows/sdk-go.yml) |
8 | | -[](https://github.com/agent-receipts/ar/actions/workflows/sdk-ts.yml) |
9 | | -[](https://github.com/agent-receipts/ar/actions/workflows/sdk-py.yml) |
| 7 | +[](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-go.yml) |
| 8 | +[](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-ts.yml) |
| 9 | +[](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-py.yml) |
| 10 | +[](https://github.com/agent-receipts/obsigna/actions/workflows/daemon.yml) |
| 11 | +[](https://github.com/agent-receipts/obsigna/actions/workflows/mcp-proxy.yml) |
| 12 | +[](https://github.com/agent-receipts/obsigna/actions/workflows/hook.yml) |
10 | 13 | [](LICENSE) |
11 | 14 |
|
12 | 15 | </div> |
|
23 | 26 |
|
24 | 27 | --- |
25 | 28 |
|
26 | | -## Start here |
27 | | - |
28 | | -The fastest way to try Agent Receipts is to put [`mcp-proxy/`](mcp-proxy/) in front of an MCP server you already use. |
29 | | - |
30 | | -In one step, you get: |
31 | | - |
32 | | -- Signed receipts for every tool call |
33 | | -- A tamper-evident audit chain you can verify later |
34 | | -- Risk scoring and policy hooks without changing the client or server |
35 | | - |
36 | | -If you want to audit GitHub MCP in a real agent workflow, start with: |
| 29 | +## What is this? |
37 | 30 |
|
38 | | -- [Claude Desktop integration](https://agentreceipts.ai/mcp-proxy/claude-desktop/) |
39 | | -- [Claude Code integration](https://agentreceipts.ai/mcp-proxy/claude-code/) |
40 | | -- [Codex integration](https://agentreceipts.ai/mcp-proxy/codex/) |
| 31 | +**Agent Receipts** is an open protocol for producing cryptographically signed, tamper-evident records of AI agent actions. It defines the receipt format, signing scheme, chain structure, and taxonomy of action types. Anyone can implement it — in any language, in any runtime. |
41 | 32 |
|
42 | | -## What is this? |
| 33 | +**Obsigna** is the reference toolset that implements the protocol: |
43 | 34 |
|
44 | | -Agent Receipts is an open protocol and set of SDKs for producing cryptographically signed, tamper-evident records of AI agent actions. Every action an agent takes -- API calls, tool use, data access -- gets a verifiable receipt that can be audited later. |
| 35 | +| Tool | What it does | |
| 36 | +|------|-------------| |
| 37 | +| `obsigna-mcp` | MCP stdio proxy — signs every tool call, adds policy hooks | |
| 38 | +| `obsigna-daemon` | Out-of-process signing daemon — holds the key, owns the audit chain | |
| 39 | +| `obsigna-hook` | PostToolUse hook for Claude Code and other runtimes | |
| 40 | +| `obsigna` | CLI for browsing and verifying receipt databases | |
| 41 | +| `sdk/go`, `@obsigna/sdk-ts`, `obsigna` (Python) | SDKs for embedding receipt creation in your own code | |
45 | 42 |
|
46 | 43 | <picture> |
47 | 44 | <img alt="How it works: Authorize → Act → Sign → Link → Audit" src=".github/how-it-works.svg"> |
48 | 45 | </picture> |
49 | 46 |
|
50 | | -## Project layout |
| 47 | +## Start here |
51 | 48 |
|
52 | | -| Project | Description | |
53 | | -|---------|-------------| |
54 | | -| [`docs/adr/`](docs/adr/) | Architecture Decision Records | |
55 | | -| [`spec/`](spec/) | Protocol specification, JSON schemas, governance | |
56 | | -| [`sdk/go/`](sdk/go/) | Go SDK | |
57 | | -| [`sdk/ts/`](sdk/ts/) | TypeScript SDK | |
58 | | -| [`sdk/py/`](sdk/py/) | Python SDK | |
59 | | -| [`daemon/`](daemon/) | Signing daemon — out-of-process key custody, shared audit chain | |
60 | | -| [`mcp-proxy/`](mcp-proxy/) | MCP proxy with receipt signing, policy engine, intent tracking | |
61 | | -| [`cross-sdk-tests/`](cross-sdk-tests/) | Cross-language verification tests | |
62 | | -| [dashboard](https://github.com/agent-receipts/dashboard) | Local web UI for browsing and verifying receipt databases | |
63 | | -| [openclaw](https://github.com/agent-receipts/openclaw) | Agent Receipts plugin for OpenClaw | |
| 49 | +Both paths below require the daemon — it holds the signing key and owns the audit chain. Install it first: |
64 | 50 |
|
65 | | -## 10-minute audited MCP quick start |
| 51 | +```bash |
| 52 | +brew install agent-receipts/tap/obsigna |
| 53 | +obsigna daemon start |
| 54 | +``` |
66 | 55 |
|
67 | | -Install the proxy: |
| 56 | +**Fastest path — PostToolUse hook (Claude Code):** one config snippet and every tool call gets a signed receipt automatically: |
68 | 57 |
|
69 | | -```bash |
70 | | -go install github.com/agent-receipts/ar/mcp-proxy/cmd/obsigna-mcp@latest |
| 58 | +```json |
| 59 | +{ |
| 60 | + "hooks": { |
| 61 | + "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "obsigna-hook" }] }] |
| 62 | + } |
| 63 | +} |
71 | 64 | ``` |
72 | 65 |
|
73 | | -Wrap any MCP server: |
| 66 | +Add that to `~/.claude/settings.json`, then inspect the audit trail: |
74 | 67 |
|
75 | 68 | ```bash |
76 | | -obsigna-mcp node /path/to/mcp-server.js |
| 69 | +obsigna list |
| 70 | +obsigna show <seq> |
| 71 | +obsigna verify |
77 | 72 | ``` |
78 | 73 |
|
79 | | -Then point your agent client at the proxy instead of the raw server: |
| 74 | +**More control — MCP proxy:** wraps any MCP server and adds policy hooks and risk scoring on top of signed receipts: |
80 | 75 |
|
81 | 76 | - [Claude Desktop setup](https://agentreceipts.ai/mcp-proxy/claude-desktop/) |
82 | 77 | - [Claude Code setup](https://agentreceipts.ai/mcp-proxy/claude-code/) |
83 | 78 | - [Codex setup](https://agentreceipts.ai/mcp-proxy/codex/) |
84 | 79 |
|
85 | | -Once your agent makes tool calls, inspect the signed audit trail: |
| 80 | +## Project layout |
86 | 81 |
|
87 | | -```bash |
88 | | -obsigna list |
89 | | -obsigna show <seq> |
90 | | -obsigna verify |
91 | | -``` |
| 82 | +| Project | Description | |
| 83 | +|---------|-------------| |
| 84 | +| [`spec/`](spec/) | Protocol specification, JSON schemas, governance | |
| 85 | +| [`sdk/go/`](sdk/go/) | Go SDK | |
| 86 | +| [`sdk/ts/`](sdk/ts/) | TypeScript SDK | |
| 87 | +| [`sdk/py/`](sdk/py/) | Python SDK | |
| 88 | +| [`daemon/`](daemon/) | Signing daemon — out-of-process key custody, shared audit chain | |
| 89 | +| [`mcp-proxy/`](mcp-proxy/) | MCP proxy with receipt signing, policy engine, intent tracking | |
| 90 | +| [`hook/`](hook/) | PostToolUse hook binary for Claude Code and other runtimes | |
| 91 | +| [`cross-sdk-tests/`](cross-sdk-tests/) | Cross-language verification tests | |
| 92 | +| [`docs/adr/`](docs/adr/) | Architecture Decision Records | |
| 93 | +| [dashboard](https://github.com/agent-receipts/dashboard) | Local web UI for browsing and verifying receipt databases | |
| 94 | +| [openclaw](https://github.com/agent-receipts/openclaw) | Agent Receipts plugin for OpenClaw | |
92 | 95 |
|
93 | 96 | ## SDK quick start |
94 | 97 |
|
|
0 commit comments