Show HN: Unbox-AI Visualize your AI traces like a JavaScript bundle

Unbox-AI, a new open-source tool, visualizes AI agent traces as interactive bundle-analyzer-style treemaps, latency waterfalls, and deduplicated conversation views, with a single command launching a local viewer. The tool reports that in a typical 16-generation trace, ~90% of input tokens are system prompts and tool definitions resent on every request, making traces unreadable raw. It also serves as a bounded, read-only trace explorer for coding agents and a drop-in replacement for the @ai-sdk/devtools viewer.

Quickstart quickstart | | ai-sdk-devtools-live AI SDK DevTools | the-viewer Viewer | for-agents For Agents | skill-installation Skills Trace Formats unbox-ai turns an AI agent trace into something you can read. One command opens a local visualization of the run; the same binary doubles as a bounded, read-only trace explorer for coding agents. - Bundle-analyzer-style treemap of input tokens: system prompt, each tool definition, each message. - Latency waterfall with TTFT, tokens, and cost per generation. - Deduplicated conversation view: only what is new in each generation. - Agent-safe CLI: capped output, --json , no accidental servers. npx unbox-ai trace.json Agent traces are unreadable raw. Every generation resends the full context, so a 16-generation trace holds hundreds of duplicated messages, and in a typical run ~90% of input tokens are the system prompt and tool definitions, paid again on every request. unbox-ai makes that visible. npx unbox-ai trace.json That's it. A local server starts and your browser opens the viewer. Works with gateway exports, opencode session exports, and AI SDK devtools databases see Trace Formats trace-formats . --json machine-readable output --port <n server port view default 4177, devtools default 4983 --no-open start the server without opening a browser unbox-ai devtools is a drop-in replacement for the @ai-sdk/devtools https://www.npmjs.com/package/@ai-sdk/devtools viewer: same capture setup, this viewer instead. Instrument your app exactly as the AI SDK documents it: js import { registerTelemetry } from "ai"; import { DevToolsTelemetry } from "@ai-sdk/devtools"; registerTelemetry DevToolsTelemetry ; Then, instead of npx @ai-sdk/devtools , run: npx unbox-ai devtools Every generateText / streamText call streams into the viewer live - token treemap, cache-hit attribution, latency waterfall, and diffed messages update as your agent runs. Every run gets its own entry in the sidebar run list, with nested agent runs tools that call the AI SDK again indented under their parent; the viewer follows the newest run until you pin an older one, and concurrent streams stay individually visible. The static commands work on the database file too: unbox-ai summary .devtools/generations.json . The run list is not devtools-only - unbox-ai view a.trace.json b.trace.json opens several trace files any mix of formats as one run list. Context treemap - input tokens attributed to system prompt, each tool definition, and each conversation message. Toggle per-generation vs cumulative size x times resent and tokens vs cost. Timeline waterfall - latency per generation with TTFT marks, tokens, cost. Generation detail - only the messages new since the previous generation, tool calls paired with their results, raw JSON one click away. Token attribution is estimated character-proportional, scaled to the reported per-generation totals and labeled as such. The same binary is a bounded, read-only trace explorer - safe to allowlist: unbox-ai runs trace.json multi-run sources: one line per run, then scope with --run unbox-ai summary trace.json totals + one line per generation unbox-ai events trace.json table: tokens, latency, cost, tool calls unbox-ai event trace.json 5 one generation, new messages only unbox-ai tools trace.json every tool call: status, time, size, args unbox-ai messages trace.json --grep "error" --role assistant --limit 10 unbox-ai get trace.json 'events 5 .messages 10 .tool calls 0 ' Every command caps its output; truncations print the exact get invocation that returns the rest. --json gives machine-readable output. When stdout is not a TTY, bare unbox-ai trace.json prints the summary instead of starting a server, so agents never spawn one by accident. An agent skill ships in skills/unbox-ai/ /tester-army/unbox-ai/blob/main/skills/unbox-ai/SKILL.md with the full workflow and analysis recipes. Install it into your agent Claude Code and friends via the skills https://skills.sh CLI: npx skills add tester-army/unbox-ai -g Or copy skills/unbox-ai/ into your agent's skills directory manually e.g. ~/.claude/skills/unbox-ai/ . Prefer zero setup? Drop this in your AGENTS.md: To inspect AI trace files, use npx unbox-ai read-only, bounded output : unbox-ai summary <trace , then unbox-ai event <trace <idx to drill in, unbox-ai messages <trace --grep <re to search, and the printed get pointers to fetch full values. Gateway exports - a JSON object with events of generation entries carrying model , metrics latency, tokens, cost , available tools , and cumulative messages snapshots. Conversation resets and multi-agent interleaving are detected and shown as segments. opencode session exports {info, messages {info, parts} } - adapted automatically. Real cache read/write tokens and per-tool execution times carry over. Note: opencode exports omit the system prompt and tool definitions, so token attribution assigns their weight to the conversation. AI SDK devtools databases {runs , steps } , .devtools/generations.json written by @ai-sdk/devtools - adapted automatically, and served live by unbox-ai devtools . Cache-read tokens carry over; the AI SDK reports no cost or TTFT, so those show as zero/absent. Tool definitions arrive without their JSON schemas, so the treemap's tools group reflects names and descriptions only. There is no universal AI-trace standard yet; the closest are the OpenTelemetry GenAI semantic conventions, OpenInference, and OpenLLMetry all span-based . Adapters for those are welcome contributions: implement TraceAdapter detect + adapt in src/core/adapters/<name .ts and register it in src/core/adapters/index.ts - src/core/adapters/opencode.ts is the reference. unbox-ai summary prints which format was detected. PRs welcome, especially trace-format adapters. To develop locally: npm install UNBOX TRACE=path/to/trace.json npm run dev viewer with live reload npm run build dist/viewer + dist/cli node dist/cli/index.js summary path/to/trace.json npm run check lint biome + typecheck + tests vitest MIT Built with ❤️ by TesterArmy