Numbat

What it is

numbat (github.com/perplexityai/numbat) is a single-binary Go tool for endpoint visibility into AI-agent activity. The existing summary covers its scope; what the page adds is the concrete operator workflow — read-only discovery, monitor-only hook installation, and the specific steps required to turn on blocking — plus the trust caveats around hooks.

How it works

Detection runs locally against one normalized event model, whether events arrive live (hooks, plugins, OTLP/HTTP exporters) or from at-rest on-disk artifacts. Output is versioned NDJSON to stdout, a local file, or optionally over HTTP. Records default to ~/.numbat/records.ndjson with --emit all. numbat hook status verifies configuration only — not that hooks actually execute or deliver.

What to do

Read-only inspection installs nothing and changes no agent config:

numbat agents
numbat scan
numbat scan --agent codex

Install monitor-only live capture (Codex example):

numbat hook install --agent codex --emit all
numbat hook status --agent codex

Enforcement is the non-obvious part. All shipped rules are monitor-only; you cannot enable blocking by flag alone. Copy a rule's complete shipped YAML into your own operator directory, keep the same id, add enforce: true, bump its version, then validate and install:

numbat rules check --rules-dir ./numbat-policy
numbat hook install --agent codex --emit all \
  --rules-dir ./numbat-policy --enforce

Install from source if you don't want a release binary (Go 1.26.6+):

go install github.com/perplexityai/numbat/cmd/numbat@latest
CGO_ENABLED=0 go build -trimpath -o numbat ./cmd/numbat

Preconditions / Caveats

• Blocking works only on supported synchronous pre-action hooks; the coverage matrix per host/surface is authoritative, so verify your agent+scope before relying on enforcement.
• Hook trust is manual and per-agent. For the Codex user hook you must review and trust its definition in /hooks (CLI) or Settings > Hooks (app) — including after changing to --enforce. Only --managed hooks are trusted by policy.
• A sequence finding (e.g. chain.secret_read_then_egress) does not prove either step completed — it reflects proposed/observed callbacks, and the same rules run during artifact scans.
• Normal output never includes a full raw transcript; adding raw evidence to a case bundle is opt-in.

flowchart TD
    A[Shipped rule: monitor-only] --> B[Copy full YAML to operator dir]
    B --> C[Keep id, add enforce:true, bump version]
    C --> D[rules check --rules-dir]
    D --> E[hook install --rules-dir --enforce]
    E --> F{Hook trusted?}
    F -->|managed: by policy| G[Enforcement active]
    F -->|user hook: manual review| G
    F -->|not trusted| H[No enforcement]