pip install agent-blackbox is a published package.Long gateway logs are difficult to read because an incoming message, a tool failure, and a later outbound flush may be far apart. Agent Blackbox’s HTML report groups those events into a timeline so an engineer can inspect the incident without manually scanning the entire log.
Generate a report from supported gateway logs
agent-blackbox demo
python agent_doctor.py export-html --minutes 180 --out exports/postmortem.html
# Alias for the same export path:
python agent_doctor.py visual --minutes 180 --out exports/postmortem.htmlThe demo uses synthetic evidence. The gateway export commands need supported local gateway logs; they do not manufacture an incident from an empty machine. Review the generated file before sharing it.
Read the timeline as evidence
- Filter for errors to identify candidate failures.
- Check incoming messages and outgoing flushes in order.
- Search for relevant identifiers without exposing private values.
- Compare the diagnosis with the underlying events.
- Record missing evidence alongside the conclusion.
A correlated flush is not delivery proof
The current analyzer uses FIFO timestamp correlation when stable message/response IDs are absent. Each flush is consumed once, so one outbound event cannot satisfy several inbound messages. It is still a heuristic: a matched flush does not prove that the intended recipient received the expected content.
Local HTML does not remove every risk
The visual export is designed for local review and escapes event text. The report may still contain sensitive contextual information after redaction. Keep raw source logs private and inspect what a recipient will actually see.
Use the right input adapter
Current Agent Blackbox also supports command recordings, Claude Code transcripts, Codex rollouts, OpenCode sessions, and a normalized JSON/JSONL event contract. These adapters feed diagnostics about missing or failed tool results and risky behavior. They should not be confused with a gateway-only visual timeline.
agent-blackbox analyze-events path/to/events.jsonl --format json --fail-on-incidentThe file must contain supported normalized events. Unknown schema versions, malformed records, unknown event types, and empty input fail visibly. The recording guide explains sanitized capture and its limits.
