A Inteligência Artificial já deixou de ser uma novidade experimental no desenvolvimento de software e passou a integrar o fluxo diário de trabalho.
Autocomplete inteligente, geração de trechos de código e explicações contextuais já são recursos comuns. O próximo estágio dessa evolução são os coding agents, sistemas que vão além da sugestão passiva e assumem um papel ativo no desenvolvimento, entendendo objetivos, navegando pelo projeto e executando tarefas completas de forma autônoma ou semi assistida.
Em vez de apenas responder perguntas, esses agentes conseguem ler arquivos do repositório, criar ou refatorar código, rodar testes, executar comandos no terminal e iterar sobre erros até chegar a um resultado funcional. Na prática, é como ter um programador assistente sempre disponível, integrado diretamente ao ambiente de desenvolvimento e capaz de operar no mesmo nível de contexto que um humano teria ao abrir o projeto.
Esse cenário fica ainda mais interessante quando tudo isso acontece localmente. Rodar um agente de código no próprio terminal elimina dependência de APIs externas, reduz custos operacionais e garante controle total sobre o código e os dados do projeto. Isso é especialmente relevante em ambientes corporativos, projetos sensíveis ou simplesmente para quem quer experimentar IA de forma mais livre e previsível.
É exatamente essa combinação que surge ao integrar o Claude Code com o Ollama. O Claude Code fornece a lógica de agente e a experiência madura de interação via terminal, enquanto o Ollama permite executar modelos de linguagem localmente, de forma simples e controlada. O resultado é um assistente de desenvolvimento poderoso, privado e totalmente sob seu controle. Neste guia, você vai ver como montar esse setup passo a passo e começar a usar agentes de codificação rodando direto na sua máquina.
O Que é o Claude Code?
O Claude Code é uma ferramenta de linha de comando criada pela Anthropic que atua como um assistente de programação com comportamento agente. Ele consegue entender o contexto do projeto, ler arquivos, alterar código e executar comandos no diretório de trabalho, tudo pelo terminal.
Originalmente, o Claude Code se conectava apenas aos servidores da Anthropic. Hoje, ele pode apontar para qualquer servidor compatível com a API da Anthropic, o que abre espaço para rodar tudo localmente usando o Ollama.
O Que é o Ollama?
O Ollama é uma plataforma que permite executar modelos de linguagem localmente no seu computador ou servidor. Em vez de depender de provedores externos, você baixa modelos open source e roda tudo offline, com mais privacidade e previsibilidade.
A proposta é simples: escolher um modelo, baixar e começar a usar. Modelos como qwen3 coder, glm 4.7 e gpt oss funcionam muito bem nesse cenário, desde que ofereçam suporte a tool calling.
Por Que Usar Claude Code com Ollama?
Usar Claude Code com Ollama é uma forma prática de ter um assistente de programação rodando localmente no terminal. Você ganha mais controle, mantém seu código privado e elimina custos com chamadas de API.
Esse setup é ideal para testar fluxos de trabalho com agentes, trabalhar em ambientes isolados ou simplesmente experimentar modelos open source sem depender da nuvem, mantendo a experiência de pair programming com IA. Lembrando que isso não substitui seu conhecimento, apenas o potencializa.
Esse modelo faz sentido especialmente se você quer manter dados sensíveis protegidos, evitar custos recorrentes, trabalhar offline ou explorar modelos e pipelines personalizados.
Instalação e Configuração
O primeiro passo é instalar o Ollama no seu sistema. Ele está disponível para macOS, Linux e Windows e a instalação é bem simples. Acesse o site oficial do Ollama e faça a instalação de acordo com seu SO:
Depois disso, você precisa baixar um modelo local. Abra seu terminal ou prompt de comando e execute:
ollama pull qwen3-coder:30b
Neste exemplo usamos o qwen3 coder de 30 bilhões de parâmetros, mas você pode escolher modelos maiores se o seu hardware permitir.
Também é importante aumentar a janela de contexto do modelo nas configurações do Ollama. Um valor de 32k costuma funcionar bem para uso com agentes.
Com o Ollama configurado, o próximo passo é instalar o Claude Code. Ele é um CLI independente que se comunica com uma API compatível com a Anthropic. A instalação varia conforme o sistema operacional, mas envolve basicamente executar o script oficial de instalação. Acesse o site oficial e siga os passos de instalação de acordo com seu SO:
Depois de instalado, você precisa configurar duas variáveis de ambiente. A primeira é o token de autenticação, que pode ser qualquer valor simbólico, como “ollama”. A segunda é a URL base da API, que deve apontar para o servidor local do Ollama em http://localhost:11434. Aqui estão as variáveis:
macOS/Linux:
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_BASE_URL=http://localhost:11434
Windows (via Power Shell):
$env:ANTHROPIC_AUTH_TOKEN=”ollama”
$env:ANTHROPIC_BASE_URL=”http://localhost:11434″
Com isso feito, já dá para executar o Claude Code apontando para o modelo local:
claude –model qwen3-coder:30b
No Windows, se o comando não for encontrado, basta chamar o executável diretamente no diretório .local bin do seu usuário assim:
C:\Users\<seu usuario>\.local\bin\claude.exe –model qwen3-coder:30b
A partir desse momento, o Claude Code já estará rodando localmente e interagindo com o modelo carregado no Ollama. Com base no seu conhecimento, defina os prompts, envie para o Claude Code e acompanhe a execução, confirmando/autorizando quando for solicitado.
Conclusão
Existem alguns pontos que precisam ser avaliados com cuidado antes de adotar esse tipo de setup. O primeiro deles é a limitação de hardware. Modelos maiores consomem mais memória e, dependendo do tamanho e da arquitetura escolhida, podem exigir uma GPU dedicada para entregar uma experiência fluida. Em máquinas mais modestas, isso pode significar tempos de resposta maiores ou a necessidade de optar por modelos menores e mais leves.
Outro fator relevante é a maturidade dos modelos open source. Embora tenham evoluído rapidamente, eles ainda podem ficar atrás dos modelos proprietários da Anthropic em tarefas mais complexas, como raciocínio profundo, planejamento de múltiplos passos ou compreensão de contextos muito extensos. Em cenários de alta complexidade, essa diferença pode aparecer. Ainda assim, para grande parte dos fluxos de desenvolvimento do dia a dia, como refatoração, automação de tarefas, geração de código e suporte a debugging, os resultados já são consistentes e confiáveis.
Dentro desse contexto, a integração entre Claude Code e Ollama se destaca por tornar os agentes de programação locais muito mais acessíveis. O Claude Code entrega uma experiência de agente bem definida, capaz de interagir com o projeto de forma ativa, enquanto o Ollama oferece a liberdade de escolher, trocar e ajustar modelos conforme a necessidade, tudo rodando na própria máquina.
No final, trata-se de uma solução especialmente atraente para quem prioriza privacidade, previsibilidade de custos e autonomia técnica. Você ganha a capacidade de experimentar, ajustar e evoluir seu fluxo de desenvolvimento com IA sem depender da nuvem, mantendo tudo concentrado no terminal e sob seu total controle.
David Matos