CLI tool
perplexityai/numbat avatar
perplexityai/numbat

Every shipped rule is monitor only, and all three examples stop mid-field

Visibility into AI agent activity on endpoints, with on-device detection, optional pre-action blocking, and forensic reconstruction.

1,165 stars128 forksGoApache-2.0

At a glance

What is it?
An endpoint agent that turns desktop, command line, IDE and gateway agent activity into one event model and evaluates it with a rule engine written in a common expression language, locally, with no agent to report to. The blocking story is deliberately unfinished, and the documentation is honest about the parts that verify configuration rather than behaviour.
Who is it for?
The design decision worth borrowing is that the detection runs on the endpoint and the same rule engine evaluates both live activity and old session files, so a policy you write once applies to history as well as to the next request. Two limits to plan around.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • perplexityai/numbat1,165 ★ · +130
Star history
Repository2026-09-112026-11-15
perplexityai/numbat1k1.2k

130 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Nothing blocks until you write the policy yourself

The capability list is specific about this. Blocking is opt in, it works only through pre-action hooks that the host actually supports and that fire synchronously, enforce mode is off by default, and every rule that ships with the tool is monitor only. The procedure for making a rule enforce is four steps: copy the complete shipped policy file into an operator directory you control, keep the same identifier so the rule you reviewed is the rule that runs, add the enforce flag, and bump the version. Then validate the directory and install with the enforce switch. The other documented install route is a single command:

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

That version bump is the detail that matters, because the version number travels into the decision records, so a decision citing an old version is a decision you can trace to a policy you can still find. Everything here is a deliberate refusal to ship a blocking policy in a tool that watches other people's agents.

The status command checks configuration, not behaviour

There is a callout about hook trust, and it is the most useful paragraph in the document. Requirements for trusting a hook vary by agent and by scope, so after installing one you are told to go and review and trust its current definition, either in a command location or in an application settings screen, and to do that again after any change to the enable flag. Hooks installed in a managed mode are trusted by policy rather than by review, which removes the step and the review with it. Then the sentence that keeps the whole tool honest: the status command verifies configuration, not execution or delivery. So a clean status means the hook is installed and defined as you intended. It says nothing about whether the agent is actually firing it, and nothing about whether records are arriving.

All three example outputs stop in the middle of a field

The page presents three worked examples, one per record type, and each one is cut off. The event example ends on an unterminated key for the session identifier. The finding example ends with a truncated observed command string that stops partway through a file path. The enforcement example ends with an unterminated array of rule identifiers. So the three records a reader needs most when reading a finding, the session it belongs to, the command that was proposed, and the full set of rules that fired, are all missing from the documentation. The surrounding prose is precise enough to compensate, mentioning a proposed destination and execution context, a replay of two pre-action callbacks, and an agent-specific deny response, but the JSON is the thing a reader will copy from. Each example also carries a parenthetical note explaining the setup, and those notes are where the two most important caveats live: one says the rule also runs during file scans, so the same finding can arrive from a live session or from a disk artefact, and the other says a finding does not prove the action completed.

A shell interpreter is in the dependency list and the page never mentions it

The module file lists a shell parser and interpreter among the direct dependencies, alongside the expression rule engine, a compression library, an embedded key value store, the YAML parser, the system package, two protobuf packages and a generated API package. The embedded store is the obvious one, being where records live, and the expression engine is documented. The shell library is not mentioned anywhere in the readme, and a tool that watches agents inevitably sees command strings, so the obvious use is to parse observed commands into structure for rules to match against. That is a reasonable inference and it is still an inference. The question to answer before deploying is whether anything in that path can be evaluated rather than only parsed, and the readme does not say. Nothing in the feature list mentions command parsing either, which is itself informative: the tool's stated job is to normalise activity into events and match them, and command handling is somewhere below that line.

Reconstruction works on agents you never instrumented

The forensic side is the reason the tool is more than a dashboard. It can reconstruct activity from on-disk session artifacts belonging to a supported agent, and the page is explicit that this needs no prior instrumentation, which is the whole point: you can point it at a workstation after the fact. The read-only commands make the same guarantee from the other direction, stating that the discovery and scan commands install no hooks and change no agent configuration, with a flag to limit discovery to a single named agent. Two cautions are stated in the prose. Sequence rules, which is how it catches a read followed by an upload, also run during those file scans, so the same finding appears whether it came from a live session or from disk. And a finding does not prove that either action completed, which is the sentence that keeps the output honest.

Records deliberately leave the raw transcript out

The record format is newline-delimited JSON with published schemas under a version directory, and the readme says events and findings keep references to their source rather than the source itself. Normal output never contains a complete raw transcript, and the artefact scanner redacts secrets it finds. Adding raw evidence files to a case bundle is opt in, so the conservative behaviour is the default and the exposed behaviour is a decision. Investigation tooling is built on that: per-session timelines, read-only agent discovery, and portable case bundles carrying a manifest of SHA-256 hashes, which is what makes a bundle something you can hand to someone else and have them check. The live monitor writes to a single file under the home directory, or to standard output, with delivery over HTTP available but not required.

One binary, two architectures, a patch-level toolchain floor

Distribution is a single file for the three desktop platforms on both processor families, built without the C library, and each release ships checksums. The toolchain requirement is stated at patch granularity, Go 1.26.6 or newer, and the module file pins the same patch release, so this is a floor at patch granularity rather than the language version alone. The repository also ships its dependency licences in a file of its own, which is more than most single-binary tools do, and the rules directory is part of the source tree rather than a downloadable bundle, which is what makes the copy-and-edit enforcement workflow possible.

Editorial conclusion

The design decision worth borrowing is that the detection runs on the endpoint and the same rule engine evaluates both live activity and old session files, so a policy you write once applies to history as well as to the next request. Two limits to plan around. Nothing blocks out of the box: every shipped rule is monitor only, and turning one into a blocking rule means copying the policy file, keeping the identifier, adding the enforce flag and bumping the version yourself, so the enforcement surface is one you wrote rather than one you inherited. And the status command checks configuration, not behaviour, so a green status tells you the hook is installed and tells you nothing about whether events are arriving.

Frequently asked questions

Does numbat block AI agent actions?

It can, but not out of the box. Every rule that ships with the tool is monitor only, and blocking works only through pre-action hooks the host supports and that fire synchronously. To enable it you copy a rule file into your own directory, keep its identifier, add the enforce flag, bump the version, validate the directory and install with the enforce switch.

Where does numbat store its records?

Newline-delimited JSON written under the home directory, or standard output, with optional delivery over HTTP. The readme says normal output never includes a complete raw transcript and that the artefact scanner redacts secrets, and adding raw evidence files to a case bundle is opt in.

Can numbat reconstruct activity from before it was installed?

Yes. Forensic reconstruction reads on-disk session artifacts from supported agents without prior instrumentation, and the read-only discovery and scan commands install no hooks and change no agent configuration.

What does the numbat hook status command verify?

Configuration only, not execution or delivery. The readme is explicit that a clean status means the hook is installed as you intended, and says nothing about whether the agent fires it or whether records arrive. Hook requirements also vary by agent and scope, so trust may need renewing after changes.

How do I install numbat?

Download a release for macOS, Linux or Windows on amd64 or arm64, with SHA-256 checksums in each release, or install with Go 1.26.6 or newer using the module install command. A static binary can also be built from a checkout with the C library disabled and paths trimmed.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. perplexityai/numbat on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/perplexityai-numbat.svg)](https://hysenlabs.com/projects/perplexityai-numbat)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/perplexityai-numbat.svg)](https://hysenlabs.com/projects/perplexityai-numbat)

Was this useful?