How it works

Capture

Capture is how gmonk records what an agent did — with enough before-state to undo it later. There are four capture taps for databases, plus filesystem and object-storage capture. Every recorded action lands in a tamper-evident tree.

1. Wire proxy — the main path

gmonk sits in the database connection. The agent points at gmonk instead of Postgres/MySQL; gmonk snapshots the before-image of each write on the agent's own connection (same transaction as the write) before passing it through. It auto-detects the engine from the URL scheme.

bash

export APP_DB_URL=postgres://user:pw@db-host:5432/appdb
gmonk protect --backend-ref APP_DB_URL --listen 6432
# agent connects to: postgres://agent@localhost:6432/appdb

It captures single-table UPDATE/DELETE/INSERT — plain or parameterized, in autocommit or inside a client transaction. In --guarantee mode the write is captured and executed in one transaction and rolled back unless the undo is provable.

2. WAL / logical decoding

For a database you can't put a proxy in front of (a locked-down managed RDS / Cloud SQL), gmonk reads the write-ahead log via a logical replication slot and drains changes into its own store. It touches the target only for the slot and REPLICA IDENTITY — nothing in the write path, no gmonk objects in your database.

3. In-database triggers

For a co-located database you own, capture triggers log the actual old/new rows. Triggers are the most precise — joins, cascades, and range updates all reverse correctly — and they're agent-agnostic: psql, an ORM, and app code are all captured, not just the agent.

gmonk protect-db detects whether the target is co-located or separate and picks WAL or triggers automatically.

4. MCP hook

For an agent that speaks MCP tool calls instead of opening a database connection, gmonk installs a capture hook. It records every tool call and gates unrecoverable shell commands using the agent's own approval prompt. Supported adapters: Claude Code, Cline, Codex, Cursor, Gemini CLI.

bash

gmonk install-hook --scope user

Full setup — scopes, transports, the shell gate, and MCP-native agents — is on Capture an agent.

Files & object storage

File writes/edits/deletes are captured with content snapshots. Object-storage put/delete (S3, MinIO) is captured by version when bucket versioning is on (record the prior versionId; reverse is a server-side copy, no bytes stored) or by snapshot otherwise (copy bytes into the content store).

The content store & action tree

Before-images live in a content-addressed store (sha256, gzip, deduped; local filesystem or S3). Actions are linked into a tamper-evident hash chain (runs → tasks → actions); every reversal is itself recorded as a new action, so history can't be quietly rewritten. Retention is handled by gmonk gc, on a schedule or in-process.

Run one capture mechanism per table (proxy or triggers, not both). The gate and capture both work across every path.

← Coverage Prevention →