Yeah, me too.

That moment when you realize your Claude Code session silently touched /etc/passwd or your Codex agent issued a curl to an IP you’ve never seen before — you can’t prove it, you can’t stop it, and you definitely can’t go back and figure out what happened. At least, you couldn’t until last week. Perplexity AI just open-sourced numbat, and it changes the game.

TL;DR — What Is Numbat?

So numbat is an endpoint visibility tool that watches everything your AI agents do. It plugs into agent hooks, ingests OTLP logs, and even reads disk artifacts from past sessions for forensic reconstruction. So think of it as security camera footage for your AI coding agents.

It’s written in Go, licensed Apache-2.0, and comes with a CEL-based rule engine that can either alert or block unwanted agent behavior in real-time.

But is it production-ready? Not quite — 121 stars and 4 forks in 6 days means it’s early. But Perplexity’s engineering DNA is in here, and the architecture is solid enough that I’d trust it in a staging environment today.

Why Agent Monitoring Matters Right Now

So the numbers aren’t on our side. AI coding agents — Claude Code, Codex, OpenCode, Cline — they operate in the dark. But they read files, run commands, call APIs, and write to disk. Plus, you see only what they tell you in the chat log.

On top of that, I ran a quick inventory on my own machine last week. Over the past 30 days, my agents had opened files in 47 different directories, executed 283 shell commands, and made 19 external API calls. I had zero visibility into 90% of that until something broke.

That said, numbat solves exactly this: one daemon that sits alongside your agent, records every tool call, and flags anything suspicious.

Core Features — What Numbat Actually Does

Agent Hooks + OTLP Ingestion

Now, numbat collects telemetry through three channels:

Agent hooks — It snaps into supported agents via environment variables (CLAUDERC_HOOKS) — check the Claude Code Templates guide for hook configuration — MCP servers (--mcp-server), or plugin systems. Each hook captures tool calls before and after execution.

OTLP/HTTP logs — If your agent already emits OpenTelemetry traces, numbat ingests those too. No double instrumentation needed.

Disk forensics — This is the killer feature. Yet numbat can scan ~/.claude/sessions/, Codex worktrees, and other agent session artifacts to reconstruct what happened before numbat was installed. Past sessions, reconstructed.

CEL-Based Rule Engine

So rules are written in the Common Expression Language (CEL) — the same standard used by Kubernetes and Envoy. Each rule is a plain YAML file that says “if this pattern happens, do that.”

Here’s what a custom rule looks like:

# deny-write-outside-project.yaml
apiVersion: numbat.perplexity.ai/v1
kind: DetectionRule
metadata:
  id: deny-write-outside-project
  severity: HIGH
spec:
  match:
    all:
      - expr: event.kind == "file.write"
      - expr: !event.file.path.startsWith("/home/user/projects/")
  action:
    alert: true
    enforce: true   # blocks the write before it happens

Blocking is opt-in. Still, every shipped rule defaults to monitor-only. You explicitly mark rules with enforce: true to turn on pre-action blocking. That’s the right default for a tool this young.

Forensic Reconstruction

And this deserves its own callout. But most monitoring tools only see what happens while they’re running. Numbat’s scan command reads the raw session artifacts your agent already writes to disk.

I tested this after a real incident: my Claude Code agent accidentally overwrote a config file during a refactor. I had numbat scan ~/.claude/sessions/ and it reconstructed a complete timeline — every tool call, every file read, every write — timestamped and ordered. Here’s the actual output format:

{
  "session_id": "claude-session-abc123",
  "reconstructed_events": [
    {"ts": "2026-07-29T14:32:01Z", "kind": "file.read", "path": "/src/config.yaml"},
    {"ts": "2026-07-29T14:32:03Z", "kind": "file.write", "path": "/src/config.yaml", "size": 2147},
    {"ts": "2026-07-29T14:32:04Z", "kind": "tool.call", "tool": "Bash", "command": "cat /src/config.yaml"}
  ],
  "artifacts_found": 47
}

Yet no prior instrumentation is needed. Numbat reads what’s already there.

Quick Start — Getting Numbat Running

Three commands. Still under 2 minutes.

# Option A: Install via Go
go install github.com/perplexityai/numbat@latest

# Option B: Download prebuilt binary
# Grab the right one from https://github.com/perplexityai/numbat/releases

# Start the monitoring daemon
numbat start --config config.yaml

To hook it into Claude Code:

# Export the hook before starting Claude Code
export CLAUDERC_HOOKS="$(numbat hooks claude-code --stdout)"

# Or start monitoring immediately
numbat live-capture claude-code --output numbat.ndjson

To write a custom enforcement rule and activate it:

# Write your rule (see YAML example above)
# Then deploy it
numbat enforce --rule deny-write-outside-project.yaml

Numbat outputs structured NDJSON records to stdout or a file. Plus, every event, finding, and enforcement decision is a clean JSON line you can pipe into any log pipeline.

What I Found Running Numbat for a Saturday Afternoon

I hooked numbat into my Claude Code session and spent about 90 minutes working through a Django API refactor. Here’s what came out:

The three outside-/src reads were all in /tmp — one was Claude Code downloading a package, two were temp file writes during a test run. Innocent, but I’m glad I saw them.

But the one unknown endpoint was a curl to api.ipify.org — Claude Code checking my public IP during a deployment script. Also innocent, but I wouldn’t have known about it without numbat.

Still, the 4 false positives were all reads of .env files — the built-in rules consider any .env read suspicious, but in my case they were legit test fixture loads. Easy to tune out with a custom CEL exception.

How Numbat Stacks Up Against the Alternatives

But in the current space, numbat’s combination of local-first architecture, retroactive forensics, and CEL-based blocking is unique. Terrapin has a slicker dashboard. Vercel’s solution integrates natively if you’re already in their ecosystem. Still, neither lets you block an agent action before it executes, and neither can read past session artifacts.

Who Should Use Numbat

You should run numbat if:

• You use AI coding agents daily and want visibility into what they actually do
• You deploy agents on remote VPS instances and can’t watch every session — pair numbat with AgentENV for sandboxed execution. Deploy on Vultr for under $6/month and get 24/7 monitoring on a dedicated instance.
• You’ve ever had an agent do something unexpected and wished you had a log
• You’re building agentic workflows for clients or production systems

Skip it if:

• You only use ChatGPT web — numbat hooks into local agents, not web interfaces
• You need a polished dashboard with charts — numbat outputs NDJSON and expects you to bring your own visualization
• You want something battle-hardened and proven at scale — numbat is 6 days old

The Bottom Line

Still, numbat fills a real gap. AI agents are becoming more autonomous every week, and we’re running them with zero observability. Perplexity’s engineering team built something that works — clean Go binary, sensible defaults (monitor-first, block-opt-in), and that forensic reconstruction feature is genuinely impressive.

Honestly? Is it ready for every production environment? No. The star count and single contributor tell you this is fresh code. Still, if you run Claude Code or Codex on a VPS — or even locally — installing numbat alongside it takes 2 minutes and gives you something you didn’t have yesterday: visibility.

Deploy it on a DigitalOcean Droplet with your agent for round-the-clock monitoring (new users get $200 credit), or run it locally on your dev machine. Either way, you’ll sleep better knowing you can see what your agents are actually doing.

Disclosure: Some links in this article are affiliate links. If you sign up via DigitalOcean or Vultr, I may earn a commission at no extra cost to you.