numbat: endpoint-side detection and optional blocking for AI agent activity

The gap numbat targets: agents that act before anyone can see them

An AI agent running on a developer workstation reads files, calls tools, and issues network requests under a user account that already has permissions to do all of it. The README frames numbat around that problem: visibility into AI agent activity on endpoints, with detection running locally. The intended audience is whoever has to answer what an agent did on a given machine, whether a specific session touched a secret file, or whether a tool call was about to send data somewhere it should not. numbat is not a proxy and not a sandbox. It sits alongside agents and consumes what they emit.

The scope is deliberately bounded to supported surfaces. The README states plainly that the coverage matrix in docs/agent-coverage.md#matrix is authoritative for each host and surface, which is the right posture for a tool whose collection depends on another program's extension points. If your agent is not in that matrix, the live monitoring path does not apply to it, and you are left with artifact scanning if the agent writes recoverable session files.

How collection works: hooks, OTLP/HTTP, and artifacts feeding one event model

numbat has three ingestion paths. The first is local hooks and plugins: for an agent with live-capture support, numbat installs a hook, and a callback such as OpenClaw's before_tool_call passes through a numbat-generated plugin and becomes a typed event. The README's example shows a browser tool call to the cloud metadata address arriving as a network.indicator event with the proposed destination, the tool name, the tool_call_id, the session_id, the source_agent, and an endpoint block carrying hostname, OS, arch, username and uid.

The second path is OTLP/HTTP log exporters, for agents that already emit telemetry in that format. The third is forensic reconstruction from on-disk session artifacts, which the README describes as working without prior numbat instrumentation. That third path is the one that matters for retroactive questions, and it is also the one with the most caveats, because it depends on what the agent chose to persist.

All three paths normalise into a single event model, and the same CEL rule engine evaluates live and at-rest activity. Records are versioned NDJSON, with JSON Schemas under docs/schema/v0.3.0/ defining the wire format, and the README notes that events and findings retain source references. Multi-step sequence rules are supported: the sample finding chain.secret_read_then_egress cites two event ids, carries rule_version 1.4, and maps to ATT&CK tags t1048, t1552 and t1567. One detail in that example deserves attention: the finding states that it does not prove either action completed. Sequence detection here is about ordering of observed callbacks, not confirmation of effect.

Install, inventory, and the first scan

Distribution is a single binary for macOS, Linux and Windows on amd64 or arm64, built without cgo. Releases carry SHA-256 checksums. With Go 1.26.6 or newer you can install from source:

go install github.com/perplexityai/numbat/cmd/numbat@latest

Or build a static binary from a checkout:

CGO_ENABLED=0 go build -trimpath -o numbat ./cmd/numbat

The read-only commands come first and do not install hooks or modify agent configuration:

numbat agents numbat scan numbat scan --agent codex

The first lists discovered agents. The second scans all parser-backed agents it found. The third restricts automatic discovery to a single agent. Running these before anything else is the cheapest way to learn whether numbat can see your environment at all.

Hooks, emit modes, and what hook status does not tell you

Live monitoring for an agent with live-capture support starts with:

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

Hooks begin in monitor-only mode. The --emit all flag writes events, findings, indicators and applicable enforcement decisions to ~/.numbat/records.ndjson. The README's hook trust note is worth reading twice. Requirements vary by agent and scope, and for the Codex user hook the definition has to be reviewed and trusted in /hooks on the CLI or Settings > Hooks in the app, including after a change such as adding --enforce. Hooks installed with --managed are trusted by policy. The README states directly that hook status verifies configuration, not execution or delivery. That is an honest limitation and it shapes how you should read a clean status output: it means the config is present, not that events are arriving. Confirm delivery by looking at the records file or the stdout stream.

Turning a detection into a block, and why nothing blocks out of the box

Blocking is opt-in at two levels. Enforce mode is disabled by default, and it applies only to rules marked enforce: true. Every shipped rule is monitor-only. The documented procedure is to copy the complete shipped YAML from rules/ into a controlled operator directory, keep the same id, add enforce: true, and bump the version. Then validate and install:

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

Enforcement is limited to supported synchronous pre-action hooks, which is the real constraint. A hook that fires after a tool call cannot prevent it, and an ingestion path that reads artifacts from disk is by definition retrospective. So the enforceable surface is a subset of the observable surface, and the coverage matrix is where that difference is recorded. The version-bump requirement on a modified rule is a sensible touch: it keeps a local enforcement policy distinguishable from the shipped rule of the same id when findings are reviewed later.

Record hygiene: redaction, previews, and case bundles

The README states that normal record output never includes a complete raw transcript, and that adding raw evidence files to a case bundle is opt-in. The hook event example carries a content_preview field rather than full content, and the sequence finding shows project_path_hash as a sha256 value instead of a path. Redaction is described as part of read-only artifact scanning. That design keeps the default output safe to ship to a log pipeline, at the cost of sometimes having less context than an investigator wants. The escape hatch is the case bundle: inventory and investigation tools produce per-session timelines and portable case bundles with SHA-256 manifests, and raw evidence is added deliberately. If your review process needs the original bytes, you are choosing to handle sensitive material, and the bundle manifest is what lets you show the evidence was not altered in transit.

Where numbat is the wrong tool, and what it is not replacing

numbat cannot see an agent that does not expose a supported hook, does not emit OTLP/HTTP logs, and does not leave parseable session artifacts. On such a host the tool has no input, and no amount of rule writing changes that. Enforcement has the same dependency plus a stricter one: it needs a synchronous pre-action hook, so an agent whose only integration point is a post-hoc log stream can be monitored but never blocked.

A second limitation is inherent to endpoint-local detection. Detection runs on the machine, which is the point, but it also means the machine is where the rules and the records live. The README describes optional HTTP delivery of records, so centralisation is possible, but the detection decision itself is local.

As an alternative, consider a network egress control layer such as a forward proxy or DNS filtering policy. The difference in approach is fundamental: a proxy decides based on the destination of a connection and can block anything that routes through it, but it sees no tool name, no session_id, no sub_agent, and no sequence across a secret read and a later upload. numbat sees the semantic context and the ordering, and in exchange it only sees agents it has an integration with. The two are complementary rather than competing, and picking one means picking which blind spot you can live with.

Maintenance cost, licence, and what to check before rollout

The maintenance surface is the rule set and the hook definitions. Rules are YAML with ids and versions, validated by numbat rules check --rules-dir, so a local policy directory can be reviewed and diffed like any other config. Shipped rules are monitor-only, which means an upgrade that changes a shipped rule cannot silently start blocking anything; enforcement only appears where an operator added enforce: true. That is a good default for a tool of this kind.

Hooks are the fragile part. The README warns that trust requirements vary by agent and scope and that a hook may need re-trusting after a change such as --enforce. Any agent-side update that moves, renames or re-scopes its hook mechanism will require reinstalling and re-trusting, and hook status will not tell you that delivery stopped. Budget for periodically confirming that records are still landing in ~/.numbat/records.ndjson.

The licence is Apache-2.0. That permits commercial use and modification and includes an explicit patent grant, with the usual obligations around preserving notices and stating changes. It is not a copyleft licence, so embedding numbat in a product does not force source disclosure of your own code. This is a description of the licence text, not legal advice; get counsel to review anything you redistribute.

Before rollout, verify three things in order. Confirm your agent and surface appear in docs/agent-coverage.md#matrix, since that document is described as authoritative. Run numbat scan and inspect what it actually finds on a representative machine. Then, if you intend to enforce, copy the rule you care about into a policy directory, run numbat rules check against it, and install with --enforce on a test host to confirm the pre-action hook fires synchronously for that agent. Until that last step succeeds, you have monitoring, not blocking.

Editorial conclusion

Adopt numbat if you already run agents that expose pre-action hooks or write session artifacts to disk and you want findings on the endpoint rather than shipping transcripts to a collector. Do not adopt it expecting blanket enforcement: blocking is off by default, every shipped rule is monitor-only, and enforcement depends on a supported synchronous hook for that specific agent. Before you install anything, open docs/agent-coverage.md#matrix and confirm your agent and surface are listed, then run numbat scan and numbat rules check against your copied policy directory to see what would actually fire.

Official sources

1. Issues
2. License: Apache-2.0
3. perplexityai/numbat on GitHub
4. README
5. Releases