A Technical Guide to Rungraph for Agent Session Visualization

Practical Overview & Architecture

Rungraph is a zero-telemetry, local developer tool designed to convert existing agent session transcripts stored on your disk into an interactive, visual graph. The software maps orchestrators, subagents, and tool calls as nodes, while linking them with spawn and return edges. It also captures human interventions directly on the execution path. By leveraging Model Context Protocol (MCP), Rungraph provides your agent with direct access to the exact same execution graph, enabling natural language inquiries about past sessions right from your terminal.

The system architecture relies on vendor-neutral Intermediate Representations (IR) derived from local agent logs and SQLite stores. Rungraph processes transcripts from Claude Code, Codex CLI, Hermes Agent, opencode, and Cursor, handling them entirely on loopback. The server binds specifically to 127.0.0.1 and implements Host-header-guarding to prevent DNS-rebound attacks. Because all operations remain local, no execution data or prompts traverse external networks unless explicitly packaged into a shareable bundle by the developer.

Prerequisites & Installation Setup

Using Rungraph requires Node.js version 20 or higher for baseline operation. However, reading native SQLite stores utilized by Hermes Agent, opencode, and Cursor requires Node.js version 22.13 or higher. On older Node versions, these specific vendor runs are skipped and accompanied by a warning message, while all other compatible transcript formats continue to function normally. The tool operates without requiring extra runtime dependencies, and its frontend ships prebuilt inside the package.

Getting started requires no complex hook configuration or persistent wrapper scripts. You can instantly scan your local disk and launch the interactive web interface by executing a single command directly in your terminal:

npx rungraph

This command automatically discovers existing agent runs, spins up a local server, and launches your default web browser to render the interactive node-based dashboard.

Documented Implementation Workflow

To connect your AI coding agent with the visual graph, Rungraph provides dedicated Model Context Protocol integration commands. Registering the MCP server allows your model to query specific execution metrics, examine node details, and highlight failing steps directly in your open browser dashboard. The initial setup requires registering the server and verifying the integration via terminal commands:

npx rungraph mcp --install npx rungraph mcp --check

The bare install command delegates directly to each vendor's native add mechanism without modifying internal configuration files directly. Once configured, developers can query their agent using natural language to investigate tool failures, verify test executions, or track down file modifications across subagent tasks. For headless environments or script-based automation, Rungraph exposes a comprehensive command-line interface supporting structured JSON output formats for indexing, filtering, and querying execution graphs:

npx rungraph list --json npx rungraph graph <runId> --json npx rungraph find <runId> token.js --json npx rungraph serve --no-open

Known Limitations Tradeoffs & Error Scenarios

Transcript formats produced by various coding agents remain largely undocumented and unversioned. When vendors introduce new record types or structural changes, Rungraph cannot always interpret every single entry. Instead of masking incomplete data, the tool calculates coverage metrics—such as reading 95 percent of a run—and explicitly highlights unparsed record types within the signal strip. This design choice guarantees that incomplete parses are never silently treated as clean execution runs.

Security boundaries during export operations represent another critical tradeoff. Because session transcripts log file read operations verbatim, opening sensitive files like environment configurations exposes secrets inside the raw session logs. Rungraph export commands actively scan for high-confidence secrets, including AWS keys, GitHub tokens, and private key blocks, and halt execution when detected. Developers must resolve these warnings explicitly by utilizing flags such as --redact-secrets or --structure-only.

Who Should Use It & Production Fit

Rungraph is exceptionally well-suited for developers, maintainers, and engineering teams who heavily utilize AI coding assistants like Claude Code, Codex, or Cursor and frequently encounter complex, multi-step agent debugging loops. If you have ever struggled to answer why a particular file modification kept failing across multiple subagent iterations, Rungraph provides the granular visibility needed to trace prompts, tool inputs, error outputs, and human permission denials without digging through raw, unstructured log files.

Production engineering teams prioritizing strict local data privacy will find Rungraph's zero-network architecture highly compatible with strict compliance requirements. Because transcripts never leave loopback storage unless manually exported, teams can safely audit agent behavior, share sanitized run bundles via offline files, and maintain total control over sensitive environment variables and internal source code paths during collaborative troubleshooting sessions.