Documentación

Todo lo que necesitas para instalar, configurar y aprovechar al máximo Halcón CLI.

Instalación

Instalación rápida (recomendado)

macOS / Linux

curl -sSfL https://cuervo.cloud/install.sh | sh

Windows (PowerShell)

iwr -useb https://cuervo.cloud/install.ps1 | iex

El instalador detecta tu plataforma, descarga el binario correcto, verifica el checksum SHA-256 y lo coloca en ~/.local/bin/halcon. No requiere sudo.

Otros métodos

Homebrew (macOS / Linux)

brew tap cuervo-ai/tap && brew install halcon

Versión específica

curl -sSfL https://cuervo.cloud/install.sh | sh -s -- --version v0.2.0

Flags globales

Los flags globales van antes del subcomando y se aplican a toda la sesión. La mayoría tienen equivalentes como variables de entorno.

halcon [FLAGS GLOBALES] <comando> [OPCIONES]

Proveedor y modelo:

-p, --provider <nombre> Proveedor IA a utilizar (env: HALCON_PROVIDER)

-m, --model <nombre> Modelo a utilizar (env: HALCON_MODEL)

Config y logging:

--config <ruta> Usar archivo de config personalizado (env: HALCON_CONFIG)

--log-level <nivel> Verbosidad: error · warn · info · debug (env: HALCON_LOG)

-v, --verbose Activar salida de depuración

--trace-json Escribir líneas JSON de traza a stderr

--no-banner Suprimir el banner de inicio

Ejemplo: halcon -p openai -m gpt-4o chat "refactoriza esta función"

Configuración

Halcón lee la configuración desde ~/.halcon/config.toml (global) y ./.halcon/config.toml (override de proyecto). En la primera ejecución se crea una configuración por defecto automáticamente.

# ~/.halcon/config.toml

[general]

default_provider = "anthropic" # anthropic · openai · deepseek · gemini · ollama

default_model = "claude-sonnet-4-5-20250929"

[agent.limits]

max_rounds = 25

max_tool_output_chars = 100000

max_parallel_tools = 10

[tools]

confirm_destructive = true

allowed_directories = ["~/", "/tmp"]

blocked_patterns = ["**/.env", "**/*.key", "**/*.pem"]

[agent.routing]

strategy = "balanced" # balanced · fast · cheap

[display]

ui_mode = "simple" # simple · expert

Cambio en tiempo real: halcon config set general.default_provider openai

Primera conversación

Agrega tu clave API

halcon auth login anthropic

Verifica que funciona

halcon chat "¿Cuánto es 2+2?"

Lanza el cockpit TUI

halcon chat --tui

Activa todo el potencial

halcon chat --full "explica este codebase"

Activa orquestación, reflexión, tareas estructuradas y feedback experto.

Referencia CLI

halcon chat

Inicia una sesión con acceso completo a herramientas. Pasa un prompt para modo puntual o sin argumento para el REPL interactivo.

halcon chat [OPCIONES] [PROMPT]

Flags principales:

--tui Lanza el cockpit TUI de 3 zonas

--provider <nombre> Usar un proveedor específico para esta sesión

--model <nombre> Usar un modelo específico para esta sesión

--resume <session-id> Reanudar sesión previa por UUID

--expert Mostrar feedback detallado del agente

Funciones avanzadas (o usa --full para todas):

--full Orquestación + reflexión + tareas + salida experto

--orchestrate Orquestación multi-agente con wave scheduling

--reflexion Bucle de auto-mejora antes de responder

--tasks Framework de tareas estructuradas con FSM

Observabilidad:

--metrics Imprimir métricas de sesión al salir

--timeline Exportar timeline de ejecución como JSON al salir

--trace-out <ruta> Escribir traza JSONL (reproducible con --trace-in)

--trace-in <ruta> Reproducir una traza JSONL antes de la sesión

halcon auth

Gestiona las claves API. Las claves se guardan en el keychain del sistema operativo — nunca se escriben en disco en texto plano.

halcon auth login <proveedor> Guardar clave API en el keychain del sistema

halcon auth logout <proveedor> Eliminar clave API del keychain

halcon auth status Mostrar qué proveedores tienen clave configurada

Proveedores: anthropic · openai · deepseek · gemini (ollama no requiere clave)

halcon config

Lee y escribe valores de configuración sin editar el archivo TOML manualmente.

halcon config show Imprimir toda la config activa (global + proyecto)

halcon config path Mostrar la ruta del archivo de config en uso

halcon config get <clave> Leer un valor individual ej. general.default_provider

halcon config set <clave> <valor> Escribir un valor en la config global

halcon init

Inicializa Halcón en el directorio del proyecto actual. Crea un override .halcon/config.toml.

halcon init Crear .halcon/config.toml en el directorio actual

halcon init --provider openai Inicializar con OpenAI como proveedor por defecto

halcon status

Muestra el estado actual del sistema: proveedor y modelo activos, número de sesiones, versión y estado del keychain.

halcon status Imprimir proveedor, modelo, sesiones y versión

halcon tools

Inspecciona y gestiona las 21 herramientas integradas. Añade herramientas personalizadas via manifests TOML en ~/.halcon/tools/<nombre>.toml.

halcon tools list Listar todas las herramientas con nombres y permisos

halcon tools validate Validación de esquema para todas las herramientas

halcon tools doctor Diagnósticos: esquema, sondeos, métricas de error

halcon tools add <nombre> \

--command <cmd> --description <desc> [--permission ReadOnly|Destructive]

halcon tools remove <nombre> [--force] Eliminar un manifest de herramienta personalizada

halcon memory

Consulta y gestiona el almacén de memoria episódica. El agente lee automáticamente la memoria relevante antes de cada respuesta usando búsqueda semántica BM25.

halcon memory search <consulta> [--limit N] Búsqueda BM25 full-text en todas las entradas

halcon memory list [--type <tipo>] Listar entradas, opcionalmente filtradas por tipo

halcon memory stats Mostrar conteos y tamaño total de almacenamiento

halcon memory prune [--force] Eliminar entradas expiradas y de baja relevancia

Tipos de entrada: fact · session_summary · decision · code_snippet · project_meta

halcon trace

Inspecciona y exporta trazas de sesión. Las trazas son archivos JSONL legibles que capturan cada round del agente, llamada a herramienta y respuesta del modelo.

halcon trace list Listar archivos de traza JSONL grabados

halcon trace show <ruta> Imprimir una traza en formato legible

halcon trace export <session-id> Exportar una sesión de la base de datos como traza JSONL

halcon replay

Reproduce un archivo de traza JSONL. Los resultados de herramientas se leen de la traza — no hay ejecución de herramientas en vivo. Útil para pruebas deterministas y depuración.

halcon replay <ruta-traza> Reproducir un archivo de traza (lee resultados del archivo)

# Tip: crea una traza con --trace-out, luego reprodúcela con halcon replay

halcon metrics

Visualiza y gestiona métricas de rendimiento agregadas de sesiones pasadas: latencia, coste, uso de tokens, invocaciones de herramientas.

halcon metrics show Mostrar métricas agregadas (P50, P95, coste promedio, etc.)

halcon metrics export Exportar métricas como JSON

halcon metrics prune Eliminar registros más antiguos que la ventana de retención

halcon metrics decide Analizar métricas y sugerir optimizaciones de configuración

halcon doctor

Ejecuta diagnósticos completos del sistema — conectividad de proveedores, salud de herramientas, validez de config, acceso al keychain, integridad de base de datos. Adjunta la salida al reportar problemas.

halcon doctor Ejecutar todas las comprobaciones e imprimir reporte

halcon update

Auto-actualización: descarga el manifest de la última versión desde cuervo.cloud, verifica el checksum SHA-256 y reemplaza el binario de forma atómica.

halcon update Descargar e instalar la última versión

halcon update --check Verificar si hay una versión más reciente disponible

halcon update --version v0.2.0 Instalar una versión específica

halcon update --force Reinstalar aunque ya tengas la última versión

halcon mcp-server

Inicia Halcón como servidor MCP sobre stdio. Expone las 21 herramientas vía JSON-RPC a cualquier IDE compatible (Cursor, VS Code, Zed, etc.).

halcon mcp-server [--working-dir <ruta>] Iniciar servidor MCP en stdio

# Agrega a tu .mcp.json:

{ "mcpServers": { "halcon": { "command": "halcon", "args": ["mcp-server"] } } }

halcon serve

Inicia un API de control HTTP con streaming por WebSocket. Útil para integraciones de escritorio y control programático.

halcon serve [--host 127.0.0.1] [--port 9849] Iniciar servidor API

# Token Bearer generado automáticamente (o definir via HALCON_API_TOKEN)

Feature flags

Las capacidades avanzadas son opt-in por sesión. Usa --full para activarlas todas de una vez, o actívalas individualmente para una sesión más liviana.

--full Activa orquestación + reflexión + tareas + salida experto en un solo flag.

--orchestrate Orquestación multi-agente con grafos de dependencias y wave scheduling. Requiere planificación adaptativa.

--reflexion Bucle de auto-mejora: el agente reflexiona sobre su propio output y se autocorrige antes de responder.

--tasks Framework de tareas estructuradas con FSM de 9 estados, políticas de reintento, tracking de artefactos y provenance.

--expert Mostrar feedback completo del agente: selección de modelo, cache hits, eventos de compactación, estadísticas de round.

--metrics Imprimir métricas de sesión al salir: rounds, tokens, coste, duración, invocaciones de herramientas.

--timeline Exportar el timeline completo de ejecución como JSON al salir.

--trace-out <ruta> Escribir una traza JSONL de ejecución. Editable; reproducir con halcon replay o --trace-in.

--resume <id> Reanudar una sesión previa por UUID — restaura mensajes, conteos de tokens y estado de sesión.

TUI Cockpit

Se lanza con halcon chat --tui. Una interfaz de terminal de 3 zonas que ofrece visibilidad y control en tiempo real sobre cada acción del agente.

Las tres zonas

Zona de prompt

arriba

Editor de texto multilinea. Altura dinámica hasta 12 líneas. Navegación de historial con ↑/↓.

Zona de actividad

centro

Salida en vivo con scroll: tarjetas de ejecución de herramientas, progreso del plan, separadores de round, texto del asistente con markdown, spinner de feedback.

Zona de estado

abajo

Barra de 3 líneas: ID de sesión · proveedor/modelo · round # · conteos de tokens · coste · tiempo transcurrido · herramientas. Click en ID para copiar. Click en ■ STOP para cancelar.

Atajos de teclado

Ctrl+Enter Enviar prompt

■ / Ctrl+C Detener el agente en ejecución

Space Pausar / reanudar agente durante la ejecución

N Paso — avanzar exactamente un round del agente

↑ / ↓ Historial de prompts (en la zona de prompt)

PgUp / PgDn Scroll en la zona de actividad

F1 Alternar panel lateral

F2 Ciclar sección del panel: Plan → Métricas → Contexto → Razonamiento → Todo

F6 Abrir selector de sesiones

Esc Cancelar overlay / denegar solicitud de permiso

Secciones del panel lateral

Plan Plan de ejecución activo con estados por paso (pendiente · ejecutando · hecho · fallido) y tiempos.

Métricas Conteos de tokens de sesión (entrada/salida), coste, invocaciones de herramientas, número de rounds.

Contexto Uso de los niveles de contexto L0–L4 y presupuestos de tokens. Muestra cuánto de cada tier está consumido.

Razonamiento Estrategia de routing seleccionada, tipo de tarea detectado, puntuación de complejidad y justificación del modelo.

Sistema de memoria

Halcón gestiona el contexto automáticamente con una arquitectura de memoria de 5 niveles. No hace falta configurarlo — el agente decide qué mantener, comprimir y recuperar según relevancia y presupuestos de tokens.

Niveles de contexto (sesión activa)

L0 HotBuffer 40% Buffer circular de los mensajes más recientes. Siempre incluido en cada petición.

L1 SlidingWindow 25% Segmentos de conversación compactados. Los mensajes más antiguos se fusionan y resumen.

L2 ColdStore 15% Segmentos comprimidos con zstd y codificación delta. Se recuperan si el presupuesto lo permite.

L3 SemanticStore 15% Recuperación indexada por BM25. El contexto pasado más relevante para la consulta actual.

L4 ColdArchive 5% Archivo persistido en disco (~/.local/share/halcon/l4_archive.bin). Entre sesiones.

Memoria episódica (entre sesiones)

Almacenada en ~/.halcon/halcon.db con SQLite e índice FTS5 de texto completo. El agente registra automáticamente decisiones, patrones de código y hechos importantes, recuperando las entradas más relevantes antes de cada respuesta.

Recuperación: búsqueda semántica BM25 sobre la consulta actual

Puntuación: relevance_score × decaimiento temporal (semivida 14 días)

Feedback: rounds exitosos aumentan score +0.2 · fallos lo reducen −0.15

Limpieza: consolidación automática fusiona entradas similares (similitud Jaccard)

Slash commands

Dentro del REPL o TUI, escribe / para acceder a comandos en vivo sin salir de la sesión.

Sesión

/session list Listar sesiones recientes con UUIDs y timestamps

/session resume <id> Reanudar sesión previa — restaura mensajes y conteos de tokens

/session diff <a> <b> Comparar dos sesiones lado a lado

/snapshot Guardar el estado actual de la sesión como checkpoint

Inspección y diagnósticos

/status Estado del sistema en vivo: sesión, rounds, tokens, coste, proveedores

/metrics Métricas de caché, memoria y especulación de herramientas

/cost Desglose de coste de sesión por proveedor y modelo

/inspect runtime Detalles del entorno de ejecución

/inspect context Uso de niveles de la pipeline de contexto y presupuestos de tokens

/inspect memory Número de entradas de memoria episódica y uso

/inspect tasks Estado del framework de tareas activo y estados FSM

/doctor Ejecutar diagnósticos de salud desde dentro del REPL

Planificación y orquestación

/plan <objetivo> Generar un plan de ejecución con el planificador LLM

/orchestrate <tarea> Delegar tarea al orquestador multi-agente

/step Ejecutar exactamente un round del agente, luego pausar

Traza y reproducción

/trace Explorar archivos de traza grabados

/replay <ruta> Reproducir una traza JSONL dentro de la sesión actual

/research <tema> Ejecutar una sesión de investigación de conocimiento enfocada

Rendimiento

/benchmark inference Medir latencia del modelo: P50, P95, promedio

/benchmark cache Tasa de aciertos de caché y ahorro de tokens

/benchmark full Suite completa de benchmarks

/analyze Ejecutar análisis de complejidad y calidad de código

/optimize Analizar sesión y sugerir optimizaciones

Configuración de proveedores

Las claves API se guardan en el keychain del OS via halcon auth login. La estrategia de routing (balanced · fast · cheap) elige entre los proveedores configurados automáticamente.

Anthropic ANTHROPIC_API_KEY

claude-opus-4-6 200K visión · herramientas

claude-sonnet-4-5-20250929 200K visión · herramientas

claude-haiku-4-5-20251001 200K visión · herramientas

OpenAI OPENAI_API_KEY

gpt-4o 128K visión · herramientas · razonamiento

gpt-4o-mini 128K visión · herramientas

o1 200K razonamiento (sin visión)

o3-mini 200K razonamiento (sin visión)

DeepSeek DEEPSEEK_API_KEY

deepseek-chat 64K herramientas

deepseek-coder 64K herramientas

deepseek-reasoner 64K herramientas · razonamiento

Gemini GEMINI_API_KEY

gemini-2.0-flash 1M visión · herramientas

gemini-1.5-pro 1M visión · herramientas

Ollama (sin clave requerida)

cualquier modelo instalado variable emulación de herramientas vía XML en system prompt

# Estrategias de routing (agent.routing.strategy):

balanced Balance coste/calidad — por defecto. Enruta al modelo más adecuado por tarea.

fast Menor latencia. Prioriza por tiempo de respuesta p95 de métricas históricas.

cheap Menor coste por token. Siempre enruta al modelo capaz más económico.

Permisos de herramientas

Cada herramienta tiene un nivel de permiso explícito. Las herramientas Destructive solicitan confirmación antes de ejecutarse. Configura tools.confirm_destructive = false para deshabilitar en pipelines CI/automatizados.

ReadOnly Nunca solicita confirmación — operaciones de solo lectura seguras

file_read · directory_tree · glob · grep · fuzzy_find · symbol_search · web_fetch · web_search · native_search · git_status · git_diff · git_log · file_inspect · background_output · task_track

ReadWrite Sin confirmación — escrituras reversibles

git_add

Destructive Solicita confirmación antes de ejecutar (confirm_destructive = true)

bash · file_write · file_edit · file_delete · git_commit · http_request · background_start · background_kill

¿Necesitas más ayuda?

support@cuervo.cloud — Preguntas, reporte de bugs, solicitudes de funciones

halcon doctor — Ejecuta diagnósticos primero y adjunta la salida a tu reporte