Introduction
AI agents now run your shell, edit your files, and ship to prod—often with zero humans in the loop. The tooling explosion of 2026 made software agent-native… and produced exactly one new question:
"What did my agent actually do while I was away?"
AGENTBOX is the answer. Strap a flight recorder to any command or agent—no SDK, no code changes, no cloud—and get a tamper-evident tape of everything it did: every tool call, every file touched, every URL hit.
I recently came across this project and it solves a problem I didn't know I had. Let me break down why it matters and how you can try it in 10 seconds.
The Problem: Agents Have Root. Who's Watching?
If you've used Claude Code, Codex CLI, or any autonomous coding agent, you know the drill: you give it a task, it runs for a while, and then something breaks. Maybe it deleted a file, maybe it hit an unexpected API, or maybe it just did something… odd.
Traditional logging doesn't cut it. You need a forensic record—a black box that captures everything in a way that can't be quietly edited afterward.
That's exactly what AGENTBOX does.
What Is AGENTBOX?
AGENTBOX is a zero-dependency, 100% local flight recorder for AI agents. It wraps any command or agent and produces a session file (JSONL) containing every event: tool calls, shell commands, file operations, URLs hit, even human keystrokes.
The tagline says it all:
"
npm testfor your agent's behavior · tamper-evident · 100% local · zero dependencies"
Key Features
🎥 The Replay: Security Footage for Your Terminal
agentbox replay opens an interactive scrubber—like security footage for your terminal.
-
Timeline bar with markers:
▲tool call ·$shell ·✎file op ·ihuman input -
Play / pause / speed (1×–64×)—skip to
00:47.2, the moment it dropped the table -
Every keystroke the human typed is on the tape (
HUMANlines) -
--headlessrenders a static frame for CI, GIFs, and GitHub
🔒 The Tape Cannot Lie
Every event is hash-chained. Each line commits to the previous one:
{ i, t, type, data, prev, hash }
hash = sha256(prev ‖ i ‖ t ‖ type ‖ data)
Edit one line—even a single character—and agentbox verify pins the exact event:
$ agentbox verify
✗ hash mismatch at event 7 — event was tampered with or forged
That makes the session file evidence, not a log: post-mortems, compliance, "the agent did it / no it didn't" arguments in PRs—settled.
🛡️ Secrets Never Land on the Tape
Every string written to a session file is scrubbed before it is hashed and appended. The chain commits to the redacted form, so the original secret is not recoverable from the file, the receipt, or a shared clip. Default patterns catch API tokens, cloud keys, auth headers, private keys, and connection strings.
You can extend the redaction patterns via AGENTBOX_REDACT_EXTRA or project-local config.
Quickstart: See It in 10 Seconds
# 1. Watch a scripted agent get recorded
npx agentbox-cli demo
# 2. Wrap anything — your agent, a script, any CLI
agentbox wrap -- claude "refactor auth.js"
agentbox wrap --name eval-run -- python evaluate.py --suite prod
# 3. Read the tape
agentbox list # all sessions
agentbox receipt # newest session, one page
agentbox replay # scrub the footage
agentbox verify # tamper check
# 4. Share a moment, not a dump
agentbox clip --from 30 --to 75 # → self-contained .clip.html
# 5. Or skip the wrapper entirely — passive mode
agentbox init claude # hooks → every claude session, recorded
agentbox mcp -- npx -y @modelcontextprotocol/server-everything
No install, no config, no accounts. Sessions land in ./.agentbox/sessions/ next to your repo—commit them if you want receipts in git history.
Passive Mode: No Wrapper Needed
Wrapping is for flights you know about in advance. Adapters are for the ones you don't.
For Claude Code, you can merge hooks into your settings with a single command:
agentbox init claude # merges hooks into .claude/settings.json
agentbox init claude --local # .claude/settings.local.json instead
agentbox init claude --remove # clean uninstall
From the next session on, Claude Code quietly feeds every event to agentbox hook claude.
The Receipt: Real Output from agentbox demo
Every session ends with a one-page flight receipt. Here's real output from the demo:
⬢ M A Y D A Y R E C E I P T
┌──────────────────────────────────────────────────┐
│ session demo-deploy │
│ command node examples/fake-agen… │
│ started 2026-09-24 18:40:52 │
│ duration 5.4s │
│ exit code 0 (clean landing) │
├──────────────────────────────────────────────────┤
│ tool calls 7 │
│ · bash("git status --s… │
│ · write(src/deploy.sh … │
│ · bash("./deploy.sh --… │
│ … +4 more │
│ shell commands 1 │
│ · rm -rf /tmp/old-buil… │
│ files touched 2 · 1 written · 1 edited │
│ · src/deploy.sh wrote │
│ · config.yaml edited │
│ urls hit 1 │
│ output volume 808 B across 17 lines │
│ stderr lines 0 │
│ humans consulted 0 (unsupervised flight) │
├──────────────────────────────────────────────────┤
│ events recorded 19 │
│ tamper chain sha256 · intact │
└──────────────────────────────────────────────────┘
uneventful flight. the best kind.
Why This Matters
Agentic tooling is moving fast, and trust is the bottleneck. Before you let an agent run terraform apply or kubectl delete, you need to know you can audit exactly what happened—and prove it wasn't altered.
AGENTBOX fills that gap with a beautiful, minimal approach:
- No cloud dependency — everything stays on your machine
- No SDK integration — wrap any command, or use passive hooks
- Cryptographically verifiable — hash-chained events make tampering detectable
- Human-readable — receipts and replay make the data accessible, not just forensic
It's the kind of tool that should be in every agent operator's toolkit.
Getting Started
Head over to the repo and try the demo:
👉 github.com/arunsoman/agentbox
npx agentbox-cli demo
If you're running agents in production (or just want to know what they're really doing), give it a star and let the author know what you think.
Have you used AGENTBOX or a similar auditing tool for your agents? Share your experience in the comments below.
Top comments (0)