
numbat
Endpoint capture of AI agent activity into NDJSON, matched against local CEL rules, with opt-in blocking
What is numbat?
numbat is a single binary that watches supported desktop, CLI, IDE and gateway agents through hooks, plugins and OTLP/HTTP log exporters, normalizes their activity into one event model, and evaluates it with a local CEL rule engine that writes versioned NDJSON events, findings and enforcement decisions. It also reconstructs past sessions from on-disk artifacts via `numbat scan`, so you can investigate an agent that was never instrumented. Blocking is deliberately conservative: enforce mode is off by default and every shipped rule is monitor-only, so denying an action means copying the rule YAML into your own `--rules-dir`, keeping its id, adding `enforce: true` and bumping the version. It is a poor fit if you expect coverage of arbitrary agents or a definitive account of what ran — the coverage matrix decides what is observable per host and surface, at-rest reconstruction cannot recover activity an agent never persisted, and findings are rule matches rather than proof that an action completed.
What can you do with numbat?
- Survey an endpoint before instrumenting it —
numbat agentslists discovered agents andnumbat scan --agent codexparses their on-disk session artifacts; both are read-only and install no hooks or agent config changes. - Stream live activity to a local record file —
numbat hook install --agent codex --emit allappends events, findings, indicators and applicable enforcement decisions to~/.numbat/records.ndjson, whilenumbat hook statusverifies configuration only — not execution or delivery. - Write detections in CEL and test them first — Custom YAML rules run through
numbat rules check --rules-dir ./numbat-policyandnumbat rules test; a rules directory replaces an embedded rule when it reuses the same id, and--no-builtin-rulesgives an operator-only catalog. - Promote a monitor rule into a deny — Copy the shipped YAML from
rules/, keep the id, addenforce: true, bump the version, thennumbat hook install --agent codex --rules-dir ./numbat-policy --enforce; blocking applies only to agents with a supported synchronous pre-action hook. - Hand an investigation to someone else —
numbat timelinebuilds a per-session view andnumbat case build/numbat case verifyproduce and check bundles with SHA-256 manifests — which establish internal consistency, not source authenticity; complete raw transcripts stay out of normal records unless you opt into adding evidence files.
Star history
16 Aug to 30 Oct · +224
Frequently asked questions
Is numbat free for commercial use?
numbat is released under the Apache-2.0 licence — OSI-approved open source, which permits commercial use.
How can numbat be deployed?
numbat is available as Runs locally / Self-hosted.