coder-leo

Um agente de código para o terminal que corre com modelos locais. Lê, escreve e edita código, executa comandos, pesquisa um projeto e mantém uma lista de tarefas, guiado por um modelo que corre na sua própria máquina através do Ollama ou de qualquer servidor com a API de chat da OpenAI (LM Studio, llama-server, vLLM, mlx). Trabalha como o Claude Code, e foi feito para janelas de contexto pequenas: mede a janela, mantém cada resultado de ferramenta dentro do orçamento, limpa os resultados antigos, resume a conversa por partes quando é preciso e dá ao modelo ferramentas que encontram as coisas sem ler tudo.

#Instalar

macOS, com Homebrew, dois comandos, uma vez:

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

brew upgrade traz as versões novas, e coder-leo update também.

Linux (qualquer distribuição, x86_64 ou ARM), Android dentro do Termux e Windows dentro do WSL:

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

Escolhe a versão para a máquina, verifica o SHA-256 publicado e instala o binário, a página de manual e os preenchimentos automáticos da shell em /usr/local (pedindo sudo quando é preciso), em ~/.local ou na pasta do próprio Termux. Executar de novo atualiza; sh -s -- --uninstall remove.

É preciso também um servidor de modelos com um modelo que suporte ferramentas:

• Ollama (predefinição): ollama pull qwen2.5-coder:14b, ou qwen3, devstral, gpt-oss, llama3.1, mistral. O coder-leo fala com 127.0.0.1:11434, ou com OLLAMA_HOST.
• LM Studio, llama-server, vLLM, mlx-lm ou qualquer servidor compatível com a OpenAI: coder-leo --api openai --host http://127.0.0.1:1234.

#Começar

Abra um terminal num projeto e execute coder-leo. Da primeira vez, escolha um modelo da lista; fica memorizado. Escreva o que pretende; /help lista os comandos.

coder-leo                         uma sessão nesta pasta
coder-leo "add tests for parser"  uma sessão com um primeiro pedido
coder-leo -p "explain main.go"    uma resposta e sai (também lê o stdin)
coder-leo -c                      continua a última sessão daqui
coder-leo --sessions              escolhe uma sessão anterior
coder-leo --list                  os modelos instalados

A caixa de boas-vindas mostra o modelo, a janela de contexto, o modo de permissões e a pasta. A linha por baixo da linha de comandos mostra o modo, o modelo, quanto do contexto está em uso e o ramo do git.

#Trabalhar com ele

• Peça alterações, não conselhos. Edita os ficheiros e executa a compilação ou os testes sozinho; nunca cola código para aplicar à mão.
• @caminho anexa um ficheiro ou uma pasta à mensagem (Tab completa, com pesquisa aproximada). Um ficheiro grande demais para a janela entra como esboço, e o modelo lê as partes de que precisa.
• !comando executa um comando na shell e guarda a saída na conversa.
• #texto guarda uma nota no CLAUDE.md do projeto.
• Esc ou Ctrl+C interrompe a resposta. O que escrever entretanto fica à espera na linha seguinte.
• Shift+Tab alterna o modo de permissões; Ctrl+O liga e desliga a saída completa das ferramentas; Ctrl+T mostra a lista de tarefas; Esc Esc recua; Ctrl+R pesquisa o histórico; Ctrl+J insere uma linha nova; uma colagem grande passa a um marcador.
• As palavras think, think hard e ultrathink num pedido aumentam o raciocínio de um modelo que pensa, nesse turno.

#Ferramentas

O modelo trabalha através destas ferramentas, com os nomes do Claude Code (também entende os nomes que outros agentes usam, como read_file ou run_command):

#A janela de contexto

Os modelos locais têm janelas pequenas (8k a 32k tokens é o habitual numa máquina de 16 GB), e reler um prompt longo custa segundos a cada turno. O coder-leo mantém a janela a funcionar:

• Tamanho: escolhido pelo limite do modelo e pela memória da máquina (/ctx mostra-o, /ctx 32k ou /ctx auto altera-o). A contagem é uma estimativa corrigida pelo que o servidor comunica.
• Prefixo estável: o prompt de sistema não muda durante a sessão, por isso o servidor reutiliza a cache em vez de reavaliar tudo.
• Resultados dentro do orçamento: cada resultado de ferramenta é cortado ao que cabe; a saída completa vai para um ficheiro cujo caminho o modelo recebe, para ler por partes ou pesquisar com Grep.
• Limpeza aos 70%: os resultados antigos passam a notas de uma linha (os últimos ficam inteiros).
• Resumo aos 85%, ou /compact [o que manter]: um resumo estruturado de passagem de testemunho substitui a conversa, mantendo os últimos turnos tal e qual; uma conversa longa demais para resumir de uma vez é resumida por partes e juntada. A transcrição fica no disco, e o Recall pesquisa nela.
• Mapa do repositório: os ficheiros mais referidos e os seus símbolos entram no prompt de sistema quando há espaço, para o modelo saber onde as coisas estão sem ler.
• /context mostra o que está a usar a janela: prompt de sistema, esquemas das ferramentas, mensagens, resultados, resultados limpos, espaço livre.

#Permissões

Quatro modos: default pergunta antes de editar e de executar comandos; acceptEdits deixa passar as edições dentro do projeto e pergunta pelos comandos; plan só lê, e o modelo apresenta um plano para aprovação; yolo executa tudo sem perguntar, como faziam as primeiras versões, e é a predefinição a não ser que as suas definições digam outra coisa. Os comandos destrutivos (remover pastas largas, descartar trabalho do git, push forçado, sudo, apagar tabelas) continuam a perguntar no modo yolo; "guard": false nas definições desliga isso.

As regras nas definições decidem antes do modo: "allow": ["Bash(git *)", "Read"], "deny": ["Bash(rm *)"], "ask": ["Write"]. Responder a a um pedido de permissão autoriza essa ferramenta durante a sessão; responder com palavras envia-as ao modelo como instruções.

#Sessões

Cada sessão é guardada à medida que acontece em ~/.config/coder-leo/sessions/<projeto>/. coder-leo -c continua a última, --resume <id> ou /resume escolhe uma, /rename dá-lhe nome, /export grava-a em Markdown. Antes de cada edição o ficheiro ganha um ponto de reposição: /rewind (ou Esc Esc) recua até um turno anterior, repondo os ficheiros alterados desde então e cortando ali a conversa.

#Instruções, comandos, skills, agentes

• CLAUDE.md ou AGENTS.md no projeto (e nas pastas acima dele, em ~/.config/coder-leo/ e em ~/.claude/) entram no prompt de sistema: convenções, comandos de compilação, o que evitar. As linhas @caminho dentro deles importam outros ficheiros. /init pede ao modelo que escreva um. /memory lista o que está carregado.
• Comandos personalizados: ficheiros Markdown em .coder-leo/commands/ (ou .claude/commands/, no projeto ou na pasta pessoal), executados como /nome argumentos. $ARGUMENTS, $1, ` !comando e @ficheiro são expandidos; o cabeçalho pode definir description, argument-hint, allowed-tools e model`.
• Skills: .coder-leo/skills/<nome>/SKILL.md (ou .claude/skills/), listadas ao modelo com as descrições; carrega uma com a ferramenta Skill quando a tarefa corresponde, ou executa-se /nome.
• Subagentes: .coder-leo/agents/<nome>.md (ou .claude/agents/) com name, description, tools e model no cabeçalho e o prompt de sistema no corpo; a ferramenta Task executa-os. De origem: explore, plan, general, review.
• Hooks: comandos de shell à volta dos eventos (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, PreCompact, SessionEnd), com o evento em JSON no stdin; sair com o código 2 bloqueia com o motivo, e uma resposta em JSON pode autorizar, negar ou acrescentar contexto. O mesmo protocolo do Claude Code.
• MCP: servidores do .mcp.json (do projeto ou da pasta pessoal) ou de mcpServers nas definições, por stdio ou HTTP; as suas ferramentas aparecem como mcp__servidor__ferramenta e os prompts como comandos. /mcp lista-os.

#Definições

~/.config/coder-leo/settings.json, depois .coder-leo/settings.json e .coder-leo/settings.local.json no projeto, cada um a sobrepor-se ao anterior; depois o ambiente (CODER_MODEL, CODER_API, CODER_HOST ou 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 mostra o que está em vigor e de onde veio; /doctor verifica o servidor, o modelo, a memória e a configuração.

#Sem terminal

coder-leo -p "pedido" responde uma vez: a resposta no stdout, tudo o resto no stderr. --output-format json imprime um objeto com o resultado, o id da sessão e as contagens de tokens; --output-format stream-json imprime um evento JSON por linha à medida que as coisas acontecem. --max-turns, --allowedTools, --disallowedTools, --system-prompt, --append-system-prompt e --mode moldam a execução; -c ou --resume continuam uma sessão.

#Privacidade

Tudo corre na sua máquina: o modelo, os ficheiros, a conversa. O programa só acede à rede quando o modelo chama WebFetch ou WebSearch para a sua tarefa (com pedido de permissão, fora do modo yolo), quando configura um servidor MCP que sai para fora e quando executa coder-leo update. Sem contas, sem telemetria, nada enviado para lado nenhum.

#Atualizações

coder-leo update verifica no site se há uma versão mais recente e instala-a (através do Homebrew, numa cópia do Homebrew); coder-leo update --check apenas avisa. O programa nunca verifica por iniciativa própria.

#Ajuda e comunicação de problemas

Problemas e ideias: o endereço de apoio no fim da página do coder-leo. Inclua o modelo, o servidor, coder-leo version e a saída de /doctor.