Visualizing AI Agent Transcripts with Rungraph

Correction: An earlier version described a different product and included unsupported commands. This replacement was checked against the project’s official documentation.

Practical Summary

Rungraph is a local developer tool that transforms AI coding agent transcripts into interactive, visual graphs. By parsing existing session data from specific directories used by agents like Claude Code, Codex, Hermes, opencode, and Cursor, it provides a way to inspect agent behavior, including tool calls, subagent activity, and human interventions. It operates entirely locally without telemetry, using an optional MCP (Model Context Protocol) server to allow your agent to query its own history and highlight relevant nodes in the browser-based dashboard. It is designed for developers who need to debug complex, multi-step agent workflows.

Core Functionality and Visualization

The tool visualizes agent runs as a directed graph where time flows downward. Prompts serve as the backbone, while parallel agent activity branches into lanes. Key features include:

• Tool Node Collapsing: Consecutive calls to the same tool are collapsed into a single node to prevent visual clutter, ensuring a test-fix loop does not become a complex hairball.
• Signal Detection: Rungraph automatically identifies issues such as retry storms, unresolved errors, human interventions, outliers, and course changes, displaying them in a signal strip above the graph.
• Interactive Inspection: Clicking any node reveals the full transcript, including prompts, responses, tool inputs/outputs, errors, and timing data.
• Focus and Find: Users can search for specific labels or file paths. Selecting a signal or search result focuses the graph on relevant nodes without hiding the rest of the context, ensuring the mental map of the run remains stable.
• Replay Mode: A replay feature allows users to scrub through the run, watching the graph evolve as the agent worked, with the ability to play or pause the sequence.

Prerequisites and Setup

Rungraph requires Node.js version 20 or higher. For specific agents like Hermes, opencode, and Cursor, Node >= 22.13 is required to utilize the built-in SQLite reader. The primary command npx rungraph initializes a local server that finds runs in vendor-defined directories (e.g., ~/.claude/projects, ~/.hermes/state.db) and opens a browser-based dashboard.

To enable agent-assisted debugging, you can optionally configure the MCP server:

npx rungraph mcp --install

You can verify the configuration using npx rungraph mcp --check. This allows your agent to call tools like find_nodes, get_graph, and focus_nodes to answer questions about its own history directly in your terminal. The agent can then call focus_nodes to light up the open dashboard, switching runs or opening a tab if necessary, and provide a deep link for collaboration.

Workflow and Sharing

Rungraph is designed for local-first privacy. It does not make network requests. When sharing runs, the export command creates a .rungraph bundle:

rungraph export --last 2 --as Bilal

The tool includes built-in security measures to block high-confidence secrets like API keys or private keys during export. Recipients can open these bundles using npx rungraph open team-work.rungraph to view the run in an ephemeral dashboard. Bundles carry a vendor-neutral IR, allowing a Codex run to open identically to a Claude Code one.

Limitations and Technical Constraints

Rungraph has specific constraints based on the agent type and environment:

• Cursor IDE: The adapter skips cloud-based agents, does not parse pre-_v:9 conversations, and cannot provide token totals as Cursor does not record them. Additionally, Linux and Windows paths for the Cursor IDE adapter are currently unverified.
• Transcript Formats: Because agent transcript formats are undocumented and unversioned, Rungraph reports coverage percentages. If a vendor introduces a new record type, the tool will report the percentage of the run it successfully interpreted rather than assuming a clean run.
• Data Handling: The tool is built to survive real transcripts; unknown record types are skipped and counted, and half-written last lines are retried on the next tick.

Who Should Use Rungraph

Rungraph is intended for developers who use AI coding agents and need to debug complex, multi-step workflows. It is particularly useful for teams or individuals who need to understand why a specific tool call or edit failed, audit agent behavior to verify if tests were actually executed, or share complex agent sessions with colleagues for collaborative debugging without exposing sensitive environment variables. For more information, visit the official repository at https://github.com/fayzan123/rungraph.