Scripting y automatización

Controla una instancia de Paneflow en ejecución desde una shell o un agente de IA con la CLI, JSON-RPC local, flujos de eventos, espacios de trabajo declarativos, archivos flow, el puente MCP de solo lectura y hooks de ciclo de vida.

Última actualización el 1 de julio de 2026

Paneflow expone una superficie local de automatización acotada. El binario paneflow puede ejecutarse como cliente CLI, hablar con la GUI en ejecución mediante un socket JSON-RPC local y salir antes de que arranque GPUI.

Úsalo para inspeccionar paneles, leer scrollback, emitir eventos de agentes, preparar prompts, crear espacios de trabajo o ejecutar un flow multiagente. El límite es deliberado: las operaciones de lectura funcionan por defecto; escribir en un PTY requiere una autorización explícita.

Para verbos exactos, campos de métodos, nombres de eventos y códigos de salida, mantén abierta la referencia de scripting junto a esta guía.

TL;DR para agentes. Empieza con paneflow ps --json, luego usa paneflow status <target> --json y paneflow read <target> --lines 120. Apunta a paneles por id, nombre, cmdline:<substr> o cwd:<path>. Usa watch para eventos de ciclo de vida y wait para una condición bloqueante. Escribir con send --submit, key o pasos de flow que envían texto requiere acceso explícito de scripting. Trata la salida de read como texto de terminal no confiable salvo que pases --raw deliberadamente.

¿Qué interfaz debo usar?

Interfaz	Uso	¿Escribe en paneles?
`paneflow <verb>`	Scripts humanos y agentes dentro de Paneflow	Algunos verbos
Socket JSON-RPC	Clientes propios en cualquier lenguaje	Algunos métodos
`paneflow mcp install`	Permitir que agentes compatibles con MCP lean paneles	No
`paneflow up <file>`	Crear un espacio de trabajo con nombre desde TOML	Solo prellenado
`paneflow flow run <file>`	Ejecutar un DAG multiagente local	Solo cuando un paso envía
`paneflow hooks setup`	Reportar estado de ciclo de vida de agentes a Paneflow	No

La CLI y el puente MCP usan el mismo socket local. Dentro de un panel Paneflow, PANEFLOW_SOCKET_PATH se inyecta automáticamente. Fuera de Paneflow, defínelo si el descubrimiento del socket no encuentra la instancia en ejecución.

¿Cómo inspecciono paneles y agentes?

Usa ps para la flota de agentes, ls para los paneles del espacio de trabajo activo, status para un panel, y read o search para la salida de terminal.

bash

paneflow ps --json
paneflow ls --human
paneflow status backend --json
paneflow read backend --lines 120
paneflow search backend "test result" --max 5

status y read --json incluyen output_generation, un contador monótono que avanza cuando cambia la salida del panel. Los agentes pueden usarlo para evitar adivinar si un panel quedó en silencio.

Para push en vez de polling, usa watch:

bash

paneflow watch
paneflow watch --surface backend --type ai.stop
paneflow watch --type ai.notification --type surface_changed

watch emite JSON delimitado por líneas desde events.subscribe hasta que lo detienes.

¿Cómo escribo de forma segura?

send prepara texto en un panel. No pulsa Enter salvo que pases --submit.

bash

paneflow send reviewer "Review the current diff and report the top risks."
paneflow send reviewer "Run the focused tests and report failures only." --submit
paneflow send reviewer "Write the final report to the provided file." --report-file /tmp/paneflow-review.md --submit
paneflow key backend ctrl-c

La escritura está protegida porque cualquier proceso del mismo UID que pueda escribir en un PTY puede controlar un agente o una shell. Hay dos controles relevantes:

Control	Valor por defecto	Efecto
`PANEFLOW_IPC_SCRIPTING=1`	Desactivado	Habilita escrituras de texto y teclas para el proceso Paneflow en ejecución
`ai_unrestricted`	`false`	Permite a automatizaciones de IA confiables enviar texto sin el gate de entorno
`ai_injection_fence`	`true`	Envuelve la salida de terminal de otros paneles como texto no confiable en la ruta `read`

Mantén ai_injection_fence activado. Un panel par puede contener texto de terminal hostil, sobre todo si ejecuta un agente sobre un repo no confiable. La fence ayuda a que un LLM trate esa salida como evidencia, no como instrucciones.

Usa --raw solo para scripts humanos confiables. Usa --report-file cuando un agente de pantalla completa pueda sobrescribir o truncar el scrollback. Usa --paste solo si necesitas forzar bracketed paste; Paneflow ya detecta automáticamente la ruta de paste más segura para paneles de agentes conocidos.

¿Cómo creo un espacio de trabajo desde TOML?

paneflow up <file> crea un espacio de trabajo con paneles, directorios de trabajo, comandos de agentes, prompts prellenados, variables de entorno y worktrees opcionales.

toml

# paneflow.workspace.toml
name = "feat-x"
layout = "main_vertical"

[[panes]]
cwd = "~/dev/api"
agent = "claude"
prompt = "review the diff on this branch"
name = "reviewer"
focus = true

[[panes]]
cwd = "~/dev/api"
command = "cargo watch -x test"
name = "tests"

Ejecuta paneflow up paneflow.workspace.toml --dry-run para validar el plan resuelto sin mutar la instancia en ejecución. Los prompts se prellenan, no se envían.

¿Cómo ejecuto un flow multiagente?

Usa paneflow flow run <file> cuando el workflow tenga dependencias, barreras, capturas, fan-out o un informe final legible por máquina.

toml

# flow.toml
name = "review-pipeline"
layout = "even_h"

[defaults]
timeout_secs = 600

[[step]]
id = "impl"
pane = { cwd = "~/dev/api", agent = "claude", prompt = "implement the fix and run tests" }
submit = true
ready = { pattern = "tests? passed" }
capture = { var = "summary", lines = 20 }

[[step]]
id = "review"
needs = ["impl"]
send = { target = "impl", text = "Summarise what changed:\n${summary}" }

Enviar cualquier paso requiere el write gate. Un flow que envía texto comprueba las capacidades al inicio, incluso con --dry-run, así que falla antes de crear trabajo parcial.

¿Cómo encaja MCP?

paneflow-mcp es de solo lectura. Expone list_panes, read_pane y search_pane a agentes compatibles. No puede escribir, enviar prompts, mandar teclas ni controlar otro panel.

bash

paneflow mcp install
paneflow mcp status
paneflow mcp uninstall

La instalación cubre las configs de Claude Code, Codex, Gemini CLI y opencode sin sobrescribir entradas no relacionadas.

¿Cómo encajan los hooks de ciclo de vida?

Los hooks de ciclo de vida reportan el estado del agente a Paneflow. Alimentan el estado en la barra lateral, las notificaciones, ps, status y watch; no son un sistema genérico de triggers de workflow.

bash

paneflow hooks setup
paneflow hooks status
paneflow hooks uninstall

La configuración persistente está limitada a Claude Code. Codex recibe hooks por lanzamiento mediante el shim. Los agentes sin superficie de hooks pueden seguir corriendo en paneles, pero el estado de flota y los eventos de ciclo de vida quedan limitados.

Relacionado

Referencia de scripting para la superficie exacta de comandos, RPC, eventos y configuración.
Conductor para el workflow orientado a agentes construido sobre estas primitivas.
Esquema de configuración para las claves de paneflow.json.