00 hailneed suite · module 01 · flight recorder

What your agent
actually did —
and what can be undone.

Name: agent-blackbox
Author: hailneed

Claude Code, Codex CLI and Gemini CLI already write every session to your disk. agent-blackbox reads those logs and produces a turn-by-turn timeline, a transparent risk audit and an undo map — and sends nothing anywhere.

Install Source Cloud waitlist

26

Readable rules
3

Agents read
0

Network calls
0

Dependencies

01 Evidence

This is a real report.
Show, do not tell.

Abridged from an actual run of --scan --days 7 on the machine this site was built on. Session directories renamed; everything else is what the scanner printed. Nothing in it ever left that machine.

risk report — markdown out

# Risk report — last 7 days

Source note: 25 sessions scanned (all) · Risk score: 395 (high)

## Most triggered rules

| Rule                     | n  | Severity |
|--------------------------|----|----------|
| force-kill               | 21 | low      |
| fs-recursive-delete      | 20 | high     |
| hardcoded-credential     | 13 | medium   |
| write-outside-workspace  |  6 | medium   |
| git-hard-reset           |  2 | high     |
| secret-file-access       |  2 | high     |

## Findings (top of 36)

| Severity | Rule                | Session    | Evidence           |
|----------|---------------------|------------|--------------------|
| high     | fs-recursive-delete | `e7d88fce` | `rm -rf`           |
| high     | git-hard-reset      | `efb30291` | `git reset --hard` |
| high     | secret-file-access  | `2f51f1d8` | `.env`             |

Every finding names the rule that fired, the session it fired in and the matched text — so you can disagree with the specific thing, not with the tool. Rules live in one file you can open, and any rule you disagree with switches off with --ignore.

02 Install

One marketplace.
Then one command.

claude code

# once
> /plugin marketplace add hailneed/plugins

# the flight recorder
> /plugin install agent-blackbox@hailneed

# and try it
> /agent-blackbox:risk

Claude Code and Node.js 18 or newer.
No dependencies, no build step, no API key, no account.
Standalone works too — node scripts/blackbox.mjs --scan --days 30 --md
CI-ready — --scan --out risk.json has a stable output format; bind it to a threshold.

Marketplace manifest

03 Commands

Three readings
of the same record.

`/agent-blackbox:timeline`

The flight record, turn by turn: what was asked, what ran, what broke, what changed. Error chains, denied calls and where the time actually went.

`/agent-blackbox:risk`

A transparent audit of what the agent was allowed to run: destructive commands, secrets that reached a transcript, permission and sandbox bypasses, writes outside the workspace. Every high finding is verified against the transcript before it is reported — what cannot be verified is dropped.

`/agent-blackbox:undo`

Every file the agent touched, mapped to a recovery source — its own backup, git, or a reverse patch — plus a separate list of what cannot be undone at all. It proposes; it never restores anything on its own.

04 Trust

Claims you can
check in the source.

No network calls. The scanner only reads files already on your disk — blackbox.mjs contains no fetch, no sockets.
Secrets are masked before any report is written — API keys, JWTs, private-key headers, credentialed connection strings. Default on; --no-redact exists and is your call.
Thinking text never leaves the log. Only its count is reported.
26 rules, no model judgement — rules.mjs is a pattern list you can read, and --selftest proves it against 33 fixtures without touching your data.
Failure stays visible. Unreadable sessions are counted in the source note, never silently dropped.
MIT. LICENSE — no account, no signup, no telemetry.

05 Cloud

agent-blackbox Cloud
is in design.

The plugin stays free and local — that is a promise, not a phase. Cloud is the optional layer for people who need more than one machine:

Team aggregation — every member's recorder in one dashboard.
Risk trend over time — is the fleet getting safer or noisier?
Policy alerts & audit export — Slack/Telegram on violation; audit trail export shaped for ISO/SOC2 evidence.