Coding Agent Local com Pi e LM Studio — Setup para 0€

No mês passado, fui para uma estação de comboios sem internet. Tinha um bug para resolver num projeto — nada crítico, mas chato. Abri o portátil, tentei usar o Claude Code, e nada. O modelo não respondia. Fiquei a olhar para o ecrã durante 20 minutos a pensar que, sem cloud, o meu coding agent era um peso de papel.

Já usei Claude Code, Codex e Gemini CLI. São ferramentas boas, mas têm um problema: ou pagas por token, ou estás dependente de um servidor remoto. Quando fico sem internet — e ainda acontece — fico sem agente. E mesmo com internet, o custo acumula rápido em projetos maiores.

Há uns meses comecei a explorar a alternativa: coding agents open-source que correm localmente. A combinação que mais gostei foi Pi (o agente) + LM Studio (o servidor) + Qwen3.6-27b (o modelo). Tudo em localhost, zero custos, privacidade total. Nada de chaves de API, nada de enviar código para servidores de terceiros.

Arquitetura — Como é que isto funciona?

A ideia é simples. Um coding agent (como o Claude Code, Codex ou Pi) comunica com um modelo através de uma API HTTP. Envia um pedido, o modelo devolve tokens, e o agente usa ferramentas (ler ficheiros, editar, correr comandos) para fazer o trabalho.

No setup tradicional, essa API está num datacenter algures. No setup local, está na tua máquina.

┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│     Pi           │ ──→  │   LM Studio      │ ──→  │   Qwen3.6-27b   │
│  (coding agent)  │ ←──  │  (localhost:1234) │ ←──  │    (modelo)     │
└──────────────────┘      └──────────────────┘      └──────────────────┘

O Pi fala o protocolo chat-completions da OpenAI. O LM Studio expõe um endpoint compatível em http://localhost:1234/v1. Basta apontar um ao outro e está feito. O modelo vive na GPU, o servidor faz de ponte, o agente faz o trabalho de verdade.

Passo 1: Verificar o Hardware

Antes de instalar seja o que for, descobre o que a tua máquina aguenta. Um modelo de 27B parâmetros em quantização 4-bit (Q4) pesa ~15-16 GB de weights. Depois tens de somar a cache de contexto (KV cache) por cima.

Há duas ferramentas web que ajudam:

• canirun.ai — deteta o teu hardware e classifica modelos de “corre bem” a “pesado demais”
• caniusellm.com — semelhante, com recomendações de quantização (Q4 vs Q8 vs FP16)

Resumo rápido:

Nota pessoal: Uso um M1 Max com 64 GB. Consigo correr o Qwen3.6-27b em Q4_K_M com contexto de 64K sem suar. Se tens Apple Silicon, a memória unificada é uma vantagem enorme — tudo o que a máquina tem está disponível para o modelo.

Passo 2: Instalar o LM Studio e Carregar o Modelo

O LM Studio é a forma mais fácil de ter um servidor local de modelos. Tem interface gráfica, busca de modelos no HuggingFace, e expõe uma API compatível com OpenAI.

1. Descarrega o LM Studio em lmstudio.ai/download (macOS, Windows ou Linux)
2. Na pesquisa de modelos, procura por qwen3.6-27b
3. Escolhe uma quantização — Q4_K_M é o ponto ideal entre qualidade e tamanho
4. Carrega o modelo
5. Vai ao separador Developer e ativa o Start Server

O servidor fica disponível em http://localhost:1234/v1. Podes confirmar com:

curl http://localhost:1234/v1/models

Se vires o modelo listado, está pronto.

Importante: Carregar o modelo no LM Studio não é suficiente. Tens de ir ao separador Developer e ligar o servidor explicitamente. É o erro mais comum.

Passo 3: Instalar o Pi

O Pi é o coding agent minimalista do Mario Zechner. Dá ao modelo quatro ferramentas — read, write, edit, bash — e é extremamente eficiente em tokens.

Instala com o script oficial:

curl -fsSL https://pi.dev/install.sh | sh

Ou via npm:

npm install -g @earendil-works/pi-coding-agent

Confirma a instalação:

pi --version

Passo 4: Configurar o models.json

O Pi descobre providers e modelos através de um ficheiro models.json. Abre-o:

vi ~/.pi/agent/models.json

E adiciona esta configuração:

{
  "providers": {
    "lmstudio": {
      "baseUrl": "http://localhost:1234/v1",
      "api": "openai-completions",
      "apiKey": "lm-studio",
      "models": [
        {
          "id": "qwen/qwen3.6-27b",
          "input": ["text"]
        }
      ]
    }
  }
}

Alguns detalhes importantes:

• "api": "openai-completions" — diz ao Pi para usar o formato de chat completions da OpenAI. É isto que faz qualquer servidor local compatível (LM Studio, Ollama, vLLM) funcionar sem adaptações.
• "apiKey": "lm-studio" — o LM Studio ignora a chave, mas o protocolo OpenAI exige o campo. Qualquer string não vazia serve.
• O id do modelo tem de coincidir exatamente com o que o LM Studio expõe. Se não tiveres a certeza, corre:

  curl http://localhost:1234/v1/models

  Copia o id do JSON que aparece e usa esse.

Depois de guardar, abre o Pi e verifica com /model — deves ver o teu modelo local listado. Podes alternar entre modelos locais e cloud no mesmo picker.

Passo 5: Tamanho do Contexto

A janela de contexto é a memória de trabalho do modelo. Tudo o que o agente “vê” (histórico da conversa, ficheiros abertos, output de comandos) tem de caber ali.

Em modelos cloud, o contexto é fixo e gerido pelo provider. Em modelos locais, és tu que decides — e pagas o custo em VRAM.

No LM Studio, define o contexto nas definições do modelo (antes ou depois de carregar) e reload para aplicar.

Quanta VRAM leva cada tamanho?

Estes valores são para um modelo de 27B parâmetros em Q4. A base de ~16 GB de weights é fixa; o extra varia com o contexto:

A minha recomendação: começa em 64K. É mais que suficiente para o dia-a-dia. Se o agente começar a “esquecer-se” de coisas no meio da sessão, sobes para 128K. 256K é para quando precisas mesmo de carregar o repositório inteiro.

256K Local vs 1M Cloud

O Qwen3.6-27b suporta até 256K tokens de contexto nativamente. Para comparação, o Claude Opus 4.8 corre com 1M tokens. Há um fosso, mas não é tão mau como parece.

256K ainda é muito. Dá para:

• Um módulo e os seus testes
• Uma funcionalidade completa com vários ficheiros
• Uma sessão de debugging longa com histórico

Onde o 1M da cloud ganha é no cenário de repositório inteiro: carregar um projeto grande de uma vez, tarefas agentic com centenas de passos, análises que precisam de documentos enormes em contexto.

A minha regra:

• Local (Qwen3.6-27b): edições focadas, coding do dia-a-dia, refactors contidos, trabalho que queres offline ou privado, tarefas onde não queres gastar tokens
• Cloud (Claude / Codex / Gemini): contexto de repositório inteiro, raciocínio mais exigente, runs agentic longas

Reutilizar Skills do Claude Code

Se já tens skills (SKILL.md) no Claude Code, tenho boas notícias: o Pi usa o mesmo formato Agent Skills Standard.

A má notícia é que o Pi não descobre skills fora das suas pastas por defeito. Se as tuas skills estão em ~/.claude/skills, tens de o dizer explicitamente.

Configura no ~/.pi/agent/settings.json:

{
  "defaultProvider": "lmstudio",
  "defaultModel": "qwen/qwen3.6-27b",
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

O defaultProvider e defaultModel são opcionais — fazem o Pi arrancar já no modelo local, sem teres de escolher manualmente.

Depois de editares, reinicia o Pi. As skills só são lidas ao arranque. A partir daí, o comportamento é igual ao Claude Code: as descrições carregam em contexto, e as instruções completas só entram quando uma tarefa corresponde.

Gotchas — O que me tramou

Uma lista do que me aconteceu e do que deves evitar:

• LM Studio server tem de estar ligado. Carregar o modelo não chega. O Server tem de estar ativo no separador Developer, senão o Pi não consegue contactar localhost:1234.
• Model ID tem de coincidir. Se no models.json escreveste qwen/qwen3.6-27b e o servidor expõe qwen3.6-27b-Q4_K_M, não vai funcionar. Corre curl http://localhost:1234/v1/models e copia exatamente o que aparece.
• É mais lento que cloud. Um modelo de 27B na tua GPU não bate os token rates de um servidor da Anthropic. A primeira resposta demora mais, e geração é mais lenta. É normal. Compensa pelo custo zero e privacidade.
• O Pi é token-eficiente. Isto é uma vantagem para modelos locais. O system prompt do Pi é muito mais pequeno que o do Claude Code, o que significa que sobra mais contexto para o teu código.

Workflow Híbrido — Planear com Claude, Executar Local

O Pi não é exclusivamente local. Suporta cloud também, o que abre um workflow que uso todos os dias.

Faz login no Pi com a tua conta Anthropic:

/login

Funciona com subscrição Claude Pro/Max ou API key. O Claude aparece no mesmo /model que o modelo local.

O workflow:

1. Planear com Claude — arquitetar uma funcionalidade, dividir o trabalho em passos, usar o 1M de contexto para carregar o repositório inteiro. Isto é onde o raciocínio mais forte faz diferença.
2. Executar com local — /model qwen/qwen3.6-27b e mãos à obra. As edições repetitivas, correr testes, fazer o refactor em si. Grátis, offline, privado.
3. Repetir — Volta e meia volto ao Claude para reavaliar ou desenrascar um problema mais complexo. Depois volto ao local.

Consigo alternar entre modelos na mesma sessão sem perder contexto. O histórico fica todo lá — só muda qual o modelo que está a gerar tokens.

Uso o OpenSpec para criar os planos: peço ao Claude para desenhar a solução, e executo os passos no modelo local. Funciona bem para projetos de tamanho médio.

Dica: Se vais usar o modelo local para a maior parte do trabalho, considera configurar "defaultProvider": "lmstudio" no settings.json. O Pi arranca logo no modelo local, e só mudas para cloud quando precisas.

O que aprendi com este setup

Depois de um mês a usar o Pi com modelos locais, a minha conclusão é mista. Funciona. Para tarefas do dia-a-dia — edições, refactors pequenos, debugging — aguenta-se bem. A privacidade é total, o custo é zero, e não dependo de internet. Isso já vale o setup.

Mas também aprendi que local não substitui cloud para tudo. Modelos de 27B são competentes, mas não têm o raciocínio de um Claude Opus ou GPT-5. Quando o problema é complexo — arquitetar uma funcionalidade nova, debuggar um bug que envolve múltiplos serviços, planear um refactor grande — volto ao Claude. E não me sinto mal por isso.

O que o setup local me deu foi independência. Poder trabalhar sem pensar no custo por token, sem me preocupar se o código que estou a editar está a ser enviado para um servidor nos EUA. Isso é mais importante do que ter o modelo mais inteligente do mundo.

Se tens um Mac com Apple Silicon e pelo menos 32 GB de RAM, experimenta. Pior das hipóteses, gastas uma tarde a configurar e aprendes qualquer coisa. Melhor das hipóteses, ficas com um coding agent que funciona sem te pagar nada a ninguém.

Recursos

• LM Studio — servidor local de modelos
• Pi coding agent — terminal coding agent
• Pi docs — Quickstart
• canirun.ai — verifica o teu hardware
• caniusellm.com — recomendações de quantização
• Agent Skills Standard — formato de skills partilhado
• OpenSpec — planos para workflow híbrido
• Artigo original do Zarar — inspiração para este guia