runlens

runlens is a Go CLI that reads a JSONL log of agent/tool execution events and reports success rate, latency (avg/p95), token usage, flaky tools, recurring error clusters, hot tool-to-tool transitions, and outlier events. Prefer invoking the runlens binary directly over re-implementing JSONL parsing or aggregation by hand — it already computes p95 latency, per-tool failure rates, and outlier classification consistently.

Workflow

1. Make sure runlens is available.

   • Install with brew install itamaker/tap/runlens, download a release binary from the Releases page of github.com/itamaker/runlens-skill, or build from a source checkout with go build -o runlens ..
   • Do not invoke bare runlens with no arguments — that launches an interactive Bubble Tea TUI and will hang a non-interactive/agent shell. Always use an explicit subcommand.

2. Identify the input trace file.

   • It must be JSONL (one JSON object per line). Each event has: timestamp, agent, tool, latency_ms, tokens_in, tokens_out, success (bool), and an optional error string.
   • examples/run.jsonl in this skill's folder is a good shape reference if the user hasn't supplied their own trace file.

3. Choose the subcommand based on what the user wants to know.

   • runlens summary -input <path>: aggregate stats only — total runs, success rate, avg/p95 latency, total tokens in/out, and a per-tool run/failure/latency breakdown. Use this for a quick health check or token/latency report.
   • runlens diagnose -input <path>: everything summary produces, plus flaky-tool detection, error clustering, top tool-to-tool transitions, and outlier events. Use this whenever the user asks "why did this fail," "what's flaky," or "what's slow."