CAcoming soon
X @tryblackboxai
v0.1 open source · zero dependencies · 100% local

The flight recorder
for AI agents.

Every model call, tool run, token and cent your app or coding agent spends, on one timeline. When something breaks, you see exactly where. One npm install, a dashboard on localhost, no account.

$npx blackbox-recorder
Get started Record Claude Code →
127.0.0.1:4500 · traces● REC
TRACES0
SPEND$0.00
TOKENS0
ERRORS0
support-agentrunning…
waiting for spans…
0dependencies
0command to start
0package size
0on your machine
// WHAT IT RECORDS

See the whole run. Not just the last error.

TIMELINE

Every step, nested

Model calls, tool runs, retrievals and your own functions on one waterfall, nested the way your code ran them. Streaming included.

COST

Every cent

Tokens and dollars per call, per run, per day, per model. Cache reads counted. Claude Code's own cost wins when it reports one.

ERRORS

Where it broke

Failed calls, tool errors and rejected tools light up red. Search across prompts, outputs and error messages.

TWO LINES

Wrap and go

// Anthropic or OpenAI
const claude = wrap(new Anthropic());
FEEDBACK

Scores & thumbs

score('grounded', 1) from code, 👍/👎 from the dashboard. Attach them to any run.

PRIVATE

Nothing leaves your machine

Recordings are plain JSON lines in ~/.blackbox. No account, no cloud, no telemetry, no Docker. Delete the folder and it's gone.

// CODING AGENTS

Put Claude Code and Codex on the record.

Coding agents speak OpenTelemetry. Point them at Blackbox and every session becomes one trace: your prompts, each model call with tokens and cost, every tool run, every tool you rejected.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4500
export OTEL_LOG_USER_PROMPTS=1  # optional
# ~/.codex/config.toml
[otel]
log_user_prompt = true
exporter = { otlp-http = { endpoint = "http://127.0.0.1:4500/v1/logs", protocol = "json" } }
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4500
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
# spans with gen_ai.* attributes become model calls
claude code session · $0.000
    you

    why did my last agent run fail?

    tool

    blackbox · recent_errors

    agent

    // MCP

    Your agent can read its own black box.

    Blackbox ships an MCP server. Add it once and ask in plain words: what failed, what it cost, what happened in that run.

    $claude mcp add blackbox -- npx -y blackbox-recorder mcp
    • recent_traces runs with status, time, tokens, cost
    • get_trace the step-by-step of one run
    • recent_errors what failed and why
    • spend cost by day and model
    • experiments eval scores
    // EVALS

    Changed the prompt? Prove it helped.

    Run your prompt or agent over a dataset, score every answer, compare runs side by side. Exact match, regex, JSON, length, or an LLM judge.

    import {evaluate, scorers} from 'blackbox-recorder';

await evaluate({
  name: 'support-v2',
  dataset: 'support-golden',
  task: ({input}) => agent(input),
  scorers: [scorers.contains(), scorers.llmJudge({client})],
});
    RUNCONTAINSJUDGE
    support-v1 · haiku0%0%
    support-v2 · sonnet0%0%
    support-v3 · sonnet + retry0%0%
    // UP IN 60 SECONDS

    Three steps. No signup.

    1. 01

      Start the recorder

      $npx blackbox-recorder

      Dashboard on http://127.0.0.1:4500. Try demo for sample runs.

    2. 02

      Wrap your client

      import {wrap, trace} from 'blackbox-recorder';
const ai = wrap(new OpenAI());

      Or point Claude Code / Codex at it. No code at all.

    3. 03

      Watch it fly

      Runs land live. Click one for the timeline, inputs, outputs, tokens and cost of every step. tail streams them in your terminal.

    // THE TOKEN

    $BBX on Pons. Revenue buys it and burns it.

    $BBXRobinhood Chain · launched on Pons
    —
    CONTRACTlaunching soon
    PRICE—
    MARKET CAP—
    BURNED—
    SUPPLY LEFT—
    Buy on PonsExplorer ↗
    BUY & BURN

    The furnace

    ETH sent to the burner can only ever become burned tokens: it buys $BBX (on the Pons curve, or the pool after graduation) and sends it to the dead address. No owner, no withdraw. Anyone can press burn.

    WAITING—
    BURNS—
    ETH SPENT—
    burner not deployed yet

    The tool is free and open source either way; the token is optional. Nothing here is financial advice. Memecoins are volatile and can go to zero.

    // FAQ

    Questions

    Where does my data go?

    Nowhere. Blackbox writes JSON lines to ~/.blackbox/events.jsonl on your machine and serves the dashboard on 127.0.0.1. Set BLACKBOX_DIR to move it, BLACKBOX_DISABLED=1 to pause.

    Does it slow my app down?

    One small file append per step. Recording never throws into your code: if it can't write, it skips.

    Which SDKs and models?

    Anthropic messages.create, OpenAI chat.completions and responses, streaming or not, plus anything that exports OpenTelemetry with gen_ai.* attributes. Costs use list prices; override any model in ~/.blackbox/prices.json.

    Python?

    Any app that exports OpenTelemetry (Python included, via OpenLLMetry or OpenInference) can send to /v1/traces as JSON. A native Python SDK is on the list.

    How do Claude Code sessions show up?

    Each session is one trace named "Claude Code session", with the prompt, every model call (tokens and the cost Claude Code reports) and every tool run. Turn on OTEL_LOG_USER_PROMPTS=1 to see prompt text.

    What does the token do?

    It's the community coin for the project, launched on Pons on Robinhood Chain. ETH sent to the BlackboxBurner contract buys it and burns it. The software doesn't need it.