coder-leo

Um agente de código para o terminal que roda com modelos locais. Ele lê, escreve e edita código, roda comandos, pesquisa um projeto e mantém uma lista de tarefas, guiado por um modelo que roda na sua própria máquina pelo Ollama ou por qualquer servidor com a API de chat da OpenAI (LM Studio, llama-server, vLLM, mlx). Trabalha do jeito que o Claude Code trabalha, 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 em partes quando precisa e dá ao modelo ferramentas que acham 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

Ele escolhe a versão para a máquina, confere o SHA-256 publicado e instala o binário, a página de manual e os autocompletares do shell em /usr/local (pedindo sudo quando precisa), em ~/.local ou na pasta do próprio Termux. Rodar de novo atualiza; sh -s -- --uninstall remove.

Você também precisa de um servidor de modelos com um modelo que suporte ferramentas:

• Ollama (padrã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 rode coder-leo. Na primeira vez, escolha um modelo da lista; ele fica guardado. Digite o que você quer; /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ão e a pasta. A linha abaixo do prompt mostra o modo, o modelo, quanto do contexto está em uso e o branch do git.

#Trabalhando com ele

• Peça mudanças, não conselhos. Ele edita os arquivos e roda o build ou os testes sozinho; nunca cola código para você aplicar.
• @caminho anexa um arquivo ou uma pasta à mensagem (Tab completa, com busca aproximada). Um arquivo grande demais para a janela entra como esboço, e o modelo lê as partes de que precisa.
• !comando roda um comando no shell e guarda a saída na conversa.
• #texto salva uma nota no CLAUDE.md do projeto.
• Esc ou Ctrl+C interrompe a resposta. O que você digitar enquanto isso espera no próximo prompt.
• Shift+Tab alterna o modo de permissão; Ctrl+O liga e desliga a saída completa das ferramentas; Ctrl+T mostra a lista de tarefas; Esc Esc volta atrás; Ctrl+R pesquisa o histórico; Ctrl+J insere uma linha nova; uma colagem grande vira um marcador.
• As palavras think, think hard e ultrathink num pedido aumentam o raciocínio de um modelo que pensa, naquele turno.

#Ferramentas

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

#A janela de contexto

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

• Tamanho: escolhido pelo limite do modelo e pela memória da máquina (/ctx mostra, /ctx 32k ou /ctx auto muda). A contagem é uma estimativa corrigida pelo que o servidor informa.
• Prefixo estável: o prompt de sistema não muda durante a sessão, então o servidor reaproveita o cache em vez de reavaliar tudo.
• Resultados no orçamento: cada resultado de ferramenta é cortado no que cabe; a saída completa vai para um arquivo cujo caminho o modelo recebe, para ler em partes ou pesquisar com Grep.
• Limpeza a 70%: resultados antigos de ferramentas viram notas de uma linha (os últimos ficam inteiros).
• Resumo a 85%, ou /compact [o que manter]: um resumo estruturado de passagem de bastão substitui a conversa, mantendo os últimos turnos ao pé da letra; uma conversa longa demais para resumir de uma vez é resumida em partes e juntada. A transcrição fica no disco, e o Recall pesquisa nela.
• Mapa do repositório: os arquivos mais referenciados 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á usando 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 rodar 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 roda tudo sem perguntar, como as primeiras versões faziam, e é o padrão a não ser que os seus ajustes digam outra coisa. Comandos destrutivos (remover pastas amplas, descartar trabalho do git, push forçado, sudo, apagar tabelas) ainda perguntam no modo yolo; "guard": false nos ajustes desliga isso.

Regras nos ajustes decidem antes do modo: "allow": ["Bash(git *)", "Read"], "deny": ["Bash(rm *)"], "ask": ["Write"]. Responder a a um pedido de permissão libera aquela ferramenta pela sessão; responder com palavras as manda ao modelo como instruções.

#Sessões

Cada sessão é salva enquanto acontece em ~/.config/coder-leo/sessions/<projeto>/. coder-leo -c continua a última, --resume <id> ou /resume escolhe uma, /rename dá nome, /export grava como Markdown. Antes de cada edição o arquivo ganha um ponto de restauração: /rewind (ou Esc Esc) volta a um turno anterior, restaurando os arquivos mudados desde então e cortando a conversa ali.

#Instruções, comandos, skills, agentes

• CLAUDE.md ou AGENTS.md no projeto (e nas pastas acima dele, e em ~/.config/coder-leo/, e em ~/.claude/) entram no prompt de sistema: convenções, comandos de build, o que evitar. Linhas @caminho dentro deles importam outros arquivos. /init pede ao modelo para escrever um. /memory lista o que está carregado.
• Comandos personalizados: arquivos Markdown em .coder-leo/commands/ (ou .claude/commands/, no projeto ou na pasta pessoal), rodados como /nome argumentos. $ARGUMENTS, $1, ` !comando e @arquivo 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 para o modelo com as descrições; ele carrega uma com a ferramenta Skill quando a tarefa combina, ou você roda /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 os roda. De fábrica: explore, plan, general, review.
• Hooks: comandos de shell em volta dos eventos (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStop, PreCompact, SessionEnd), com o evento em JSON no stdin; sair com código 2 bloqueia com o motivo, e uma resposta em JSON pode permitir, negar ou acrescentar contexto. O mesmo protocolo do Claude Code.
• MCP: servidores do .mcp.json (do projeto ou da pasta pessoal) ou de mcpServers nos ajustes, por stdio ou HTTP; as ferramentas deles aparecem como mcp__servidor__ferramenta e os prompts como comandos. /mcp lista.

#Ajustes

~/.config/coder-leo/settings.json, depois .coder-leo/settings.json e .coder-leo/settings.local.json no projeto, cada um sobrepondo o 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á valendo e de onde veio; /doctor confere o servidor, o modelo, a memória e a configuração.

#Sem terminal

coder-leo -p "pedido" responde uma vez: a resposta no stdout, todo 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 conforme 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 roda na sua máquina: o modelo, os arquivos, a conversa. O programa só acessa a rede quando o modelo chama WebFetch ou WebSearch para a sua tarefa (com pedido de permissão, fora do modo yolo), quando você configura um servidor MCP que sai para fora e quando você roda coder-leo update. Sem contas, sem telemetria, nada enviado para lugar nenhum.

#Atualizações

coder-leo update confere no site se há uma versão mais nova e a instala (pelo Homebrew, numa cópia do Homebrew); coder-leo update --check só avisa. O programa nunca confere sozinho.

#Ajuda e relatos de problemas

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