Index of every page on this site: llms.txt
All skills
e2e-inc avatar

/unbox-ai

@a5d1788
by e2ee2e-inc/e2e14k stars
782
Run it yourself

Analyze AI agent trace files (*.trace.json - gateway or opencode exports, or .devtools/generations.json AI SDK devtools databases, even mid-run while the app writes them) without reading the raw JSON. Use when asked to inspect an agent run, find why it was slow or expensive, check cache efficiency, debug tool calls, or summarize what an agent did. All commands are read-only with bounded output - safe to run freely.

Use this Skill: https://skilld.dev/gh/e2e-inc/e2e/unbox-ai

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈107 tokens for metadata: the name and description. ≈1.4k when used: this file.

Description uses 5.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈429 characters, or 5.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

unbox-ai: explore AI traces from the CLI

Traces are too big to read raw (megabytes of duplicated context). unbox-ai normalizes them and answers questions with bounded output. Never cat or Read a trace file - always go through the CLI.

Run via npx unbox-ai (or node dist/cli/index.js in the unbox-ai repo).

Workflow

Always start wide, then drill:

unbox-ai runs <trace>           # multi-run sources only: one line per independent run
unbox-ai summary <trace>        # who/what/cost + one line per generation
unbox-ai tools <trace>          # per-tool usage: calls, failures, time, output size
unbox-ai events <trace>         # table: tokens, latency, cost per generation
unbox-ai event <trace> <idx>    # one generation: metrics + only its NEW messages
unbox-ai messages <trace> --grep <q> [--role r] [--event n] [--limit n]
unbox-ai get <trace> '<path>'   # exact raw value, e.g. events[3].messages[2].content
unbox-ai compare <a> <b>        # A/B: metric deltas + system prompt / tool-set diff
  • --json on summary/events/event/tools/messages for machine-readable output (unbounded - prefer the plain forms first).
  • --run <n|id> scopes any text command to one run of a multi-run source (AI SDK devtools databases hold many). Without it they see the whole file merged. Keep passing the same --run when following printed pointers - generation indexes are run-local.
  • Truncated output always prints the exact get invocation that returns the rest. Follow those pointers instead of guessing paths.
  • --grep accepts regex; invalid regex silently falls back to literal search.
  • tools --all lists every individual call with args.
  • compare answers "what changed between these two runs": token/cost/time deltas, a task diff (differing tasks make deltas misleading), per-tool usage deltas, then a line diff of the system prompt and the tool-set changes - added/removed names plus, per changed tool, what changed (description or schema). Two runs of one file: compare <trace> --run 0 --run 1 (first --run scopes A, second B). Diff output is bounded; --json has the full diff. --trajectory adds a content-aligned action table (* = differing step,
    • = no counterpart; alignment is LCS over tool sequences, so an extra step in one run offsets nothing) - the fastest way to see where two runs actually diverged.
  • unbox-ai view <trace> starts a localhost visualization - only offer this to the human; as an agent, stay on the read commands.

Reading the numbers

  • generation = one model request/response. segment = one conversation thread (resets and interleaved agents split threads).
  • caching NN% = input tokens that were a repeated, cache-eligible prefix (real cache reads when the trace reports them, else inferred from repeats).
  • cost - = the source reports no dollar amounts (AI SDK devtools traces); reason about tokens instead.
  • latency NN% prompt wait = share of model time spent re-reading input (TTFT). High = the run is prompt-bound; shrinking resent context cuts both cost and wall-clock.
  • re-paid ~N tokens = identical system prompt/tools re-processed because fresh conversations start from zero - a prompt-caching or one-conversation opportunity.
  • event shows only messages NEW in that generation; earlier context is in prior events of the same segment.

Analysis recipes

Cost hotspots (which segment/agent burns the money):

unbox-ai events <trace> --json | jq 'group_by(.segment) | map({seg: .[0].segment, model: .[0].model, cost: ([.[].cost] | add), in: ([.[].inputTokens] | add)}) | sort_by(-.cost)'

Retry loops (same tool + same args repeating = a stuck agent):

unbox-ai tools <trace> --json | jq 'group_by(.name + (.args|tostring)) | map(select(length > 2) | {call: .[0].name, args: .[0].args, times: length})'

Latency outliers: unbox-ai events <trace> and scan the latency column; drill into the outlier with event, and check its tool durations in tools --all (wait-style tools show their requested duration).

Failures: unbox-ai tools <trace> failed column, then messages --grep "error|failed" for the evidence trail.

Supported formats

Gateway exports ({events[]} with cumulative message snapshots), opencode session exports ({info, messages[{info, parts}]}), and AI SDK devtools databases ({runs[], steps[]}, usually .devtools/generations.json) are auto-detected - summary prints which. Unknown files fail with a readable error; do not retry with other commands.

Live AI SDK apps (devtools databases)

A project instrumented with @ai-sdk/devtools writes every AI SDK call to .devtools/generations.json in the app's cwd - analyze it with the commands above WHILE the app runs. Each command reads a fresh snapshot, so this is the way to debug an agent mid-flight:

unbox-ai runs .devtools/generations.json            # what ran / is running ([live])
unbox-ai summary .devtools/generations.json --run 2 # drill into one run
unbox-ai tools .devtools/generations.json --run 2   # its tool behavior
  • Always start with runs on these files and scope with --run; the unscoped view merges every run and its indexes shift as the app appends.
  • A run marked [live] (or a generation with latency 0.00s and no output) is still executing - re-run the command for updated state.
  • unbox-ai devtools serves a live browser viewer of the same file; only offer it to the human, as an agent stay on the read commands.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings1mo3 checks · Risk MEDIUM
  • Gen Agent Trust Hub1mo

    The skill instructs the agent to download and execute an external package via npx for analyzing AI trace files, which introduces a remote code execution vector. It also processes external data files that may contain indirect prompt injections.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: MEDIUM · 1 issue

Signed by skilld at a5d1788. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
metadata
{
  "internal": true
}

README badge

README badge for e2e-inc/e2e/unbox-ai