Saltar al contenido
PaneflowPaneflow

Referencia de scripting

Verbos CLI, selectores, métodos JSON-RPC, frames de eventos, claves de configuración, specs de workspace, specs de flow, herramientas MCP, hooks y códigos de salida para automatización Paneflow.

Esta es la referencia compacta de Scripting y automatización. Nombra la superficie pública que un script humano o un LLM puede citar con precisión.

Verbos CLI

El binario paneflow intercepta estos verbos y sale antes de iniciar la GUI. Los verbos desconocidos salen con código de uso 2 en vez de lanzar la app silenciosamente.

VerboMétodo principal o motor¿Escribe en paneles?Uso
ls [--human]surface.listNoLista paneles en el espacio de trabajo activo
read <target>surface.readNoLee el scrollback de un panel
search <target> <pattern>surface.searchNoBusca en el scrollback de un panel
ps [--json]fleet.listNoLista agentes detectados entre espacios de trabajo
status <target> [--json]surface.statusNoLee el estado de agente de un panel
new [--name] [--cwd] [--space]workspace.createNoCrea un espacio de trabajo, en el espacio activo salvo que --space indique otro
select <index>workspace.selectNoSelecciona un espacio de trabajo y cambia a su espacio
split <h|v>surface.splitNoDivide un panel
focus <target>surface.focusNoEnfoca un panel y su espacio de trabajo
send <target> <text>surface.send_textGatePrepara o envía texto
key <target> <keystroke>surface.send_keystrokeGateEnvía una tecla que no somete
wait --match <sel>surface.read, events.subscribeNoBloquea hasta pattern, idle o ambos
watch [--surface <sel>] [--type <event>]events.subscribeNoEmite eventos de ciclo de vida y superficie
up <file>Motor de spec workspaceSolo prellenadoCrea un workspace declarativo
flow run <file>Motor flowGate para pasos que envíanEjecuta un DAG multiagente local
sessions [--json] [--follow]Flujo de sesiones del workerNoLee el estado de las sesiones de agentes, con o sin ventana

Alias aceptados por la CLI: list_panes apunta a ls, read_pane a read y search_pane a search.

Selectores

SelectorEjemploNotas
Id numéricopaneflow read 42Coincide exactamente con surface_id
Nombrepaneflow status backendMejor selector para scripts duraderos
cmdline:<substr>paneflow read cmdline:viteargv foreground completo en Linux, nombre de ejecutable en macOS y Windows
cwd:<path>paneflow read cwd:/home/me/apiCoincide con el directorio de trabajo del panel

Un selector que no coincide con nada o coincide con varios paneles sale con código 3, salvo comandos que aceptan explícitamente múltiples coincidencias como send --broadcast, wait --any y wait --all.

Códigos de salida

CódigoSignificado
0Éxito
1Fallo runtime: instancia inaccesible, panel cerrado, gate rechazado o error de handler
2Error de uso CLI
3Objetivo no encontrado o ambiguo, o send rechazó un agente de destino que espera una decisión o salió del primer plano
4Timeout de wait o timeout de ready en flow

Gates de escritura

La lectura está permitida por defecto. Las escrituras se separan por capacidad:

OperaciónGate
send sin --submitPANEFLOW_IPC_SCRIPTING=1 o ai_unrestricted
send --submitPANEFLOW_IPC_SCRIPTING=1 o ai_unrestricted
keyPANEFLOW_IPC_SCRIPTING=1
send --scope all, key --scope all, flow run --scope all desde dentro de un panelPANEFLOW_IPC_ORCHESTRATION=1
session.input del host desde un cliente de controlPANEFLOW_IPC_SCRIPTING=1
session.create del host desde un cliente de control con comando, prompt o envPANEFLOW_IPC_ORCHESTRATION=1
session.create del host desde un cliente de control, en otro casoPANEFLOW_IPC_SCRIPTING=1
Paso flow con submit = trueCapacidad scripting reportada por system.capabilities

send no añade carriage return salvo que --submit esté presente. key rechaza teclas que someten como enter, ctrl-m y ctrl-j. Un payload único de surface.send_text está limitado a 64 KiB.

Claves de configuración relevantes:

ClaveValor por defectoSignificado
ai_unrestrictedfalsePermite a automatizaciones de IA confiables enviar texto sin el gate de entorno
ai_injection_fencetrueEnvuelve el texto de surface.read en una envoltura de terminal no confiable
submit_paste_delay_ms70Retardo base entre bracketed paste y el carriage return de envío
terminal.envningunoVariables de entorno inyectadas en nuevos terminales

Campos de lectura

paneflow read <target> --json y surface.read crudo devuelven:

CampoSignificado
textTexto de scrollback, fenced por defecto
linesNúmero de líneas devueltas
total_linesTotal de líneas retenidas
eofSi la lectura llegó a la línea retenida más antigua
output_generationContador monótono avanzado por la salida del panel

Valores por defecto y límites: lines vale 200 por defecto y se limita a 1-4000. offset parte del final del buffer. Un offset fuera de rango es un error invalid-params.

El parámetro JSON-RPC fenced usa ai_injection_fence por defecto. El flag CLI --raw pasa fenced: false.

Campos de estado de agente

paneflow ps --json devuelve {"agents":[...]}. paneflow status <target> --json devuelve un objeto de estado.

CampoSignificado
pidId de proceso del agente, si se conoce
toolFamilia de agente como claude, codex, opencode o gemini
statethinking, waiting_for_input, finished, errored, stalled, idle o unknown_running
hookedSi el lanzamiento actual informa mediante hooks de ciclo de vida que instala Paneflow; un hook de un lanzamiento anterior nunca cuenta
state_seqContador por sesión que aumenta en cada transición de estado, en status
reasonRazón de detección, incluido no_hook
surface_idId del panel
surface_nameNombre del panel
workspaceÍndice del espacio de trabajo
active_tool_nameHerramienta que se está ejecutando dentro del agente
messagePrompt o texto de permiso en espera
last_resultResumen del último turno, si está disponible
waiting_msTiempo pasado esperando input
idle_msTiempo desde la última actividad observada
output_generationContador de salida del panel, en status; se omite si es desconocido

Una flota vacía es {"agents":[]} con código de salida 0. Un panel sin agente rastreado devuelve estado idle, no un error.

Spec workspace

paneflow up <file> lee una spec workspace TOML.

Campo top-levelTipoValor por defectoNotas
namestring"Workspace"Título del espacio de trabajo
spacestringespacio activoNombre del espacio (sin distinguir mayúsculas y minúsculas) o id; Default designa el espacio predeterminado
layoutstring"even_h"even_h, even_v, main_vertical o tiled
port_baseinteger3000Base para la asignación ${port_offset}
[[panes]]arrayrequeridoUna entrada por panel
Campo de panelTipoValor por defectoNotas
cwdstringningunoDebe existir tras expansión y canonicalization
agentstringningunoNombre de launcher de agente, mutuamente exclusivo con command
commandstringningunoComando crudo, mutuamente exclusivo con agent
promptstringningunoPrellenado en la entrada de un agente, nunca enviado por up
focusboolfalseDa foco inicial a este panel
envtableningunoSe fusiona sobre terminal.env; soporta ${port_offset}
namestringningunoNombre selector estable
worktreestringningunoNombre de rama para un worktree gestionado bajo la raíz worktrees.dir (ver el esquema de configuración)
fromstringHEADRama o commit desde el que parte la rama del worktree cuando up lo crea
copy_envbooltrueCopia las entradas del .worktreeinclude del repositorio al worktree, o los .env* de primer nivel y AGENTS.override.md sin ese archivo
setupstringningunoComando ejecutado antes del lanzamiento
setup_timeout_secsinteger300Timeout de setup
worktree_teardownstring"auto"auto elimina worktrees limpios al cerrar; keep los conserva

${port_offset} solo se sustituye dentro de valores env. Las claves desconocidas son errores. La creación de workspace valida rutas antes de crear paneles.

Spec flow

paneflow flow run <file> lee una spec flow TOML y la ejecuta contra la instancia Paneflow actual.

CampoTipoNotas
idstringId de paso requerido y único
needsarrayDependencias; en foreach, espera todas las instancias
foreacharrayFan-out, una instancia por item
paneinline tableCrea un panel usando campos de panel workspace
sendinline table{ target, text, submit? }; requiere una dependencia
readytable{ pattern, timeout_secs? }; barrera regex
capturetable{ var, lines }; captura 1-500 líneas después de ready
submitboolEnvía el prompt de un panel creado; requiere acceso scripting

Variables:

VariableAlcance
${item}Pasos foreach: cwd, name, worktree, env, send.target, ready.pattern, prompts y textos
${var}Valores capturados dentro de send.text y pane.prompt que se envía
${var.<item>}Capturas de un grupo foreach

El runner valida claves desconocidas, dependencias faltantes, ciclos de dependencias, regex inválidas, capturas indefinidas, presupuesto de paneles y timeouts faltantes antes de ejecutar. Ctrl-C detiene el bucle de orquestación; los paneles creados permanecen en Paneflow.

Conexión JSON-RPC

PropiedadValor
Endpoint Linux$XDG_RUNTIME_DIR/paneflow/paneflow.sock; si XDG_RUNTIME_DIR no está definida o no es un directorio con permiso de escritura, $TMPDIR, y si no, ~/.cache/run
Endpoint macOS$TMPDIR/paneflow/paneflow.sock, y si no, ~/Library/Caches/run; XDG_RUNTIME_DIR se ignora
Endpoint Windows\\.\pipe\paneflow
FramingJSON-RPC 2.0 delimitado por líneas
Modelo de peticiónUna petición por conexión, salvo events.subscribe
Confianza localMismo usuario únicamente; sin listener de red, sin token, sin TLS
BackpressureLímite de conexiones y colas de eventos acotadas devuelven errores estructurados o frames dropped

Sondea capacidades en runtime:

bash
printf '%s\n' '{"jsonrpc":"2.0","method":"system.capabilities","params":{},"id":1}' \
| nc -U "$PANEFLOW_SOCKET_PATH"

Métodos JSON-RPC

MétodoParamsRetorno o notas
system.ping-Check de vida
system.capabilities-{scripting, methods[]}
system.identify-{name, version, protocol}
workspace.list-Espacios de trabajo con índices globales, títulos y space: {id, name}, o null para el espacio predeterminado
workspace.current-Espacio de trabajo mostrado, con su space
workspace.createname?, cwd?, layout?, space?Crea un espacio de trabajo; space es un nombre (sin distinguir mayúsculas y minúsculas) o un id, y vale el espacio activo cuando falta; uno desconocido se rechaza con unknown space: <value>
workspace.selectindexCambia de espacio de trabajo, y a su espacio cuando está oculto
workspace.closeindexCierra un espacio de trabajo
workspace.upname, layout, panes[], space?Spawn declarativo usado por up y raíces flow; space como en workspace.create
workspace.restore_layoutlayoutAplica un árbol layout
surface.list-{surfaces:[{surface_id,name,title,cwd,cmd,workspace,space}]}
surface.readsurface_id, lines?, offset?, fenced?Scrollback y output_generation
surface.searchsurface_id, pattern, max_matches?Coincidencias substring case-insensitive
surface.renamesurface_id, nameRenombra o borra el nombre de un panel
surface.focussurface_idEnfoca panel y espacio de trabajo
surface.statussurface_idEstado de agente para un panel
surface.send_textsurface_id, text, submit?, paste?Escritura de texto PTY con gate
surface.send_keystrokesurface_id, keystrokeTecla no submit gated por env
surface.splitdirection, surface_id?, cwd?, command?, prompt?, env?, name?, managed_worktree?Divide un panel
tmux.compatteam, surface_id, argv, scope_session?Comando tmux desde un panel de equipo de Claude Code; team es el token que Paneflow dio a los paneles de ese equipo, y la respuesta es {stdout, stderr, exit}
fleet.list-Snapshot read-only de la flota
events.subscribesurfaces?, types?Stream persistente de eventos delimitado por líneas

Los métodos de ciclo de vida ai.* ya no se aceptan en el socket de la app; los eventos de ciclo de vida vienen del reporter paneflow-ai-hook, y events.subscribe sigue entregando eventos ai.*.

Los fallos estructurados usan envolturas JSON-RPC error: -32602 invalid params, -32601 gated method, -32001 permission y -32000 backpressure. Algunos errores de validación legacy aún llegan como {"error":"..."} dentro de result; los clientes deben tratar ambas formas como fallos.

Eventos

paneflow watch y events.subscribe crudo emiten JSON delimitado por líneas. El primer frame confirma la suscripción.

Tipo de eventoSignificado
subscribedSuscripción confirmada
ai.session_startLa sesión de agente empieza
ai.prompt_submitSe envía un prompt
ai.tool_useEl agente reporta uso de herramienta
ai.notificationEl agente pide input o permiso
ai.stopEl turno del agente se detiene
ai.exitEl proceso del agente sale
ai.session_endLa sesión de agente se cierra
surface_changedEl output_generation del panel avanzó
heartbeatKeepalive idle
droppedEl subscriber se retrasó y se descartaron eventos

Después de un frame dropped, resincroniza con paneflow ps --json o paneflow status <target> --json.

Puente MCP

paneflow-mcp es un servidor MCP stdio sobre el mismo socket Paneflow.

HerramientaParamsRetorno
list_panes-Paneles con surface_id, name, title, cwd, cmd, workspace
read_panetarget, lines?, offset?Texto de scrollback
search_panetarget, pattern, max_matches?Líneas coincidentes
write_panetarget, text, submit?approval_pending hasta que una persona permite el par, después el resultado de la entrega; con submit, también started y state

write_pane es la única herramienta que escribe, y solo después de que una persona permite ese par de sesiones de agente en Paneflow; la guía de automatización describe sus controles. Ninguna herramienta envía teclas, enfoca ni divide paneles. La salida de terminal devuelta está fenced como datos no confiables.

Hooks de ciclo de vida

paneflow-ai-hook lee JSON de evento en stdin, envía un evento de ciclo de vida (ai.stop, ai.notification, etc.) al host local y sale con 0 para que una instancia Paneflow detenida no rompa el agente. Los hooks llevan la identidad del agente y los metadatos de su sesión a ps, status, watch y paneflow sessions; el estado del turno viene de OSC 7501.

ComandoEfecto
paneflow integrations listLista los runtimes que tienen instalador y su estado
paneflow integrations install <runtime>Instala los hooks de claude-code (o claude) o codex y registra el servidor MCP paneflow
paneflow integrations remove <runtime>Quita solo los handlers de Paneflow; un handler propio en el mismo grupo de hooks se conserva
paneflow hooks setupInstala cada runtime detectado que tiene instalador
paneflow hooks uninstallQuita las integraciones y la entrada MCP paneflow
paneflow hooks statusImprime una línea <runtime>: <state> por runtime; siempre sale con 0

Los hooks se instalan una vez por máquina, desde la CLI o Settings > Agents. Los hooks de Claude Code van a $CLAUDE_CONFIG_DIR/settings.json (por defecto ~/.claude/settings.json), los de Codex a $CODEX_HOME/hooks.json (por defecto ~/.codex/hooks.json), y terminan de inmediato fuera de un panel de Paneflow. Los demás agentes no tienen instalador: siguen ejecutándose, se detectan a partir de su proceso y solo obtienen un estado de turno cuando lo informan mediante OSC 7501.

Worker y sesiones

El estado de los agentes vive en un worker por home, iniciado como paneflow serve run. Corre separado, uno por PANEFLOW_HOME, reduce el estado que cada sesión declara mediante OSC 7501 a un único estado, reconstruye ese estado desde el disco cuando se reinicia y nunca toca una shell en marcha. status, send --submit y wait --idle leen el estado reducido desde el worker haya o no una ventana abierta; paneflow sessions lee el worker directamente.

ComandoEfecto
paneflow serve startInicia el worker de este PANEFLOW_HOME o adopta el que ya lo sirve
paneflow serve statusImprime el pid, el protocolo, el home, el número de sesiones y las capacidades
paneflow serve stop [--drain-ms 5000]Detiene el worker; los terminales no se tocan
paneflow sessions [--json] [--follow]Imprime la lista de sesiones de la barra lateral; --follow imprime una línea por transición y se reconecta cuando el worker se reinicia
paneflow sessions ack <session-id>...Baja el flag unread que levanta un turno terminado

Relacionado