rungraph CLAUDE.md

rungraph — project instructions

Zero-setup, agent-first visualizer for AI agent runs: npx rungraph reconstructs Claude Code sessions + Workflow runs from ~/.claude/projects native transcripts (post-hoc, no hooks) into an interactive directed agentic graph, with live tail via file watching.

Current state

• Specs (source of truth, read before any work):
  • docs/superpowers/specs/2026-08-11-rungraph-design.md — v1 architecture.
  • docs/superpowers/specs/2026-08-11-frontend-navigation-design.md — canvas navigation.
  • docs/superpowers/specs/2026-08-12-signal-and-focus-layer-design.md — signals, focus, files, MCP.
  • docs/superpowers/specs/2026-08-20-opencode-adapter-design.md — the opencode adapter, src/sqlite.js, and the core IRNode.reverted field.
  • docs/superpowers/specs/2026-08-20-mcp-install-loop-design.md — src/clients.js, multi-client --install/--check, the launch resolver and the serve nudge. Read its Implementation amendments section: two of its ground-truth claims were falsified by re-probing during the build, and the code follows the probe, not the spec.
  • docs/superpowers/specs/2026-08-20-cursor-adapter-design.md — the Cursor adapter (one adapter, two stores), the key-name redaction rule in src/secrets.js, and the first genuine paste-tier client. Read its Implementation amendments and the §14 calibration record: the build deviated from the spec's letter in fifteen recorded places — four from the build, eleven from the 53-agent adversarial review after it.
  • docs/superpowers/specs/2026-08-23-session-replay-design.md — session replay: the additive call-level timing contract (callOffsets, tool endedAt), src/timeline.js, the replay bar, the moment-aware canvas/inspector/strip/minimap, playback as a fixed-speed time-lapse, the follow-camera, live detach, the t= deep link, the agent hook and the landing-page chip. Read its Implementation amendments: the playhead's stored identity gained a tie ordinal (k) because real runs put many events on one millisecond, and a leading untimed node materializes with its successor rather than at epoch zero.
• Session replay is implemented (2026-08-24): every adapter with a per-call clock emits callOffsets and tool endedAt (Cursor CLI has none and emits neither — asserted), the signals snapshot was byte-identical before and after (tool groups still carry no durationMs, so the outlier population did not move), and the dashboard's r key opens the bar. deriveSignals is untouched; replay only reveals signals at their completion.
• v1 and the signal & focus layer are implemented. Scanner, adapter, IR, CLI, server, live-tail watcher, the Preact frontend, deriveSignals, file attribution, the FocusSet spine, and rungraph mcp all ship.
• Five adapters ship, and five clients: claude-code, codex, hermes, opencode, cursor. The last three read SQLite through the shared src/sqlite.js and need Node ≥ 22.13; on older Nodes they self-disable with a structured warning, and only when a database actually exists to be skipped. Cursor is two stores under one adapter — the IDE's global state.vscdb (every project's conversations in one key-value table) and cursor-agent's per-chat store.db (a content-addressed blob store whose conversation order lives in a protobuf root snapshot) — because the rail should show one vendor for one product. Refs carry surface: 'ide' | 'cli'; the scan root array holds both roots and the adapter classifies each by shape. No Cursor field says whether a tool call succeeded (a refused command is status: completed), so outcome.js is a calibrated classifier shared by both surfaces.