coder-leo

Un agente de programación para la terminal que corre con modelos locales. Lee, escribe y edita código, ejecuta comandos, busca en un proyecto y lleva una lista de tareas, guiado por un modelo que corre en tu propia computadora a través de Ollama o de cualquier servidor con la API de chat de OpenAI (LM Studio, llama-server, vLLM, mlx). Trabaja como Claude Code, y está hecho para ventanas de contexto pequeñas: mide la ventana, mantiene cada resultado de herramienta dentro del presupuesto, limpia los resultados antiguos, resume la conversación por partes cuando hace falta y le da al modelo herramientas que encuentran las cosas sin leer todo.

#Instalar

macOS, con Homebrew, dos comandos, una sola vez:

brew tap leonardoaguiar/coder-leo https://leonardoaguiar.com/apps/coder-leo/tap.git
brew install leonardoaguiar/coder-leo/coder-leo

brew upgrade trae las versiones nuevas, y coder-leo update también.

Linux (cualquier distribución, x86_64 o ARM), Android dentro de Termux y Windows dentro de WSL:

curl -fsSL https://leonardoaguiar.com/apps/coder-leo/install.sh | sh

Elige la compilación para la máquina, verifica su SHA-256 publicado e instala el binario, la página de manual y los autocompletados de la shell en /usr/local (pidiendo sudo cuando hace falta), en ~/.local o en la carpeta de Termux. Ejecutarlo de nuevo actualiza; sh -s -- --uninstall lo quita.

También necesitas un servidor de modelos con un modelo que admita herramientas:

• Ollama (predeterminado): ollama pull qwen2.5-coder:14b, o qwen3, devstral, gpt-oss, llama3.1, mistral. coder-leo habla con 127.0.0.1:11434, o con OLLAMA_HOST.
• LM Studio, llama-server, vLLM, mlx-lm o cualquier servidor compatible con OpenAI: coder-leo --api openai --host http://127.0.0.1:1234.

#Empezar

Abre una terminal en un proyecto y ejecuta coder-leo. La primera vez, elige un modelo de la lista; queda guardado. Escribe lo que quieres; /help lista los comandos.

coder-leo                         una sesión en esta carpeta
coder-leo "add tests for parser"  una sesión con un primer pedido
coder-leo -p "explain main.go"    una respuesta y sale (también lee stdin)
coder-leo -c                      continúa la última sesión de aquí
coder-leo --sessions              elige una sesión anterior
coder-leo --list                  los modelos instalados

La caja de bienvenida muestra el modelo, la ventana de contexto, el modo de permisos y la carpeta. La línea debajo del prompt muestra el modo, el modelo, cuánto contexto está en uso y la rama de git.

#Trabajar con él

• Pide cambios, no consejos. Edita los archivos y ejecuta la compilación o las pruebas él mismo; nunca pega código para que lo apliques tú.
• @ruta adjunta un archivo o una carpeta al mensaje (Tab completa, con búsqueda aproximada). Un archivo demasiado grande para la ventana entra como esquema, y el modelo lee las partes que necesita.
• !comando ejecuta un comando en la shell y guarda la salida en la conversación.
• #texto guarda una nota en el CLAUDE.md del proyecto.
• Esc o Ctrl+C detiene la respuesta. Lo que escribas mientras tanto queda esperando en el siguiente prompt.
• Shift+Tab cambia el modo de permisos; Ctrl+O activa o desactiva la salida completa de las herramientas; Ctrl+T muestra la lista de tareas; Esc Esc retrocede; Ctrl+R busca en el historial; Ctrl+J inserta una línea nueva; un pegado grande se pliega en un marcador.
• Las palabras think, think hard y ultrathink en un pedido aumentan el razonamiento de un modelo que piensa, en ese turno.

#Herramientas

El modelo trabaja con estas herramientas, con los nombres de Claude Code (también entiende los nombres que usan otros agentes, como read_file o run_command):

#La ventana de contexto

Los modelos locales tienen ventanas pequeñas (de 8k a 32k tokens es lo común en una máquina de 16 GB), y volver a leer un prompt largo cuesta segundos en cada turno. coder-leo mantiene la ventana funcionando:

• Tamaño: elegido según el límite del modelo y la memoria de la máquina (/ctx lo muestra, /ctx 32k o /ctx auto lo cambia). El conteo es una estimación corregida con lo que informa el servidor.
• Prefijo estable: el prompt de sistema no cambia durante la sesión, así que el servidor reutiliza su caché en vez de reevaluar todo.
• Resultados dentro del presupuesto: cada resultado de herramienta se recorta a lo que cabe; la salida completa se guarda en un archivo cuya ruta recibe el modelo, para leerla por partes o buscar con Grep.
• Limpieza al 70%: los resultados antiguos pasan a ser notas de una línea (los últimos quedan enteros).
• Resumen al 85%, o /compact [qué conservar]: un resumen estructurado de traspaso reemplaza la conversación, conservando los últimos turnos tal cual; una conversación demasiado larga para resumirla de una vez se resume por partes y se une. La transcripción queda en el disco, y Recall busca en ella.
• Mapa del repositorio: los archivos más referenciados y sus símbolos entran en el prompt de sistema cuando hay lugar, para que el modelo sepa dónde está cada cosa sin leer.
• /context muestra qué está usando la ventana: prompt de sistema, esquemas de herramientas, mensajes, resultados, resultados limpiados, espacio libre.

#Permisos

Cuatro modos: default pregunta antes de editar y de ejecutar comandos; acceptEdits deja pasar las ediciones dentro del proyecto y pregunta por los comandos; plan solo lee, y el modelo presenta un plan para su aprobación; yolo ejecuta todo sin preguntar, como hacían las primeras versiones, y es el predeterminado salvo que tu configuración diga otra cosa. Los comandos destructivos (borrar carpetas enteras, descartar trabajo de git, push forzado, sudo, borrar tablas) siguen preguntando en modo yolo; "guard": false en la configuración lo desactiva.

Las reglas de la configuración deciden antes que el modo: "allow": ["Bash(git *)", "Read"], "deny": ["Bash(rm *)"], "ask": ["Write"]. Responder a a un pedido de permiso autoriza esa herramienta durante la sesión; responder con palabras se las envía al modelo como instrucciones.

#Sesiones

Cada sesión se guarda mientras ocurre en ~/.config/coder-leo/sessions/<proyecto>/. coder-leo -c continúa la última, --resume <id> o /resume elige una, /rename le pone nombre, /export la escribe en Markdown. Antes de cada edición el archivo recibe un punto de control: /rewind (o Esc Esc) vuelve a un turno anterior, restaurando los archivos cambiados desde entonces y cortando ahí la conversación.

#Instrucciones, comandos, skills, agentes

• CLAUDE.md o AGENTS.md en el proyecto (y en las carpetas superiores, en ~/.config/coder-leo/ y en ~/.claude/) entran en el prompt de sistema: convenciones, comandos de compilación, qué evitar. Las líneas @ruta dentro de ellos importan otros archivos. /init le pide al modelo que escriba uno. /memory lista lo que está cargado.
• Comandos personalizados: archivos Markdown en .coder-leo/commands/ (o .claude/commands/, del proyecto o de tu carpeta personal), ejecutados como /nombre argumentos. $ARGUMENTS, $1, ` !comando y @archivo se expanden; el encabezado puede fijar description, argument-hint, allowed-tools y model`.
• Skills: .coder-leo/skills/<nombre>/SKILL.md (o .claude/skills/), listadas al modelo con sus descripciones; carga una con la herramienta Skill cuando la tarea coincide, o ejecutas /nombre.
• Subagentes: .coder-leo/agents/<nombre>.md (o .claude/agents/) con name, description, tools y model en el encabezado y el prompt de sistema en el cuerpo; la herramienta Task los ejecuta. De fábrica: explore, plan, general, review.
• Hooks: comandos de shell alrededor de los eventos (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, PreCompact, SessionEnd), con el evento en JSON por stdin; salir con código 2 bloquea con el motivo, y una respuesta en JSON puede permitir, denegar o agregar contexto. El mismo protocolo que Claude Code.
• MCP: servidores de .mcp.json (del proyecto o de tu carpeta personal) o de mcpServers en la configuración, por stdio o HTTP; sus herramientas aparecen como mcp__servidor__herramienta y sus prompts como comandos. /mcp los lista.

#Configuración

~/.config/coder-leo/settings.json, luego .coder-leo/settings.json y .coder-leo/settings.local.json en el proyecto, cada uno sobre el anterior; después el entorno (CODER_MODEL, CODER_API, CODER_HOST u OLLAMA_HOST, CODER_API_KEY).

{
  "model": "qwen2.5-coder:14b",
  "api": "ollama",
  "numCtx": 16384,
  "think": "low",
  "permissions": { "mode": "default", "allow": ["Bash(git *)"], "guard": true },
  "compact": { "micro": 0.7, "full": 0.85, "keepRecent": 6 },
  "repoMap": { "enabled": true, "budget": 3000 },
  "tools": { "minimal": false, "disabled": ["WebSearch"] },
  "hooks": { "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "./check.sh" }] }] },
  "mcpServers": { "fs": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] } },
  "statusLine": { "command": "~/.config/coder-leo/status.sh" },
  "notify": "bell"
}

/config muestra lo que está vigente y de dónde viene; /doctor revisa el servidor, el modelo, la memoria y la configuración.

#Sin terminal

coder-leo -p "pedido" responde una vez: la respuesta por stdout, todo lo demás por stderr. --output-format json imprime un objeto con el resultado, el id de sesión y los conteos de tokens; --output-format stream-json imprime un evento JSON por línea a medida que ocurren las cosas. --max-turns, --allowedTools, --disallowedTools, --system-prompt, --append-system-prompt y --mode dan forma a la ejecución; -c o --resume continúan una sesión.

#Privacidad

Todo corre en tu computadora: el modelo, los archivos, la conversación. El programa solo accede a la red cuando el modelo llama a WebFetch o WebSearch para tu tarea (con pedido de permiso, fuera del modo yolo), cuando configuras un servidor MCP que sale afuera y cuando ejecutas coder-leo update. Sin cuentas, sin telemetría, nada se envía a ningún lado.

#Actualizaciones

coder-leo update revisa en el sitio si hay una versión más nueva y la instala (a través de Homebrew en una copia de Homebrew); coder-leo update --check solo avisa. El programa nunca revisa por su cuenta.

#Ayuda y reportes de errores

Problemas e ideas: la dirección de soporte al final de la página de coder-leo. Incluye el modelo, el servidor, coder-leo version y la salida de /doctor.