Aider + Ollama: programar no terminal com um agente 100% local

#Por que usar Aider no terminal

Enquanto Cline ou Continue funcionam no VS Code, Aider aposta no terminal. Você permanece no seu shell, na raiz do seu repositório git, e dialoga com o modelo como se estivesse conversando com um colega que tivesse acesso ao código. É um fluxo de trabalho diferente, mais próximo da linha de comando, que agrada quem vive no tmux e não gosta de tirar as mãos do teclado.

Centrado em git

Cada modificação aceita se torna um commit limpo, com uma mensagem escrita pelo Aider. Seu histórico permanece legível e você pode desfazer qualquer alteração com um simples git revert.

Mapeamento automático de repositório

O Aider constrói um mapa do seu repositório (assinaturas de funções, classes, estrutura) e o envia ao modelo junto com os arquivos abertos. O modelo entende o contexto sem que você carregue todo o projeto.

Independente do editor

Aider modifica os arquivos no disco. Você continua usando seu editor habitual em paralelo: Aider vê suas alterações, e você vê as alterações dele.

100 % local com Ollama

Conectado ao Ollama, o modelo roda na sua GPU. Seu código e seus prompts nunca saem do computador, o que muda tudo para código proprietário ou sob NDA.

#Pré-requisitos e instalação

Três componentes: Python para o Aider, Ollama em execução com um modelo de código carregado e um repositório git. O Aider exige um repositório git para funcionar plenamente — é o Aider que controla os commits.

1. 01
   Verifique Ollama

   Ollama deve estar escutando na sua porta padrão. Execute ollama list para confirmar que ele responde e ver os modelos já instalados.
2. 02
   Instale Aider

   O método recomendado é usar o pipx ou o script de instalação oficial, que isola o Aider em seu próprio ambiente para evitar conflitos de dependências do Python.
3. 03
   Acesse um repositório git

   Abra um terminal na raiz de um projeto versionado. Se o projeto ainda não estiver sob git, faça um git init primeiro: o Aider precisa disso para commitar suas alterações.

# Via pipx (isole Aider, n'encombre pas votre Python système)
python -m pip install --user pipx
pipx install aider-chat

# Vérifier l'installation
aider --version

#Configurar Aider para Ollama

Aider fala com Ollama via seu endpoint compatível com OpenAI. Duas coisas para configurar: a URL base do Ollama (variável de ambiente) e o modelo a ser usado. A forma mais limpa é criar um arquivo .aider.conf.yml na raiz do projeto (ou no seu diretório pessoal para configuração global), para não precisar digitar as opções a cada lançamento.

# Indique à Aider où trouver l'API Ollama
export OLLAMA_API_BASE=http://127.0.0.1:11434

# Lancer Aider avec un modèle Ollama (préfixe ollama/)
aider --model ollama/qwen3.5:9b

Para não ter que digitar tudo de novo, salve esses ajustes em um arquivo de configuração. O Aider lê automaticamente um .aider.conf.yml encontrado na raiz do repositório ou no seu diretório pessoal.

# Modèle principal servi par Ollama (préfixe ollama/ obligatoire)
model: ollama/devstral:24b

# Modèle léger pour les tâches annexes (messages de commit, résumés)
weak-model: ollama/qwen3.5:9b

# Auto-commit des modifications acceptées (comportement par défaut)
auto-commits: true

# Ne pas committer automatiquement les fichiers que VOUS modifiez
dirty-commits: false

- name: ollama/devstral:24b
  extra_params:
    num_ctx: 8192

#Qual modelo de acordo com a VRAM

Aider envia muito contexto (arquivos adicionados + mapa do repositório) e espera um patch bem formatado de volta. Um modelo muito pequeno gera diffs quebrados que Aider não consegue aplicar. Escolha o maior modelo de código que sua placa consiga carregar com conforto, mantendo margem para o contexto.

#Workflow de ponta a ponta

Este é o ciclo típico de uma modificação, desde a inicialização do Aider até o commit. Depois de pegar esse ritmo, você faz uma alteração após a outra sem nunca sair do terminal.

1. 01
   Inicie o Aider na raiz do repositório

   O Aider inicia, lê a configuração, constrói o mapa do repositório e exibe um prompt. Ele indica o modelo ativo e a quantidade de arquivos detectados.
2. 02
   Adicione os arquivos envolvidos com /add

   Adicione apenas os arquivos que a tarefa precisa modificar. Quanto menos arquivos houver no contexto, mais preciso o modelo será. O repo-map já dá ao modelo uma visão do restante do projeto.
3. 03
   Descreva a modificação em francês

   Digite sua solicitação em linguagem natural: “adicione a validação de e-mail no formulário de inscrição”. O Aider pensa e depois propõe um patch.
4. 04
   Revise o diff proposto

   Aider mostra o diff antes de aplicar as alterações. Verifique-o. Se algo estiver errado, responda para corrigir: « não, use uma regex mais rigorosa ».
5. 05
   Deixe o Aider criar os commits

   Depois que o patch é aplicado, o Aider cria automaticamente um commit com uma mensagem descritiva. Seu histórico Git permanece limpo e cada alteração é rastreável.
6. 06
   Itere ou desfaça

   Continue com a modificação seguinte. Se um commit do Aider não for adequado, /undo anula o último commit que ele criou, sem afetar o resto.

$ aider
Aider v0.x — model: ollama/devstral:24b
Repo-map: 42 fichiers

> /add src/auth/register.py
Added src/auth/register.py to the chat

> Ajoute la validation de l'email dans le formulaire d'inscription

[Aider propose un diff, l'applique, puis :]
Commit a1b2c3d  feat: valider le format de l'email à l'inscription

#Comandos principais no dia a dia

O Aider é controlado por comandos iniciados com uma barra (/) no seu prompt. Poucos comandos bastam para cobrir 90% dos usos.

/add fichier

Adiciona um ou mais arquivos ao contexto da edição. É nesses arquivos que o Aider escreverá. Limite-se ao estritamente necessário.

/drop fichier

Remove um arquivo do contexto. Útil quando você muda de tarefa para recomeçar com um contexto limpo.

/architect

Ativa o modo de planejar e depois codificar: o modelo primeiro raciocina sobre a abordagem e depois gera o diff. Ideal para mudanças não triviais.

/diff

Mostra as alterações feitas desde o último commit, para revisar o que o Aider mudou antes de continuar.

/undo

Anula o último commit criado pelo Aider. Uma proteção imediata caso uma modificação dê errado.

/run commande

Executa um comando shell (testes, linter) e reinjeta a saída no chat. O Aider pode então corrigir com base nos erros reais.

/ask question

Faz uma pergunta sobre o código SEM acionar nenhuma modificação nem commit. Para entender antes de agir.

#Limitações da execução local em relação à nuvem

Sejamos honestos: um modelo local com 8 a 16 GB não iguala um modelo de nuvem de ponta. Conhecer as limitações evita a frustração e ajuda a escolher a ferramenta certa para a tarefa.

Diffs às vezes mal formados

Modelos pequenos às vezes produzem um patch que o Aider não consegue aplicar (formato inválido). Aumentar o tamanho do modelo ou ampliar num_ctx reduz significativamente esse problema.

Contexto mais curto

Um modelo em nuvem dá conta de dezenas de arquivos. Ao usar um modelo local, mantenha o contexto enxuto: adicione poucos arquivos por vez com /add e use o repo-map em vez de carregar tudo.

Raciocínio envolvendo vários arquivos

As refatorações que afetam muitos arquivos de uma só vez continuam sendo o ponto fraco dos modelos locais. Divida em várias tarefas pequenas ou mude para /architect para estruturar o trabalho.

Velocidade ligada à GPU

A latência depende da sua placa. Um 32B em uma placa modesta será lento. Se a rapidez de resposta for prioridade, um 7B ou 14B bem ajustado é mais agradável no dia a dia.

#Perguntas frequentes