← Back to all projects

numbat

Endpoint capture of AI agent activity into NDJSON, matched against local CEL rules, with opt-in blocking

OfficialApache-2.0
Stars
1.1k
Forks
123
Open issues
16
Last commit
30 Oct 2026

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 agents lists discovered agents and numbat scan --agent codex parses 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 all appends events, findings, indicators and applicable enforcement decisions to ~/.numbat/records.ndjson, while numbat hook status verifies 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-policy and numbat rules test; a rules directory replaces an embedded rule when it reuses the same id, and --no-builtin-rules gives an operator-only catalog.
  • Promote a monitor rule into a deny — Copy the shipped YAML from rules/, keep the id, add enforce: true, bump the version, then numbat 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 timeline builds a per-session view and numbat case build / numbat case verify produce 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

9251.1k

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.