Skip to content

Commit 2e0ca94

Browse files
ojongeriusojongerius
authored
docs: reframe README around Agent Receipts (protocol) vs Obsigna (tools) split (#829)
* docs: reframe README around Agent Receipts (protocol) vs Obsigna (tools) split Introduce "What is this?" above "Start here" so the two brands are explained before any setup instructions. Agent Receipts is defined as the open protocol (format, signing scheme, chain, taxonomy); Obsigna is the reference toolset that implements it, with each binary and SDK listed in a table. Also adds the missing hook/ row to the project layout table and moves docs/adr/ to the end of that table. * docs: add CI badges for daemon, mcp-proxy, and hook; fix badge repo URLs Badge URLs were pointing at the old `ar` repo name; update to `obsigna`. Add badges for daemon, mcp-proxy, and hook alongside the existing SDK badges. * docs: fix 'start here' — hook is fastest path, daemon is required for both The section was written before the daemon/hook split. Correct it: - daemon install is the prerequisite for both paths - obsigna-hook (one settings.json snippet) is the fastest entry point - mcp-proxy is the 'more control' path (policy, risk scoring) - remove the now-redundant '10-minute MCP quick start' section
1 parent f6f8d7c commit 2e0ca94

1 file changed

Lines changed: 45 additions & 42 deletions

File tree

‎README.md‎

Lines changed: 45 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77
[![Go Tests](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-go.yml/badge.svg)](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-go.yml)
88
[![TS Tests](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-ts.yml/badge.svg)](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-ts.yml)
99
[![Python Tests](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-py.yml/badge.svg)](https://github.com/agent-receipts/obsigna/actions/workflows/sdk-py.yml)
10+
[![Daemon](https://github.com/agent-receipts/obsigna/actions/workflows/daemon.yml/badge.svg)](https://github.com/agent-receipts/obsigna/actions/workflows/daemon.yml)
11+
[![MCP Proxy](https://github.com/agent-receipts/obsigna/actions/workflows/mcp-proxy.yml/badge.svg)](https://github.com/agent-receipts/obsigna/actions/workflows/mcp-proxy.yml)
12+
[![Hook](https://github.com/agent-receipts/obsigna/actions/workflows/hook.yml/badge.svg)](https://github.com/agent-receipts/obsigna/actions/workflows/hook.yml)
1013
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
1114

1215
</div>
@@ -23,72 +26,72 @@
2326

2427
---
2528

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?
3730

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.
4132

42-
## What is this?
33+
**Obsigna** is the reference toolset that implements the protocol:
4334

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 |
4542

4643
<picture>
4744
<img alt="How it works: Authorize → Act → Sign → Link → Audit" src=".github/how-it-works.svg">
4845
</picture>
4946

50-
## Project layout
47+
## Start here
5148

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:
6450

65-
## 10-minute audited MCP quick start
51+
```bash
52+
brew install agent-receipts/tap/obsigna
53+
obsigna daemon start
54+
```
6655

67-
Install the proxy:
56+
**Fastest path — PostToolUse hook (Claude Code):** one config snippet and every tool call gets a signed receipt automatically:
6857

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+
}
7164
```
7265

73-
Wrap any MCP server:
66+
Add that to `~/.claude/settings.json`, then inspect the audit trail:
7467

7568
```bash
76-
obsigna-mcp node /path/to/mcp-server.js
69+
obsigna list
70+
obsigna show <seq>
71+
obsigna verify
7772
```
7873

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:
8075

8176
- [Claude Desktop setup](https://agentreceipts.ai/mcp-proxy/claude-desktop/)
8277
- [Claude Code setup](https://agentreceipts.ai/mcp-proxy/claude-code/)
8378
- [Codex setup](https://agentreceipts.ai/mcp-proxy/codex/)
8479

85-
Once your agent makes tool calls, inspect the signed audit trail:
80+
## Project layout
8681

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 |
9295

9396
## SDK quick start
9497

0 commit comments

Comments
 (0)