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

> Source: <https://github.com/tester-army/unbox-ai>
> Published: 2026-08-25 13:57:45+00:00

[ 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**