{"slug": "show-hn-unbox-ai-visualize-your-ai-traces-like-a-javascript-bundle", "title": "Show HN: Unbox-AI Visualize your AI traces like a JavaScript bundle", "summary": "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.", "body_md": "[ Quickstart](#quickstart) |\n\n[|](#ai-sdk-devtools-live)\n\n**AI SDK DevTools**[|](#the-viewer)\n\n**Viewer**[|](#for-agents)\n\n**For Agents**[|](#skill-installation)\n\n**Skills**\n\n**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.\n\n- Bundle-analyzer-style treemap of input tokens: system prompt, each tool definition, each message.\n- Latency waterfall with TTFT, tokens, and cost per generation.\n- Deduplicated conversation view: only what is new in each generation.\n- Agent-safe CLI: capped output,\n`--json`\n\n, no accidental servers.\n\n```\nnpx unbox-ai trace.json\n```\n\nAgent 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.\n\n```\nnpx unbox-ai trace.json\n```\n\nThat's it. A local server starts and your browser opens the viewer. Works with\ngateway exports, opencode session exports, and AI SDK devtools databases (see\n[Trace Formats](#trace-formats)).\n\n```\n--json        machine-readable output\n--port <n>    server port (view default 4177, devtools default 4983)\n--no-open     start the server without opening a browser\n```\n\n`unbox-ai devtools`\n\nis a drop-in replacement for the\n[ @ai-sdk/devtools](https://www.npmjs.com/package/@ai-sdk/devtools) viewer:\nsame capture setup, this viewer instead. Instrument your app exactly as the\nAI SDK documents it:\n\n``` js\nimport { registerTelemetry } from \"ai\";\nimport { DevToolsTelemetry } from \"@ai-sdk/devtools\";\n\nregisterTelemetry(DevToolsTelemetry());\n```\n\nThen, instead of `npx @ai-sdk/devtools`\n\n, run:\n\n```\nnpx unbox-ai devtools\n```\n\nEvery `generateText`\n\n/ `streamText`\n\ncall streams into the viewer live - token\ntreemap, cache-hit attribution, latency waterfall, and diffed messages update\nas your agent runs. Every run gets its own entry in the sidebar run list, with\nnested agent runs (tools that call the AI SDK again) indented under their\nparent; the viewer follows the newest run until you pin an older one, and\nconcurrent streams stay individually visible. The static commands work on the\ndatabase file too: `unbox-ai summary .devtools/generations.json`\n\n.\n\nThe run list is not devtools-only - `unbox-ai view a.trace.json b.trace.json`\n\nopens several trace files (any mix of formats) as one run list.\n\n**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.\n\nToken attribution is estimated (character-proportional, scaled to the reported per-generation totals) and labeled as such.\n\nThe same binary is a bounded, read-only trace explorer - safe to allowlist:\n\n```\nunbox-ai runs trace.json             # multi-run sources: one line per run, then scope with --run\nunbox-ai summary trace.json          # totals + one line per generation\nunbox-ai events trace.json           # table: tokens, latency, cost, tool calls\nunbox-ai event trace.json 5          # one generation, new messages only\nunbox-ai tools trace.json            # every tool call: status, time, size, args\nunbox-ai messages trace.json --grep \"error\" --role assistant --limit 10\nunbox-ai get trace.json 'events[5].messages[10].tool_calls[0]'\n```\n\nEvery command caps its output; truncations print the exact `get`\n\ninvocation\nthat returns the rest. `--json`\n\ngives machine-readable output. When stdout is\nnot a TTY, bare `unbox-ai trace.json`\n\nprints the summary instead of starting a\nserver, so agents never spawn one by accident.\n\nAn agent skill ships in [ skills/unbox-ai/](/tester-army/unbox-ai/blob/main/skills/unbox-ai/SKILL.md) with the\nfull workflow and analysis recipes. Install it into your agent (Claude Code and\nfriends) via the\n\n[skills](https://skills.sh)CLI:\n\n```\nnpx skills add tester-army/unbox-ai -g\n```\n\nOr copy `skills/unbox-ai/`\n\ninto your agent's skills directory manually\n(e.g. `~/.claude/skills/unbox-ai/`\n\n). Prefer zero setup? Drop this in your\nAGENTS.md:\n\n```\nTo inspect AI trace files, use `npx unbox-ai` (read-only, bounded output):\n`unbox-ai summary <trace>`, then `unbox-ai event <trace> <idx>` to drill in,\n`unbox-ai messages <trace> --grep <re>` to search, and the printed `get`\npointers to fetch full values.\n```\n\n**Gateway exports**- a JSON object with`events[]`\n\nof`generation`\n\nentries carrying`model`\n\n,`metrics`\n\n(latency, tokens, cost),`available_tools`\n\n, and cumulative`messages`\n\nsnapshots. Conversation resets and multi-agent interleaving are detected and shown as segments.**opencode session exports**(`{info, messages[{info, parts}]}`\n\n) - 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[]}`\n\n,`.devtools/generations.json`\n\nwritten by`@ai-sdk/devtools`\n\n) - adapted automatically, and served live by`unbox-ai devtools`\n\n. 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.\n\nThere is no universal AI-trace standard yet; the closest are the OpenTelemetry\nGenAI semantic conventions, OpenInference, and OpenLLMetry (all span-based).\nAdapters for those are welcome contributions: implement `TraceAdapter`\n\n(detect + adapt) in `src/core/adapters/<name>.ts`\n\nand register it in\n`src/core/adapters/index.ts`\n\n- `src/core/adapters/opencode.ts`\n\nis the\nreference. `unbox-ai summary`\n\nprints which format was detected.\n\nPRs welcome, especially trace-format adapters. To develop locally:\n\n```\nnpm install\nUNBOX_TRACE=path/to/trace.json npm run dev   # viewer with live reload\nnpm run build                                 # dist/viewer + dist/cli\nnode dist/cli/index.js summary path/to/trace.json\nnpm run check                                 # lint (biome) + typecheck + tests (vitest)\n```\n\nMIT\n\nBuilt with ❤️ by **TesterArmy**", "url": "https://wpnews.pro/news/show-hn-unbox-ai-visualize-your-ai-traces-like-a-javascript-bundle", "canonical_source": "https://github.com/tester-army/unbox-ai", "published_at": "2026-08-25 13:57:45+00:00", "updated_at": "2026-08-25 14:17:49.137490+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "ai-agents"], "entities": ["Unbox-AI", "AI SDK DevTools", "@ai-sdk/devtools"], "alternates": {"html": "https://wpnews.pro/news/show-hn-unbox-ai-visualize-your-ai-traces-like-a-javascript-bundle", "markdown": "https://wpnews.pro/news/show-hn-unbox-ai-visualize-your-ai-traces-like-a-javascript-bundle.md", "text": "https://wpnews.pro/news/show-hn-unbox-ai-visualize-your-ai-traces-like-a-javascript-bundle.txt", "jsonld": "https://wpnews.pro/news/show-hn-unbox-ai-visualize-your-ai-traces-like-a-javascript-bundle.jsonld"}}