convez.ai
AgenteDesenvolvimento WebIntermediário
everettjf

Coding Agent Visualizer

everettjf/coding-agent-visualizer

Visualize execuções de agentes de código com grafos, spans e análise de custos

Ver no GitHub
BomPluginScore · de 0 a 100

Ferramenta que transforma os logs JSONL gerados por agentes de código (Claude Code, OpenAI Codex) em visualizações interativas e analíticas. Exibe grafos de execução, waterfalls de spans, flame graphs de tokens, heatmaps de arquivos e dashboards de custos — tudo rodando localmente sem enviar dados para nuvem.

Instalação

$npx convez-ai everettjf/coding-agent-visualizer

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
20
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 4 meses
Versão
v0.1.4
Issues abertas
3
Contribuidores
3

Casos de uso

  • Debugar e entender o fluxo de execução de agentes de IA
  • Analisar custos de token por sessão e modelo
  • Rastrear quais arquivos foram modificados e com que frequência
  • Comparar performance e padrões entre múltiplas execuções de agentes

Veredito

Solução técnica madura e bem-executada para observabilidade de agentes de código. Preenche uma lacuna real: dados brutos de JSONL viram insights visuais acionáveis. Stack moderno (React 19, React Flow, D3) e abordagem local-first inspiram confiança.

README

A tradução para o português deste README ainda está na fila.

Coding Agent Visualizer

Coding Agent Visualizer

Turn the local session files of your coding agents into a beautiful, interactive map.

Bun React React Flow Tailwind Chart.js License: MIT PRs welcome

Live demo / landing page →


Coding agents like Claude Code and OpenAI Codex quietly record every session to disk as JSONL — messages, reasoning, tool calls, file edits and token usage. That data is a goldmine, but it lives in raw log files no one reads.

Coding Agent Visualizer reads those local files and renders them as an interactive execution graph, a distributed-tracing span waterfall, a token-cost flame graph, a file heatmap and an analytics dashboard — so you can actually see what your agent did, how it branched into sub-agents, which files it hammered, and where the tokens went.

No office mascots, no 3D robots. Just a fast, good-looking, useful lens on real agent runs. Everything runs locally — your transcripts never leave your machine.

Span waterfall — every event as a span, indented by call depth

Span waterfall

Execution graphToken-cost flameAnalytics
GraphFlameStats

✨ Features

🕸️ Execution graphConversation rebuilt as a graph and laid out left-to-right with dagre. Tool-only turns fold into chips, fragments reconnect into one spine, sub-agents branch off — a readable flow instead of an endless staircase.
🌊 Span waterfallThe distributed-tracing view (à la Jaeger / LangSmith / Phoenix): every event is a span, indented by call depth, positioned on a shared time axis, width = inferred duration.
🔥 Token-cost flameAn icicle (top-down flame graph) where width ∝ tokens and depth = call nesting — a token-heavy turn or sub-agent jumps right out. Built on d3-hierarchy.
⏱️ TimelineEvery event placed on a time track with role colors and previews — see the rhythm and gaps of a session.
🗂️ File heatmapWhich files the session touched and how often, colored cool→hot by edit frequency.
📊 Stats dashboardDuration, message/tool counts, input/output/cache tokens, a cumulative-token line, a token-breakdown doughnut and per-tool bars — all rendered with Chart.js.
💵 Real dollar costToken counts turned into USD under each model's published pricing (cache reads/writes priced separately) — per session on Stats, and aggregated total / per-model in analytics.
💬 TranscriptA clean, readable conversation view with collapsible tool blocks.
🔎 Full-text searchSearch across every session body — messages, reasoning and tool I/O — with snippets, not just titles.
⚖️ Compare sessionsDiff two runs metric-by-metric — duration, tokens, cost and tool usage with signed deltas — to see what changed when you tweaked a prompt.
📂 Open any fileDrag-and-drop (or pick) a transcript from anywhere; the source is auto-detected and rendered through every view.
🔍 Graph search & filtersHighlight matching nodes; toggle roles (hide reasoning/tools), flip layout horizontal/vertical.
🧩 Diff & inspectClick any node for full message / reasoning / tool I/O, with syntax-highlighted diffs for Edit/Write and one-click copy.
🗂️ Multi-sourceClaude Code, Codex, Gemini CLI, Qwen Code, OpenCode, Cursor and Cline today; a new agent is just one pluggable adapter away.
📝 AnnotationsFlag any turn and jot a private note (stored locally); export flagged turns as a Markdown review document.
🌐 Online demoA fully client-side demo — drop a transcript and explore it in the browser, nothing uploaded.
🔴 Live tailToggle LIVE to stream a session into the graph as the agent writes to disk — watch it think in real time.
📈 Cross-session analyticsAggregate every local session: token & cost over time, tool-usage trends, and per-source / per-model / per-project breakdowns.
🧬 Collapsible sub-agentsFold a whole sub-agent (sidechain) branch into its entry node — collapse one or all at once to focus the graph.
📤 ExportSave any session as Markdown or a self-contained, shareable HTML transcript — generated locally, nothing uploaded.

🚀 Quick start

Requires Bun (≥ 1.2). Install it if you haven't:

# macOS & Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

Run it without cloning:

bunx coding-agent-visualizer@latest   # → http://localhost:19876

Set a different port with PORT=4000 bunx coding-agent-visualizer@latest. After a global install (bun add -g coding-agent-visualizer@latest) you can launch it with the short cav command.

Or grab a standalone binary (no Bun needed):

Download the executable for your platform from the latest release and run it — the whole app and the Bun runtime are bundled into one file:

./coding-agent-visualizer-darwin-arm64   # → http://localhost:19876

Or clone for development:

git clone https://github.com/everettjf/coding-agent-visualizer.git
cd coding-agent-visualizer
bun install
bun dev          # → http://localhost:19876

The app auto-discovers sessions from:

  • Claude Code — ~/.claude/projects/<encoded-cwd>/*.jsonl
  • Codex — ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
  • Gemini CLI — ~/.gemini/tmp/<project-hash>/checkpoint-*.json
  • Qwen Code — ~/.qwen/tmp/<project-hash>/checkpoint-*.json (Gemini-compatible fork)
  • OpenCode — ~/.local/share/opencode/storage/{session,message,part}/…
  • Cursor — the IDE's state.vscdb SQLite (composer chats)
  • Cline — VS Code globalStorage …/saoudrizwan.claude-dev/tasks/<id>/

Pick a session from the sidebar and explore — or drop any transcript file onto the window to visualize one from outside those locations. Nothing is uploaded anywhere.

🧱 Architecture

A single Bun fullstack server (Bun.serve) serves both the React UI and a tiny local-data API — no separate backend, no database, no telemetry.

src/
├─ lib/
│  ├─ types.ts            # UnifiedSession / SessionNode — the shared model
│  ├─ stats.ts            # computeStats() + buildTrace()/buildHierarchy() derivations
│  ├─ pricing.ts          # model → published USD rates; token breakdown → cost
│  ├─ analytics.ts        # cross-session aggregation (cost/time, tool & model trends)
│  ├─ discovery.ts        # scan all sources (mtime-cached), search, upload, dispatch
│  └─ adapters/
│     ├─ claudeCode.ts    # uuid/parentUuid tree → nodes; tool calls; tokens
│     ├─ codex.ts         # rollout response_items → nodes
│     ├─ gemini.ts        # Gemini Content[] (checkpoints) → nodes; also Qwen Code (fork)
│     ├─ opencode.ts      # session/message/part JSON files → nodes
│     ├─ cursor.ts        # state.vscdb SQLite composer chats → nodes
│     └─ cline.ts         # Cline task JSON (Anthropic messages + UI events) → nodes
│  ├─ pricing.ts          # model → published USD rates; token breakdown → cost
│  ├─ search.ts           # inverted index (prefix + TF ranking) for full-text search
│  └─ parseUpload.ts      # browser-safe "detect + parse a dropped transcript"
├─ cli.ts                 # `bunx coding-agent-visualizer` launcher
├─ server/index.ts        # Bun.serve: UI + /api/sessions, /api/session, /api/analytics, /api/search, /api/parse
└─ frontend/
   ├─ App.tsx             # sidebar, search, Radix tabs, export menu, panel orchestration
   ├─ demo.tsx            # standalone client-side online demo (GitHub Pages)
   ├─ GraphView.tsx       # React Flow + dagre graph, collapsible sub-agents
   ├─ DetailPanel.tsx     # node inspector (message / reasoning / tool / diff / notes)
   ├─ ui.tsx              # role/tool/source colors + lucide icon mapping
   ├─ lib/
   │  ├─ charts.ts        # Chart.js registration + dark-theme defaults
   │  ├─ highlight.tsx    # tiny dependency-free syntax highlighter for diffs
   │  ├─ annotations.ts   # local per-node flags + notes (localStorage) + export
   │  ├─ export.ts        # session → Markdown / self-contained HTML
   │  └─ utils.ts         # cn() Tailwind class merge helper
   └─ views/              # Waterfall / Flame / Timeline / Files / Stats / Transcript / Analytics / Compare

The UI is Tailwind v4 (via bun-plugin-tailwind, wired in bunfig.toml) with Radix primitives and lucide icons; charts are Chart.js, the graph layout is dagre, and the flame hierarchy uses d3-hierarchy.

The unified model

Every adapter normalizes its raw format into one shape, so all views are source-agnostic and a new agent only needs a new adapter:

UnifiedSession {
  id, source, cwd, gitBranch, startedAt, endedAt,
  messageCount, toolCallCount, totalTokens, model,
  nodes: SessionNode[]          // DAG via parentId; tool calls are children
}

SessionNode {
  id, parentId, role: user | assistant | tool | reasoning | system,
  timestamp, isSidechain,       // isSidechain = Claude Code sub-agent branch
  text?, thinking?,
  tool?:   { name, input, result, isError, files[] },
  tokens?: { input, output, cacheRead, cacheCreation }
}

🔌 Adding a new source

  1. Create src/lib/adapters/<name>.ts exporting a parser that returns a UnifiedSession (see claudeCode.ts as the reference).
  2. Register its directory + dispatch in src/lib/discovery.ts.
  3. That's it — every view works automatically.

🛠️ Scripts

CommandDescription
bun devDev server with hot reload
bun startProduction server
bun run buildBundle the frontend to dist/ (also a CI build check)
bun run compileBuild a standalone single-file executable (no Bun needed to run)
bun testAdapter + library unit tests (runs against fixtures/)
bun run typecheckTypeScript check (tsc --noEmit)
bun scripts/shot.tsHeadless smoke test — opens every tab, reports runtime errors
bun scripts/capture.tsRegenerate the README / landing-page screenshots

All six adapters are covered by tests validated against realistic sample logs in fixtures/: Claude Code / Codex / Gemini / Cline in adapters.test.ts, and the non-JSONL OpenCode (fixture storage tree) and Cursor (in-memory SQLite) adapters in extra.test.ts. Pricing/cost (pricing.test.ts), cross-session aggregation, full-text search + upload detection (discovery.test.ts), the diff syntax highlighter and the Markdown/HTML exporters are unit-tested too. The Claude Code adapter is additionally verified against real local sessions (graph integrity: single connected tree, tool results linked, files tracked).

🔒 Privacy

Everything is read from your local disk and rendered in your local browser. There is no backend service, no account, and no network egress.

📄 License

MIT © everettjf

Ver o original no GitHub

Bom para

Relacionados