--- name: claude_pipe lang: go domain: infra version: 0.1.0 description: "Alternativa a 'claude -p' que obtiene la respuesta de claude como dato PARSEANDO su TUI interactiva: captura el render via PTY, reconstruye el layout y extrae los turnos + la respuesta final. Emite JSON con el mismo shape que 'claude -p --output-format json'. Para interaccion programatica robusta prefiere el camino stream-json (claude_stream_go_core); esta app es la variante que va a traves de la TUI." tags: [cli, claude, terminal, pty, tui, parser] uses_functions: - pty_capture_idle_go_infra - pty_capture_stream_go_infra - vt_render_go_tui - parse_claude_tui_go_tui - text_prefix_delta_go_core uses_types: - claude_tui_parse_go_tui - claude_turn_go_tui framework: "" entry_point: "main.go" dir_path: "apps/claude_pipe" icon: phosphor: "faders" accent: "#0ea5e9" e2e_checks: - id: build cmd: "CGO_ENABLED=1 go build -tags fts5 -o claude_pipe ." timeout_s: 120 - id: smoke_fake_text cmd: "./claude_pipe --bin ./tests/fake_claude.sh --warmup 300ms --step-delay 100ms --idle 700ms --max 5s --format text test" expect_stdout_contains: "RESPUESTA_FAKE_OK" timeout_s: 15 - id: smoke_fake_json cmd: "./claude_pipe --bin ./tests/fake_claude.sh --warmup 300ms --step-delay 100ms --idle 700ms --max 5s --format json test" expect_stdout_contains: "\"result\":\"RESPUESTA_FAKE_OK\"" timeout_s: 15 - id: smoke_fake_stream cmd: "./claude_pipe --stream --bin ./tests/fake_claude.sh --warmup 300ms --step-delay 100ms --snapshot-interval 120ms --idle 700ms --max 5s test" expect_stdout_contains: "\"type\":\"text_delta\"" timeout_s: 15 --- # claude_pipe ## Que hace Devuelve la respuesta de `claude` como dato **parseando su TUI interactiva**, en lugar de usar `claude -p`. Internamente lanza el `claude` interactivo dentro de un pseudo-terminal, captura el render de la pantalla, reconstruye el layout 2D, y extrae los turnos de la conversacion mas la respuesta final del asistente. La salida por defecto imita `claude -p --output-format json`. Es la respuesta a "quiero parsear la TUI y que devuelva lo mismo que `claude -p`". Para la mayoria de los casos programaticos el camino limpio es `stream-json` (ver `claude_stream_go_core`), que no toca la TUI; `claude_pipe` existe para cuando se quiere expresamente ir a traves de la TUI. ## Arquitectura (composicion de funciones del registry) ``` claude (TUI) ─pty_capture_idle_go_infra─▶ bytes crudos del terminal ─vt_render_go_tui──────────▶ pantalla como texto plano (layout 2D) ─parse_claude_tui_go_tui───▶ ClaudeTUIParse {Turns, Answer} ─(esta app)────────────────▶ JSON estilo claude -p / texto / turns ``` La app no aporta logica reutilizable: solo orquesta las tres funciones y elige el formato de salida. ## Formatos de salida (`--format`) | Formato | Salida | Equivale a | |---|---|---| | `json` (default) | `{"type":"result","subtype":"success","is_error":false,"result":""}` | `claude -p --output-format json` (campos esenciales) | | `text` | solo el texto de la respuesta | `claude -p` plano | | `turns` | el `ClaudeTUIParse` completo: cada turno visible (user/assistant/tool_use/tool_result) + answer | — (mas rico que `claude -p`) | | `screen` | el render de la pantalla sin parsear | debug | ## Ejemplo ```bash cd apps/claude_pipe CGO_ENABLED=1 go build -tags fts5 -o claude_pipe . # Respuesta como JSON (mismo shape que claude -p --output-format json) ./claude_pipe --cwd /home/enmanuel/fn_registry "responde unicamente con la palabra PONG" # {"type":"result","subtype":"success","is_error":false,"result":"PONG"} # Solo el texto ./claude_pipe --format text --cwd /home/enmanuel/fn_registry "resume el README en 3 lineas" # Todos los turnos visibles (incluye tool_use/tool_result que la TUI muestra) ./claude_pipe --format turns --cwd /home/enmanuel/fn_registry "lee main.go y resumelo" # Prompt por stdin echo "explica este error" | ./claude_pipe --cwd /home/enmanuel/fn_registry ``` ## Flags | Flag | Default | Que hace | |---|---|---| | `--prompt` | — | Prompt a enviar. Si vacio, se toma del arg posicional o de stdin. | | `--format` | `json` | `json` \| `text` \| `turns` \| `screen`. | | `--cwd` | — | Directorio donde se lanza claude (usa un repo con los MCP aprobados, para saltar el dialogo de arranque). | | `--bin` | `claude` | Binario claude a lanzar (o un fake para tests). | | `--warmup` | `4s` | Espera antes de enviar el prompt, para que la TUI cargue. | | `--step-delay` | `600ms` | Espera entre teclear el prompt y pulsar Enter. | | `--idle` | `4s` | Corta la captura tras este silencio (respuesta terminada de renderizar). | | `--max` | `120s` | Timeout duro de toda la captura. | | `--stream` | false | Emite la respuesta incrementalmente como NDJSON (`text_delta` por snapshot) y un `result` final. | | `--snapshot-interval` | `150ms` | En `--stream`, cada cuánto se captura y re-parsea la TUI. | ## Streaming (`--stream`) Con `--stream`, la app usa `pty_capture_stream_go_infra` para tomar snapshots del render cada `--snapshot-interval`, re-parsea cada snapshot con `parse_claude_tui_go_tui`, y emite el delta del `Answer` (via `text_prefix_delta_go_core`) como NDJSON, terminando con un `result`: ```bash ./claude_pipe --stream --cwd /home/enmanuel/fn_registry "explica Go en 3 frases" # {"type":"text_delta","text":"Go es un lenguaje..."} # {"type":"text_delta","text":" compilado y concurrente..."} # {"type":"result","subtype":"success","result":"Go es un lenguaje... compilado y concurrente..."} ``` Un programa externo Go (u otro) lo lanza como subprocess y lee líneas. **Es heurístico** (ver Gotchas): la TUI re-renderiza el frame entero, así que solo se emite `text_delta` cuando el nuevo `Answer` extiende limpiamente al anterior; los frames no monótonos (reflow) se reconcilian en el `result` final, cuyo `result` lleva siempre la respuesta completa. Para streaming limpio y monótono nativo sin tocar la TUI, `claude_stream_go_core` (stream-json) es superior. ## Cuando usarla - Cuando quieras la respuesta de una sesion `claude` como dato yendo **a traves de la TUI** (no via `claude -p`). - Para auditar/scriptear lo que la TUI muestra y obtener ademas los `tool_use`/`tool_result` visibles (`--format turns`). Si no necesitas pasar por la TUI, usa `claude_stream_go_core` (stream-json) — es mas robusto. ## Gotchas - **No reemplaza 1:1 a `claude -p`**: el campo `result` (la respuesta) coincide, pero NO se extraen los metadatos (`cost`, `tokens`, `session_id`, `duration_ms`) porque la TUI no los expone de forma fiable. - **Truncacion por scroll**: la captura solo ve el grid visible (40x120). Una respuesta mas larga que la pantalla se trunca por arriba (el render no guarda scrollback). Respuestas cortas/medias van bien. - **Heuristico y version-dependiente**: el parser asume el layout actual de la TUI de claude. Si claude cambia su UI, hay que ajustar `parse_claude_tui_go_tui`. - **Dialogo de arranque**: en un cwd cuyos MCP no estan aprobados, claude bloquea con "new MCP servers found". Usa `--cwd `. - **Latencia**: anade `warmup` + `idle` (por defecto ~8s de overhead) sobre el tiempo de respuesta de claude. `claude -p` no tiene ese overhead. Es el precio de ir por la TUI. - **Linux/Unix only**: hereda el PTY POSIX de `pty_capture_idle_go_infra`. - **Streaming heurístico**: `--stream` emite deltas re-parseando snapshots del render. Como la TUI re-renderiza el frame entero, el `Answer` parseado puede no ser monótono (reflow al crecer la respuesta, spinner). Solo se emite `text_delta` cuando el nuevo answer extiende limpiamente al anterior; el `result` final siempre lleva la respuesta completa. Posibles artefactos: deltas que reaparecen, o fragmentos perdidos en un frame intermedio. Si necesitas streaming exacto, usa `claude_stream_go_core` (stream-json).