deedglass

module

v0.6.0 Latest Latest Go to latest Published: Oct 20, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/deedglass/deedglass

Links

Open Source Insights

README ¶

Deedglass

An agent said it updated 1 row. Postgres changed 301.

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.

Try it in your browser · Quickstart · Docs · Security · deedglass.com

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 …):

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

_{A real run of make demo-hero (commit 97a524c, 2026-10-14), each line shown at the time it printed.
Source: docs/assets/demo-hero.cast.json, drawn by scripts/demo/cast2svg.mjs.}

Four ways in

	Command	What it needs	What leaves your machine
In your browser	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.

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

mkdir acme-agents && cd acme-agents
npx -y deedglass init --yes
npx -y deedglass doctor
npx -y deedglass init --trigger

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

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.

How it works

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

If you need	Use this	Where Deedglass fits
An agent that only reads	A Postgres role with `SELECT` and nothing else. It can't change data whatever the agent sends, and there's nothing to install.	You don't need it. It's for agents that must write. (compare)
A place for an agent to try changes	A database branch: a Neon branch is a copy-on-write clone of your data; Supabase branches start without production data by default.	For the writes that must reach production: rules first, then the check and the record. (compare)
Routing, isolation and credentials for many MCP servers	An MCP gateway, such as Docker's, which runs each server in an isolated container and injects credentials.	Behind the gateway, for the servers that write to Postgres. (compare)
Traces of each step, and evaluations	Langfuse or LangSmith.	Next to them: a trace is the agent's side of the story; the check reads what Postgres committed. (compare)
Rules at the wire for Postgres, Kubernetes and HTTP	Claw Patrol, which gates each action against rules over the parsed traffic.	It also decides first; it adds the check of what Postgres committed, records anyone can check offline, and undo. (compare)
Scanning what an agent sends out and what its tools return	Pipelock, an agent firewall that scans MCP traffic in both directions.	It adds the check of what Postgres committed after each call, and undo for the rows. (compare)

Install

How	Command
npx (no install)	`npx -y deedglass help`
Install script (macOS, Linux)	`curl -fsSL https://raw.githubusercontent.com/deedglass/deedglass/main/scripts/install.sh \| sh`
Binaries	archives for macOS, Linux and Windows on the latest release, with `checksums.txt`
Go	`go install github.com/deedglass/deedglass/cmd/deedglass@latest` (the CLI, without the Console)
Docker	build the image from a checkout: `make web-build docker` (tags `deedglass:dev`; Node 24 builds the Console)

The install script downloads the release archive for your platform, checks its sha256 against the release's checksums.txt, and copies deedglass into ~/.local/bin; read it first: scripts/install.sh. A public container image is coming; until it's published, build the image locally as above. Checksums, signatures and SBOMs: docs/INSTALL.md.

Add it to your agent client

Install in VS Code · LM Studio · Goose · Claude Desktop · Every client

claude mcp add deedglass -- npx -y deedglass mcp serve

No link holds a key. Run npx deedglass init first; each client asks Deedglass for the key it wrote.

Claude Code plugin (the MCP server, the /deedglass:scan, /deedglass:wrap and /deedglass:watch commands, and skills for reading a scan and for giving an agent Postgres access safely), from this repo's own marketplace:

/plugin marketplace add deedglass/deedglass
/plugin install deedglass@deedglass

Every format, with its source: docs/INSTALL_CLIENTS.md.

SDKs and clients

TypeScript: @deedglass/sdk, with adapters for the AI SDK, the OpenAI Agents SDK, LangChain and the Claude Agent SDK.
Python: pip install deedglass, with LangChain and Claude Agent SDK adapters.
Go: github.com/deedglass/deedglass/pkg/deedglass.
MCP: deedglass mcp wrap governs any stdio MCP server; deedglass mcp serve governs remote ones for Claude Desktop, Claude Code, Cursor, VS Code and Windsurf.

Connectors

Postgres (Proven), REST, GitHub, Slack, Stripe (test mode only), Gmail drafts, Notion and remote MCP servers. Credentials live in an encrypted vault; every outbound call goes through one egress door. See docs/CONNECTORS.md.

Numbers

What	Measured	Target
Gate · allow, no witness	p50 5.81 ms · p99 19.4 ms	p50 < 5 ms · p99 < 25 ms (p50 missed)
Policy · 50 rules	p99 148 µs	p99 < 1 ms
Witness · L2 at 100 writes/s	p50 118 ms · p99 317 ms	p50 < 1 s
Verify · 100,000 deeds	1.53 s · 80.9 MiB	< 5 s · < 256 MiB
Stop · across 2 instances	max 23.5 ms over 20 trials	< 2 s

How they were measured, and the misses: docs/BENCHMARKS.md.

Security

The attack suite runs 82 cases against a real server and real Postgres on every release candidate: 82 matched, 0 differ (attack/results/latest.json, docs/ATTACK_SUITE.md). Report a vulnerability privately: SECURITY.md.

Free features send nothing to deedglass.com: the free scan reads files on your machine and, with --postgres-dsn-env, connects only to the database you name. A Pro licence is checked with Dodo Payments and deedglass.com: deedglass serve asks at start and then daily, and Pro commands ask when you run them; a request goes out when the last successful check is a day old, and at once when the clock runs more than 5 minutes behind the last check or the latest time seen, or when licence.clock is missing, unreadable or altered. deedglass licence activate, refresh and deactivate always call out. DEEDGLASS_NO_NETWORK=1 stops every licence call, and only those: deedglass version --check and the --latest option of deedglass policy install and policy packs contact GitHub when you use them. Head timestamps are off by default; with TSAs or a transparency service listed in deedglass.yaml, deedglass deeds timestamp and each export contact only those. With the network off, Pro runs on its cached token for up to 14 days after the last successful check. What each request carries: docs/LICENSING.md.

Contributing

Read CONTRIBUTING.md: make dev, make ci, the tests a change needs, and DCO sign-off (git commit -s). Questions go to Discussions (SUPPORT.md); how decisions are made is in GOVERNANCE.md.

If Deedglass showed you something your logs didn't, a GitHub star helps other people find it.

License

The core, the SDKs and the CLI are Apache-2.0. The Pro features in ee/ are FSL-1.1-ALv2, and each release of them becomes Apache-2.0 two years after it ships. The release binary, the @deedglass/cli-* npm packages and the container image include ee/, so their licence is Apache-2.0 AND FSL-1.1-ALv2.

FSL-1.1-ALv2 lets you read, run and change ee/ for anything except offering a competing product (ee/LICENSE); everything Deedglass does for safety is free and outside ee/ (docs/LICENSING.md). The rest is LICENSE; third-party notices are in NOTICE.

The record spec (spec/: the deed format and the export bundle) and the intent-vs-effect corpus (corpus/) are published under CC-BY-4.0, so anyone can implement, copy or adapt them with credit.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api Package api holds the Deedglass OpenAPI 3.1.1 document (openapi.yaml), written by hand and embedded in the binary.	Package api holds the Deedglass OpenAPI 3.1.1 document (openapi.yaml), written by hand and embedded in the binary.
attack Package attack holds the V0 attack suite (spec §13): integration tests run on testcontainers against PostgreSQL 16.15, 17.11 and 18.6, one per case in attack_meta.json.	Package attack holds the V0 attack suite (spec §13): integration tests run on testcontainers against PostgreSQL 16.15, 17.11 and 18.6, one per case in attack_meta.json.
cmd/attack-report command Command attack-report prints the last attack run and regenerates docs/ATTACK_SUITE.md from attack/attack_meta.json and attack/results/latest.json (S18).	Command attack-report prints the last attack run and regenerates docs/ATTACK_SUITE.md from attack/attack_meta.json and attack/results/latest.json (S18).
harness Package harness runs Deedglass's V7 attack cases (S18) against a real `deedglass serve` process, a real Postgres and loopback upstreams, and checks the universal invariants after every case: the deed chains are intact, the target is unchanged when nothing should have run, every action is terminal, no secret appears anywhere, and forbidden listeners saw no traffic.	Package harness runs Deedglass's V7 attack cases (S18) against a real `deedglass serve` process, a real Postgres and loopback upstreams, and checks the universal invariants after every case: the deed chains are intact, the target is unchanged when nothing should have run, every action is terminal, no secret appears anywhere, and forbidden listeners saw no traffic.
bench
cmd/dgbench command Command dgbench runs Deedglass's benchmark suites and reports them (S35).	Command dgbench runs Deedglass's benchmark suites and reports them (S35).
internal/load Package load is Deedglass's open-loop load generator and its reporting (S35 §3.1): a fixed arrival rate, latency measured from each request's intended send time (so a stalled server shows in the tail instead of slowing the generator down), warm-up discarded, several runs, and a log-linear histogram whose percentiles are within 1% of the exact ones.	Package load is Deedglass's open-loop load generator and its reporting (S35 §3.1): a fixed arrival rate, latency measured from each request's intended send time (so a stalled server shows in the tail instead of slowing the generator down), warm-up discarded, several runs, and a log-linear histogram whose percentiles are within 1% of the exact ones.
cmd
deedglass command Command deedglass is Deedglass in one binary: the server (deedglass serve), the CLI, and the MCP bridge (deedglass mcp serve and mcp wrap).	Command deedglass is Deedglass in one binary: the server (deedglass serve), the CLI, and the MCP bridge (deedglass mcp serve and mcp wrap).
deedglass/internal/ui Package ui is the deedglass CLI's visual language (brand §13.3): symbols, colour and alignment.	Package ui is the deedglass CLI's visual language (brand §13.3): symbols, colour and alignment.
mcpbgen command Command mcpbgen writes the Claude Desktop bundles (S47 §3.6) from built binaries:	Command mcpbgen writes the Claude Desktop bundles (S47 §3.6) from built binaries:
packgen command Command packgen writes internal/packs/snapshot/index.json from the pack directories next to it (S47 §3.8): every pack compiles, passes its cases and carries at least 12.	Command packgen writes internal/packs/snapshot/index.json from the pack directories next to it (S47 §3.8): every pack compiles, passes its cases and carries at least 12.
playgen command Command playgen writes the data files of the browser playground on deedglass.com/play (S47).	Command playgen writes the data files of the browser playground on deedglass.com/play (S47).
deploy
postgres Package postgres embeds the control-plane roles script, so deedglass init creates the roles with the same SQL as deploy/docker-compose.yml.	Package postgres embeds the control-plane roles script, so deedglass init creates the roles with the same SQL as deploy/docker-compose.yml.
ee
agency
scanfull
securitypack
undosession
examples
demo/policies Package demopolicies embeds the Acme demo policy, so deedglass dev seed --demo loads exactly the file the demo's cases test (S15).	Package demopolicies embeds the Acme demo policy, so deedglass dev seed --demo loads exactly the file the demo's cases test (S15).
demo/snippet command Command snippet prints the Acme demo's MCP client config (make demo-snippet CLIENT=…).	Command snippet prints the Acme demo's MCP client config (make demo-snippet CLIENT=…).
demo/sql Package sql holds the Acme demo's SQL (S15, S17, S21), embedded so deedglass init loads the same schema and seed into its local demo database as make demo-up does into the demo's orders-db.	Package sql holds the Acme demo's SQL (S15, S17, S21), embedded so deedglass init loads the same schema and seed into its local demo database as make demo-up does into the demo's orders-db.
mock-orders command Command mock-orders is a small orders API for the REST connector demo (S16) and S19's lying-mock witness demo.	Command mock-orders is a small orders API for the REST connector demo (S16) and S19's lying-mock witness demo.
policies Package policies holds Deedglass's starter policies (S12 §3.9) and their test cases, embedded so onboarding (default-deny), dev seed and the tests read the same bytes as the files on disk.	Package policies holds Deedglass's starter policies (S12 §3.9) and their test cases, embedded so onboarding (default-deny), dev seed and the tests read the same bytes as the files on disk.
sim Package simfiles embeds the default scenario for deedglass dev simulate (S27) and the three versions of its policy, so the CLI, the generator and the tests read the same bytes as the files on disk.	Package simfiles embeds the default scenario for deedglass dev simulate (S27) and the three versions of its policy, so the CLI, the generator and the tests read the same bytes as the files on disk.
slack Package slack holds the example Slack app manifest that `deedglass slack manifest` prints.	Package slack holds the example Slack app manifest that `deedglass slack manifest` prints.
internal
a2a Package a2a puts the Gate in front of a remote agent reached over the Agent2Agent (A2A) protocol (TY-07, ADR-113): deedglass a2a proxy.	Package a2a puts the Gate in front of a remote agent reached over the Agent2Agent (A2A) protocol (TY-07, ADR-113): deedglass a2a proxy.
a2a/a2atest Package a2atest is a fake A2A v1.0 peer for tests: a JSON-RPC endpoint at /rpc and an Agent Card at /.well-known/agent-card.json, on httptest (loopback, no network).	Package a2atest is a fake A2A v1.0 peer for tests: a JSON-RPC endpoint at /rpc and an Agent Card at /.well-known/agent-card.json, on httptest (loopback, no network).
agentscript Package agentscript is the scripted agent behind `deedglass dev agent-script` (S37 §3.3): a YAML file of scenes, each a list of steps (a tool call through the Gate as an agent, an allow-listed demo make target, a deedglass subcommand as argv, an approval, or a one-byte change to a file under .tmp/demo/), each with the outcome it expects from the real product.	Package agentscript is the scripted agent behind `deedglass dev agent-script` (S37 §3.3): a YAML file of scenes, each a list of steps (a tool call through the Gate as an agent, an allow-listed demo make target, a deedglass subcommand as argv, an approval, or a one-byte change to a file under .tmp/demo/), each with the outcome it expects from the real product.
approve Package approve handles human approval: requests, one-time approval links, expiry, four-eyes rules and resuming the action once decided (contract §5).	Package approve handles human approval: requests, one-time approval links, expiry, four-eyes rules and resuming the action once decided (contract §5).
approve/sections Package sections holds approval context sections other than undo (S40): email_preview, what a person reads before countersigning an email.	Package sections holds approval context sections other than undo (S40): email_preview, what a person reads before countersigning an email.
archtest Package archtest holds the import-layering test (ADR-013).	Package archtest holds the import-layering test (ADR-013).
buildinfo Package buildinfo reports what this binary is: its version, the commit it was built from, and the API versions it serves (contract §8, dated versions).	Package buildinfo reports what this binary is: its version, the commit it was built from, and the API versions it serves (contract §8, dated versions).
bundle Package bundle holds Operation Bundles (spec §6): a vendor-authored, content-addressed manifest (bundle_hash = "sha256:" + hex(SHA-256(JCS(manifest)))) that fixes the intent schema, the entry function and the SHA-256 of its exact prosrc, the expected schema, the write set and the marker count, plus the registry of rules compiled into the verifier (map[bundle_hash]Rule, starting with rules/transfer_v1.go).	Package bundle holds Operation Bundles (spec §6): a vendor-authored, content-addressed manifest (bundle_hash = "sha256:" + hex(SHA-256(JCS(manifest)))) that fixes the intent schema, the entry function and the SHA-256 of its exact prosrc, the expected schema, the write set and the marker count, plus the registry of rules compiled into the verifier (map[bundle_hash]Rule, starting with rules/transfer_v1.go).
caught Package caught finds the moments worth a person's attention in what Deedglass already recorded (S50 §3.7): "Deedglass caught this".	Package caught finds the moments worth a person's attention in what Deedglass already recorded (S50 §3.7): "Deedglass caught this".
cli/mark Package mark draws the Deedglass mark in a terminal (brand §5 and §13.3; S05X): the Split Orb in half-block pixels beside a short welcome (Banner), the one-line inline mark ◖│◗ that heads init, doctor and help (Inline), and the optional "Sealed" closing moment (Sealed).	Package mark draws the Deedglass mark in a terminal (brand §5 and §13.3; S05X): the Split Orb in half-block pixels beside a short welcome (Banner), the one-line inline mark ◖│◗ that heads init, doctor and help (Inline), and the optional "Sealed" closing moment (Sealed).
cli/mark/gen command Command gen writes orb_gen.go, the Split Orb's pixel grid, from the brand geometry (internal/cli/mark/internal/orbgen).	Command gen writes orb_gen.go, the Split Orb's pixel grid, from the brand geometry (internal/cli/mark/internal/orbgen).