Start here

Capture an agent

The database wire proxy only sees SQL. To capture everything else an agent does — file writes, shell commands, and tool calls — you wire gmonk into the agent itself. For Claude Code that's the hook; for MCP-native agents it's the MCP gateway. This is the setting you're looking for if you want gmonk to "listen to all changes."

Two capture paths, often both. Run the wire proxy for database writes and the hook below for files/shell — they record into the same run tree and reverse the same way. Use whichever the agent actually touches.

Claude Code — the hook

install-hook makes a one-time, idempotent edit to Claude Code's settings.json, merging PreToolUse + PostToolUse blocks that pipe each tool call to gmonk. It never clobbers hooks you already have. The default matcher is:

text

Write | Edit | MultiEdit | NotebookEdit | Bash

— so file edits and shell commands are captured, and shell commands are gated before they run. The fast hook POSTs each call to the already-running review UI, so bring the stack up first, then install:

bash

# 1. get the compose file (if you don't have it) and start the review UI —
#    the fast hook posts to it, so it must be running
curl -O https://gmonk.dev/docker-compose.yml
docker compose up -d

# 2. register the hook against your host's Claude Code settings
docker compose run --rm -v "$HOME/.claude:/root/.claude" \
  gmonk install-hook --scope user

# 3. restart Claude Code / start a new session

Running gmonk from source (not Docker) instead? It's simply:

bash

gmonk install-hook --scope user

Or let the wizard do it: gmonk setup --files --scope user installs this hook (and gmonk setup --all sets up the database proxy too).

Scopes — where the hook is written

Scope	File	Use when
`user`	`~/.claude/settings.json`	All your projects. Recommended — keeps the embedded token out of any committed file.
`project`	`.claude/settings.json`	This repo, shared with the team (committed).
`local`	`.claude/settings.local.json`	This repo, just you (gitignored).

Remove it any time with gmonk uninstall-hook.

Transports

Fast HTTP (default) — a curl that POSTs to http://127.0.0.1:4319/hook-ingest over loopback, with an auto-provisioned bearer token. Far quicker than spawning a process per call, so it never freezes the agent.
Spawn (--exec) — a per-call process, for a headless setup with no running web endpoint. For Docker: --exec --command 'docker compose exec -T gmonk node build/gmonk.cjs hook-ingest'.
GMONK_HOOK_ENDPOINT=off on the web service disables the fast endpoint entirely (install-hook then uses spawn).

The hook is fail-safe: any error — endpoint down, missing curl, internal fault — logs and exits 0, so it can never break the agent's loop. At worst a single action goes unrecorded.

The shell gate

The same hook gates shell commands before they run, using Claude Code's own approval prompt. gmonk can only recover file changes inside the working directory, so it pauses any command that reaches outside it or does a device-level op with no before-image (rm -rf outside cwd, dd, mkfs).

bash

GMONK_SHELL_GATE=ask     # default: pause unrecoverable commands for approval
GMONK_SHELL_GATE=deny    # hard-block them
GMONK_SHELL_GATE=off     # disable
GMONK_SHELL_ALLOW='^terraform ,^make deploy'   # always-run regexes

See Prevention for the full gate model and the honest scope of the shell gate (best-effort defense in depth, not a sandbox).

Other agents

gmonk ships adapters for Claude Code, Cline, Codex, Cursor, Gemini CLI, and a generic stdin adapter — the same capture engine behind each.

MCP-native agents — the gateway

If your agent speaks MCP tool calls rather than opening a database connection, run gmonk as an MCP gateway in front of a downstream MCP server. It records every tool call, resolves its effect type, and applies the oracle, guard policy, and approval holds — including tool calls that touch object storage or external APIs.

bash

gmonk run -- <your-mcp-server> [args…]

Terminology: "proxy" always means the database wire proxy. The MCP path is the gateway — a different interception point.

Configuration

Hook and shell-gate variables (GMONK_HOOK_TOKEN, GMONK_HOOK_ENDPOINT, GMONK_SHELL_GATE, GMONK_SHELL_ALLOW, …) are in the configuration reference. What gets captured and how it's reversed is in coverage.

← Capture Recovery →