halilneed
TREN

agent-blackbox

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 risk audit based on 26 readable rules and an undo map. It sends nothing anywhere.

Rules
26
Agents read
Claude Code, Codex CLI, Gemini CLI
Network calls
none
Dependencies
none
Licence
MIT

Example output

This is abridged from a real run of --scan --days 7 on the machine this site was built on. The session directories are renamed. Everything else is what the scanner printed. The scan made no network calls.

# 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 one specific finding. The rules live in one file you can open, and any rule you disagree with can be switched off with --ignore.

Install

# once
> /plugin marketplace add halilneed/plugins

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

# and try it
> /agent-blackbox:risk

The marketplace id is hailneed, which is why the install line ends in @hailneed.

  • Claude Code and Node.js 18 or newer.
  • No dependencies, no build step, no API key, no account.
  • It also runs standalone: node scripts/blackbox.mjs --scan --days 30 --md
  • For CI, --scan --out risk.json has a stable output format, so a build can fail when the risk score passes a threshold you set.

Commands

/agent-blackbox:timeline

The session turn by turn: what was asked, what ran, what broke and what changed. It also shows error chains, denied calls and where the time went.

/agent-blackbox:risk

An audit of what the agent was allowed to run: destructive commands, secrets that reached a transcript, permission and sandbox bypasses, and 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 a recovery and never restores anything on its own.

What it does and does not do

  • It makes no network calls. The scanner only reads files already on your disk, and blackbox.mjs contains no fetch and no sockets.
  • Secrets are masked before any report is written: API keys, JWTs, private-key headers and credentialed connection strings. Masking is on by default. --no-redact exists and is your call.
  • Thinking text never leaves the log. Only its count is reported.
  • There are 26 rules and no model judgement. rules.mjs is a pattern list you can read, and --selftest runs it against 33 fixtures without touching your data.
  • Unreadable sessions are counted in the source note.
  • MIT-licensed (LICENSE). No account, no signup, no telemetry.

Planned

A hosted version, agent-blackbox Cloud, is planned. The plugin stays free and local.

  • Team aggregation: every member’s reports in one dashboard.
  • Risk trend over time across the team’s machines.
  • Policy alerts and audit export: Slack or Telegram on violation, and an audit trail export shaped for ISO/SOC2 evidence.

To hear when it exists, subscribe on the writing page.