---
name: claude_cli_prompt
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def claude_cli_prompt(prompt: str, timeout_s: int = 60, model: str | None = None, max_chars_response: int = 200_000, extra_args: list[str] | None = None) -> str"
description: "Invoca `claude -p` via subprocess y devuelve la respuesta completa como string. Valida presencia del CLI, captura stderr en errores, y trunca respuestas largas."
tags: [claude, llm, cli, ai, navegator, subprocess]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [shutil, subprocess]
params:
  - name: prompt
    desc: "Texto del prompt a enviar a Claude."
  - name: timeout_s
    desc: "Segundos antes de raise TimeoutExpired. Default 60."
  - name: model
    desc: "Modelo a usar (ej. claude-opus-4-5). None usa el default del CLI."
  - name: max_chars_response
    desc: "Trunca stdout a este numero de caracteres. Default 200_000."
  - name: extra_args
    desc: "Lista de argumentos adicionales para el CLI."
output: "Respuesta de Claude como texto plano (stdout del proceso)."
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/infra/claude_cli_prompt.py"
---

## Ejemplo

```python
from infra.claude_cli_prompt import claude_cli_prompt

# Pregunta simple
respuesta = claude_cli_prompt("Suma 2+2 y devuelve solo el numero")
print(respuesta)  # "4"

# Con modelo especifico y timeout extendido
respuesta = claude_cli_prompt(
    prompt="Resume este texto en 3 puntos: ...",
    model="claude-opus-4-5",
    timeout_s=120,
)
```

## Cuando usarla

Cuando necesitas invocar Claude desde un script Python sin mantener sesion de chat — un prompt puntual (clasificacion, resumen, extraccion) que se resuelve en una sola llamada. Ideal para pipelines que procesan chunks de AX tree, texto, o cualquier contenido que requiera razonamiento LLM.

## Gotchas

- Requiere `claude` CLI instalado y autenticado en PATH. Si no esta: `FileNotFoundError`.
- Cada llamada lanza un subproceso nuevo — no hay cache ni sesion persistente.
- El CLI puede tardar varios segundos al cold-start. Usa `timeout_s` conservador (>=30s).
- `extra_args` se pasan literalmente — validar antes de pasar input de usuario.
- En CI/CD sin display interactivo puede requerir `--no-interactive` en `extra_args`.