rungraph

Ve las ejecuciones de tu agente como un grafo. — fayzan123.github.io/rungraph incluye una ejecución real con la que puedes interactuar, directamente en la página.

Eso es rungraph observando la sesión en vivo que construyó esta función: la barra indica qué salió mal, y un clic ilumina los nodos a los que se refiere.

Tu agente de codificación ya ha registrado todo lo que hizo. rungraph convierte esas transcripciones en un grafo agéntico dirigido interactivo: orquestador, subagentes y herramientas como nodos; relaciones de creación/retorno como aristas; los momentos de cambio de rumbo (denegaciones, respuestas, reintentos) marcados en la ruta. Funciona de forma retroactiva, en cada sesión que aún está en tu disco: sin hooks, sin envoltorios, sin configuración, sin telemetría.

npx rungraph

Eso es todo el inicio rápido. Escanea ~/.claude/projects, inicia un servidor local y abre tu navegador. Elige una ejecución, incluyendo una que se esté ejecutando en este momento: el grafo crece en vivo mientras el agente trabaja (solo vigilancia de archivos).

El grafo también es algo con lo que puedes conversar: conecta el servidor MCP a tu agente de codificación y pregúntale sobre una ejecución — "¿por qué seguía fallando la edición en token.js?" — la respuesta llega a tu terminal, y el agente resalta los nodos exactos que está describiendo en el grafo abierto mientras responde. Consulta Pregunta a tu agente sobre una ejecución.

¿Nuevo aquí? docs/GUIDE.md te guía por todo: leer el grafo, qué significa cada señal, conectarlo a tu propio agente y qué hacer cuando algo parece estar roto.

Lo que ves

Las sesiones de agente dejaron de ser conversaciones hace tiempo. Son ejecuciones: un orquestador que crea subagentes, flujos de trabajo que despliegan revisores, herramientas que fallan y reintentan, un humano que ocasionalmente dice que no. rungraph dibuja esa estructura para que una transcripción de 4.000 líneas se convierta en algo que realmente se pueda leer:

• El tiempo fluye hacia abajo. Tus indicaciones son la columna vertebral; los agentes paralelos se despliegan en carriles lado a lado y regresan al turno que recogió su resultado.

• Los nodos de herramienta indican qué se ejecutó, no solo qué herramienta: Bash · npm test ×12, Edit · canvas.jsx, Grep · waitForURL. Las llamadas consecutivas de la misma herramienta se colapsan en un nodo para que un bucle de prueba-corrección no se convierta en una maraña.

• Haz clic en cualquier nodo para obtener la historia completa: indicación y respuesta para turnos; entradas, salidas, errores y tiempos de cada llamada para herramientas; la transcripción completa para subagentes. Los nodos de herramienta también muestran el porqué — la narración del propio agente justo antes de la llamada ("Ahora volveré a ejecutar las pruebas para comprobar…").

• Las intervenciones humanas son nodos de primera clase. Un permiso denegado, una pregunta respondida, una interrupción a mitad de turno: estos son los momentos en que una ejecución cambia de dirección, y las aristas que los siguen llevan el motivo (after permission denial, retry after failure, after Bash error).

• Las ejecuciones de flujo de trabajo (orquestaciones multiagente) aparecen como nodos únicos en los que se puede profundizar: su propio grafo, cajas de fase y todo, reintentos vinculados a los intentos que reemplazaron.

• Los tokens, duraciones y modelos anotan los nodos; totales de toda la ejecución en el encabezado.

Related MCP server: CodeGraph

Lo que salió mal

Un grafo que representa todo con el mismo peso no apunta a nada: una lectura de archivo de dos segundos y una espiral de reintentos de cuarenta minutos se ven idénticos. Por eso rungraph tiene una opinión. Deriva señales de la ejecución y las coloca en una barra sobre el lienzo — y en una ejecución limpia esa barra no ocupa altura, porque un marcador en el que no se puede confiar es peor que ningún marcador.

Haz clic en una señal y el grafo se enfoca: esos nodos se iluminan, todo lo demás se atenúa a un cuarto — atenuado, nunca oculto, para que la forma que ya memorizaste permanezca. Esc o un clic en el lienzo vacío lo limpia.

El mismo mecanismo de enfoque respalda todo lo demás que apunta a nodos:

• Buscar (/) — subcadena simple sobre etiquetas de nodos y los archivos que tocó cada nodo. Sin modelo, sin red, sin subproceso; filtra en el navegador.

• Archivos — los nodos de herramienta y agente llevan las rutas que tocaron, incluido el trabajo realizado dentro de subagentes, que es donde ocurre gran parte de la edición real. El inspector enumera cada archivo que la ejecución tocó con un conteo; haz clic en uno para ver exactamente qué pasos lo tocaron.

• Escalada en vivo — las señales se recalculan en cada actualización en vivo. Haz otra cosa mientras el agente trabaja; la barra solo se vuelve ruidosa cuando algo nuevo ha salido realmente mal.

Pregunta a tu agente sobre una ejecución

El panel es para ti; el servidor MCP es para tu agente. Son dos extremos de un mismo bucle, no dos productos.

npx rungraph mcp --install     # one time, then restart Claude Code
npx rungraph mcp --check       # is it working? prints exactly what to fix

Luego pregunta, en Claude Code, el tipo de preguntas que una transcripción puede responder realmente:

• ¿qué ediciones en mi última ejecución fallaron — y alguna quedó rota?

• ¿qué pasos tocaron src/auth.js, incluidos los subagentes?

• ¿qué encontró el agente "auditar módulo de autenticación"?

• ¿cuál fue el error real detrás de ese nodo rojo?

• ¿realmente ejecutó las pruebas, o solo dijo que lo hizo?

Claude llama a find_nodes / get_graph / get_detail y responde en tu terminal — tu modelo, tu sesión, completamente inspeccionable. Luego llama a focus_nodes, y el grafo que tienes abierto ilumina los nodos exactos sobre los que trata la respuesta — cambiando a la ejecución correcta, o abriendo una pestaña del navegador, si es necesario — y devuelve un enlace profundo que restaura el mismo resaltado para cualquiera a quien se lo pegues.

Tampoco tienes que inventar las preguntas: la parte inferior del inspector las escribe por ti, a partir de la ejecución que estás viendo, con un botón de copiar.

Nada está anclado, solicitado ni proxyado: rungraph contribuye el grafo, no la conversación. Las herramientas de solo lectura funcionan sin ningún servidor en ejecución.

Con más de un panel activo — el tuyo, más un paquete que alguien te envió (abajo) — el MCP los agrega: list_runs fusiona las ejecuciones de cada servidor, etiquetadas con su origen, y cada otra herramienta enruta por id de ejecución al panel que realmente muestra esa ejecución.

Compartir una ejecución

Una ejecución puede salir de la máquina — como archivo, en tus términos. Digamos que el agente de Bilal se desvió y tú podrías ayudar, o quieres mostrarle a un colega dónde se construyó realmente una función.

Bilal exporta. Ya sea desde el panel — compartir… en el panel de ejecuciones, marcar ejecuciones, revisar lo que está a punto de salir — o preguntando a su agente:

rungraph export --last 2 --as Bilal
# rungraph: export inventory (full content):
#   2 runs · 143 nodes · 12 of your prompts included
#   files touched: 24
# rungraph: wrote acme-2026-08-15.rungraph (412,882 bytes)

El inventario se imprime cada vez: la gente no se da cuenta de cuánto vive en una transcripción, por lo que la herramienta lo muestra antes de que salga. Y la exportación se bloquea si encuentra un secreto de alta confianza (claves AWS, tokens de GitHub/Slack/API, bloques de clave privada — patrones anclados, calibrados para falsos positivos casi nulos), listando exactamente dónde está cada uno. Resuélvelo con --redact-secrets (marcadores de posición, todo lo demás textual), --structure-only (forma del grafo, nombres de herramientas, archivos y tiempos — sin indicaciones, sin salidas), o --allow-secrets si son claves de prueba que has verificado.

El archivo es la transferencia. Envía el .rungraph a través de cualquier medio que ya confíes — Slack, AirDrop, un repositorio. rungraph nunca toca una red.

Tú lo abres.

npx rungraph open team-work.rungraph

Eso sirve el paquete en su propio panel efímero — no se copia nada en ningún lado; cierra el proceso y desaparece; guarda el archivo para reabrirlo en cualquier momento. Cada ejecución lleva su procedencia ("compartido por Bilal · team-work.rungraph"), y todo el bucle funciona sobre él: las señales se derivan en tu rungraph, y tu propio agente puede apuntar a las ejecuciones de Bilal — "¿qué salió mal en el paquete que me envió Bilal?" — junto a las tuyas.

Un paquete lleva la IR neutral de proveedor, por lo que una ejecución de Codex se exporta y abre de manera idéntica a una de Claude Code, y abrir un paquete no necesita adaptadores en absoluto. sharedBy es una cadena de visualización, no una identidad — confía en un paquete de la misma manera que confías en el canal por el que llegó.

Enlace a lo que ves. copiar enlace en el encabezado captura la vista actual — ejecución, nodo seleccionado, enfoque — como una URL; focus_nodes devuelve el mismo tipo de enlace, para que tu agente pueda darte algo que pegar en un PR o una incidencia. Los enlaces re-ejecutan su consulta al cargar (un enlace de búsqueda vuelve a buscar, un enlace de señal vuelve a derivar), y un enlace que llega al panel incorrecto ofrece un salto con un clic al que tiene la ejecución.

Navegación

La navegación es estilo Figma, diseñada para los grafos altos y delgados que producen las ejecuciones reales:

Un minimapa (abajo a la derecha) muestra toda la ejecución como una tira con un viewport arrastrable — los errores brillan como balizas rojas; haz clic en uno para saltar directamente al fallo. Las ejecuciones se abren con un zoom legible: las ejecuciones finalizadas en la primera indicación, las ejecuciones en vivo en la actividad más reciente, con el modo de seguimiento deslizando la vista a medida que llegan nuevos nodos.

Para agentes

Todo lo que la interfaz puede hacer, un agente de codificación puede hacerlo a través de la CLI — sin navegador, sin indicaciones, JSON en stdout, registros en stderr, códigos de salida 0 ok / 1 error / 2 no se encontraron ejecuciones. Pega esta sección en una indicación y un agente puede auto-servirse:

npx rungraph list --json
# {"runs":[{"runId":"claude-code:…:5822df8b-…","kind":"session","title":"Fix flaky auth test",
#           "project":"/home/you/dev/app","modifiedAt":"2026-08-11T16:31:06.055Z","active":true,…},…]}

npx rungraph graph 'claude-code:…:5822df8b-…' --json
# The full Graph IR for that run on stdout:
# {"irVersion":1,"meta":{"runId":"…","kind":"session","title":"…","totals":{"tokens":184230,"toolCalls":57,"agents":4},…},
#  "nodes":[{"id":"…","kind":"agent","label":"Investigate flaky test","status":"completed",
#            "files":["/home/you/dev/app/src/auth/token.js"],"tokens":{…}},…],
#  "edges":[{"kind":"spawn","from":"…","to":"…","label":"Investigate why auth.spec.ts flakes"},…],
#  "groups":[…],
#  "signals":[{"kind":"retry-storm","severity":"high","nodeIds":["…"],"label":"6 failed Edit calls",
#              "reason":"Edit failed 6× across 3 consecutive steps on token.js, …"}]}
# → an agent can read its own past runs: what it spawned, what failed, where the human said no.

npx rungraph find 'claude-code:…:5822df8b-…' token.js --json
# {"matched":4,"nodeIds":[…],"nodes":[…]}
# → narrow first. A big graph is 20k+ tokens of context to answer one question.

npx rungraph serve --no-open
# {"url":"http://127.0.0.1:4321"}   (server stays in foreground; same data over HTTP + SSE live tail)

La misma superficie está disponible como herramientas MCP — consulta "Pregunta a tu agente sobre una ejecución" arriba, o rungraph mcp --install.

El IR está versionado y documentado en SCHEMA.md. Es neutral respecto al proveedor, con dos adaptadores: Claude Code (sesiones, subagentes y ejecuciones de Workflow, bajo ~/.claude/projects) y Codex CLI (hilos de rollout y sus hilos de subagentes generados, bajo ~/.codex/sessions). Todo lo que está aguas abajo — incluidos los paquetes .rungraph — solo transporta el IR.

Privacidad

Todo es local. El servidor se vincula solo a 127.0.0.1, y cada solicitud está protegida por el encabezado Host, por lo que una página web hostil no puede hacer un reenlace DNS para acceder a tus transcripciones. rungraph no realiza solicitudes de red y no se comunica con ningún lugar.

Nada sale de tu máquina a menos que ejecutes rungraph export — un comando explícito que nombra ejecuciones explícitas, que imprime un inventario de lo que se incluye cada vez y se detiene de forma forzosa si se detectan secretos. El canal de transferencia del archivo resultante es tuyo, no de rungraph.

Cómo funciona

Claude Code escribe transcripciones JSONL bajo ~/.claude/projects — archivos de sesión principal, archivos por subagente y diarios de workflow con un manifiesto por ejecución. rungraph reconstruye el grafo de ejecución a partir de esos archivos a posteriori: los adaptadores convierten las líneas de transcripción en un IR versionado y neutral respecto al proveedor, y todo lo que está aguas abajo (interfaz web, CLI, API HTTP) consume solo el IR.

Está construido para sobrevivir transcripciones reales:

• Nunca una pantalla en blanco. Los tipos de línea desconocidos se omiten y se cuentan — si el formato de la transcripción es más nuevo que tu rungraph, obtienes un banner y un grafo, no un bloqueo. Una línea final a medio escribir (un agente en medio de una escritura) se tolera y se reintenta en el siguiente tick.

• En vivo sin hooks. La vivacidad proviene de observar los propios archivos de la ejecución; el grafo se actualiza mediante SSE con identificadores de nodo estables, por lo que los deltas se fusionan en lugar de redibujar.

• Ligero en tu máquina. El backend tiene cero dependencias en tiempo de ejecución (node:http, fs.watch y amigos). El frontend (Preact + elkjs) se envía preconstruido en el paquete — no hay paso de compilación en tu máquina.

Referencia de la CLI

rungraph                       scan, serve, open browser (human default)
rungraph list [--json]         run index, newest first
rungraph graph <runId>         Graph IR for one run (JSON on stdout)
rungraph find <runId> <query>  nodes whose label or files match a substring
rungraph serve [--no-open]     start server; prints {"url": …}
rungraph export <runId…>       write a shareable .rungraph bundle (see --help)
rungraph open <bundle…>        serve bundle files, ephemerally
rungraph mcp [--install]       MCP server on stdio; --install registers it once
rungraph mcp --check           verify the agent side end to end
  --project <path>             only runs for this project directory
  --port <n>                   preferred port (auto-increments if taken)
  --last <n>                   export: the n most recent runs of this project
  --scope <s>                  mcp --install: user (default) | project | local

Requiere Node ≥ 20.

Hoja de ruta

• Anotaciones — marcar nodos antes de exportar un paquete ("mira aquí primero").

• Preguntas entre ejecuciones — la atribución de archivos reside en el IR de cada ejecución, por lo que preguntar "¿qué más tocó este archivo?" entre ejecuciones necesita iteración, no una migración.

• Comparación de ejecuciones — comparar dos ejecuciones de la misma tarea.

• Estimaciones de costos — convertir los recuentos de tokens por nodo en dólares.

Contribuciones

Los adaptadores para otras CLI de agentes son lo más valioso que puedes añadir, y los informes de errores con un paquete --structure-only adjunto son los más útiles. CONTRIBUTING.md contiene el mapa del repositorio, los aspectos no negociables del proyecto (vale la pena leerlos antes de construir), y el flujo de trabajo de fixtures. Informes de seguridad: SECURITY.md, de forma privada por favor.

Licencia

MIT