deedglass

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/lockup-horizontal-dark.svg">
    <img src="docs/assets/lockup-horizontal-light.svg" alt="Deedglass" width="360">
  </picture>
</p>

<h3 align="center">An agent said it updated 1 row. Postgres changed 301.</h3>

<p align="center">
<!-- description:summary (docs/description.json; docs/description_test.go checks it) -->
Deedglass sits between AI agents and the systems they change. Rules decide each tool call, a check
compares what the system really changed with what the agent reported (Claimed, Checked or Proven;
Matches, Doesn't match or Can't check), and each result is sealed as a signed record anyone can
check offline. It can undo the rows an action changed.
</p>

<p align="center">
  <a href="https://github.com/deedglass/deedglass/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/deedglass/deedglass/actions/workflows/ci.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/deedglass/deedglass/releases"><img alt="Release" src="https://img.shields.io/github/v/release/deedglass/deedglass?sort=semver&label=release"></a>
  <a href="https://www.npmjs.com/package/deedglass"><img alt="npm" src="https://img.shields.io/npm/v/deedglass?label=npm"></a>
  <a href="#license"><img alt="Licence: Apache-2.0, with ee/ under FSL-1.1-ALv2" src="https://img.shields.io/badge/licence-Apache--2.0%20%2B%20ee%2F%20FSL--1.1--ALv2-0F766E"></a>
  <a href="https://pkg.go.dev/github.com/deedglass/deedglass/pkg/deedglass"><img alt="Go reference" src="https://pkg.go.dev/badge/github.com/deedglass/deedglass/pkg/deedglass.svg"></a>
  <a href="docs/ATTACK_SUITE.md"><img alt="Attack suite" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdeedglass%2Fdeedglass%2Fmain%2Fattack%2Fresults%2Fbadge.json"></a>
</p>

<p align="center">
<a href="https://deedglass.com/play">Try it in your browser</a> · <a href="https://docs.deedglass.com/quickstart/">Quickstart</a> ·
<a href="https://docs.deedglass.com">Docs</a> · <a href="SECURITY.md">Security</a> · <a href="https://deedglass.com">deedglass.com</a>
</p>

An agent was asked to mark order 42 as shipped. It ran one `UPDATE` and its tool reported 1 row. A
legacy trigger shipped 300 more orders in the same transaction. This is the real output of the
Quickstart's last step on 2026-10-14 (shortened where you see `…`):

```text
$ npx -y deedglass init --trigger
…
✕ UPDATE order 42         Proven · Doesn't match · Postgres changed 301 rows in public.orders. The agent reported 1.
  expected   UPDATE 1 row in public.orders where id = 42 · sets status
  observed   UPDATE 301 rows in public.orders · 300 outside id = 42
…
✓ Trigger off             orders_ship_open_batch dropped
✓ Undo preview            Undo available · 301 rows in public.orders · 301 updates
    policy   undo-needs-approval · a person countersigns first
```

The agent's log says 1 row. Deedglass read Postgres's own change log for that transaction, found
301, sealed the difference as a record, and planned an undo from those rows that runs only after a
person countersigns.

<p align="center">
  <img src="docs/assets/demo-hero.svg" width="846" alt="Terminal recording of a real make demo-hero run. Order 42 ships: Proven, Matches, 1 row. A legacy trigger is turned on and the same UPDATE runs: Proven, Doesn't match, Postgres changed 301 rows in public.orders, the agent reported 1, with the row diff. Then every record verifies offline.">
</p>
<p align="center"><sub>A real run of <code>make demo-hero</code> (commit 97a524c, 2026-10-14), each line shown at the time it printed.
Source: <a href="docs/assets/demo-hero.cast.json"><code>docs/assets/demo-hero.cast.json</code></a>, drawn by <a href="scripts/demo/cast2svg.mjs"><code>scripts/demo/cast2svg.mjs</code></a>.</sub></p>

## Four ways in

| | Command | What it needs | What leaves your machine |
|---|---|---|---|
| **In your browser** | [deedglass.com/play](https://deedglass.com/play) | A browser tab. Postgres runs in the page; it opens on the "said 1, changed 301" scene. | Nothing |
| **In your terminal** | `npx deedglass play` | Node, and deedglass 0.1.1 or newer from npm. No Docker. The rules decide each call live and the records are sealed and checked on your machine; Postgres's lines are replayed from a recorded real run, and labelled as such. | Nothing |
| **Scan your setup** | `npx deedglass scan` | Node. Reads your MCP configs and, if you name one, a database catalog, read-only. Grades what your agents could change, A to F. | Nothing, apart from read-only catalog queries to a database you name |
| **Observe mode** | `deedglass observe run --connector pg-demo -- ./agent.sh` | A Postgres connector with `observe` on. Nothing to rewire: it reads Postgres's change log beside whatever gate you already use. | Nothing |

When a scan finds a trigger or a cascade on a table your agent can write, it says so and points to
the 301 scene. Observe mode is [below](#observe-mode-nothing-to-rewire).

## Quickstart

Docker running with about 2 GiB of free disk, Node 18 or newer, and macOS or Linux (WSL 2 on
Windows), then (from the [tested Quickstart](https://docs.deedglass.com/quickstart/)):

<!-- quickstart:begin (scripted copy of docs-site/src/content/docs/quickstart.mdx; docs/readme_test.go compares them) -->
```sh
mkdir acme-agents && cd acme-agents
npx -y deedglass init --yes
npx -y deedglass doctor
npx -y deedglass init --trigger
```
<!-- quickstart:end -->

`deedglass init` starts two Postgres 18.6 containers in Docker (Deedglass's own database and a demo
database), runs `deedglass serve` on `127.0.0.1:8080`, creates an org, an agent and the
`postgres-safe` policy, and ends with a blocked `DROP TABLE` and an `UPDATE` checked at Proven.
`deedglass doctor` runs sixteen read-only checks, each with its fix. `deedglass init --trigger` turns
on the demo database's legacy trigger, sends the same one-row `UPDATE`, and ends on the 301-row
mismatch and the undo preview shown above.

## Observe mode: nothing to rewire

```sh
deedglass observe run --connector pg-demo -- ./agent.sh   # open a watched session, run the agent, close it
deedglass observe show obs_01k… --undo-sql                # the undo as SQL you review and run (free)
deedglass observe run --connector dev --undo-sql ~/deedglass-undo -- claude   # watch a Claude Code session, shell included
```

Turn it on with `witness.observe.enabled: true` in the connector's config. Observe mode reads only
Postgres's change log, through the role and replication slot that `deedglass connector postgres init`
creates, so it works beside any gate you already use, or none.
It shows every row committed on the watched tables while the session was open and seals the session
as a record. It can't tell which program wrote a row, so a session gets no Matches or Doesn't match
verdict; row images are kept 30 days; a `TRUNCATE` can't be undone from the record. Undo SQL is free;
a one-step undo through Deedglass is Pro. Details: [`docs/OBSERVE.md`](docs/OBSERVE.md).

## How it works

```mermaid
flowchart LR
  A["AI agents<br/>Claude · OpenAI · Cursor · any MCP client"] -->|tool call + agent key| G
  subgraph D["Deedglass · one binary + Postgres"]
    I[Identity] --> P[Policies] --> G[Rules]
    G --> W[Check] --> S[Records] --> L[Ledger] --> N[Insights]
  end
  G -->|credentials from the vault| T["Tools<br/>Postgres · GitHub · Slack · Stripe · MCP servers"]
  T -->|what actually happened| W
  H[People] -->|approve · stop| G
```

Every tool call passes through Deedglass with the agent's key. Your rules (policies) decide `allow`,
`deny` or `require_approval`; Deedglass runs the call with credentials the agent never holds; the
check compares what happened with what was asked; and the outcome is sealed as a record in the org's
chain.

## How sure each check is

| Level | What it checks | What it can't see |
|---|---|---|
| **Claimed** | The tool's own answer, against a schema and your postconditions | Whether the answer is true |
| **Checked** | A read-back from the target (GitHub, Slack, Stripe, Notion, REST, Postgres rows) | Side effects the read-back doesn't cover |
| **Proven** | Postgres's change log (logical decoding): every row the transaction committed | DDL, sequences, unlogged tables and anything outside that database's WAL |

Each record claims one level and one result: **Matches**, **Doesn't match** or **Can't check**. When
Deedglass can't tell whether a tool ran, the result is Can't check, never Matches. The API keeps
the short names (`L0`/`L1`/`L2`, `VERIFIED`/`MISMATCH`/`UNVERIFIABLE`); the
[glossary](https://docs.deedglass.com/concepts/glossary/) maps them.

## What it doesn't do

- Proven checks cover Postgres only, and need `wal_level=logical` and `REPLICA IDENTITY FULL` on watched tables.
- A hijacked agent with a valid key and an in-policy action is allowed. Policies, budgets and
  approvals narrow this; they don't close it.
- Deedglass trusts the Postgres server, its superusers, the host it runs on and its seal key. It
  can't protect you from a compromised host.
- Records hold digests, not payloads. One set of seal keys signs every org on an instance.
- It doesn't replace a least-privilege database role. Use both: the role limits what the agent can
  do; Deedglass checks what it did with that.

The whole list, with workarounds: [`docs/LIMITATIONS.md`](docs/LIMITATIONS.md) and [`KNOWN_ISSUES.md`](KNOWN_ISSUES.md).

## Alternatives

You may not need Deedglass, or you may want it next to one of these. Each has a longer page, with
sources and the date each was checked, at [deedglass.com/compare](https://deedglass.com/compare).
<!-- claims: C-109 (role), C-114 and C-116 (branches), C-117 (Docker's gateway), C-122 and C-123 (traces), C-110 (Claw Patrol), C-119 (Pipelock) -->

| If you need | Use this | Where Deedglass fits |
|---|---|---|
| An agent that only reads | A Postgres role with `SELECT` and nothing else. It can't