Pular para o conteudo
Voltar aos artigos
pi-coding-agentclaude-codetutorialalternativaai-coding

Pi Coding Agent: a Alternativa Minimalista ao Claude Code

Tutorial passo a passo do Pi, o coding agent de terminal open-source: instale, conecte qualquer modelo e veja onde ele substitui (ou não) o Claude Code.

14 min de leitura

Pi Coding Agent: a Alternativa Minimalista ao Claude Code

Um coding agent de terminal open-source, com quatro ferramentas e um system prompt minúsculo. Este tutorial mostra como instalar, conectar qualquer modelo e decidir se ele substitui o Claude Code no seu fluxo.

Contexto

Você já usa o Claude Code. Conhece o ciclo: abre o terminal, descreve a tarefa, a IA lê os arquivos, edita, roda comandos e devolve o resultado. Funciona. Mas talvez você tenha sentido o que muita gente sente depois de alguns meses: a ferramenta cresceu. A cada release o system prompt muda, novas funcionalidades aparecem, o comportamento do modelo desliza um pouco, e fluxos que você tinha afinado param de funcionar do mesmo jeito.

O Pi nasceu exatamente dessa frustração. É um coding agent de terminal open-source que faz a aposta oposta: começar mínimo e deixar você construir o resto. Em vez de desligar funcionalidades que você não usa, você liga só as que precisa.

Este tutorial cobre a instalação, a conexão com modelos, o uso no dia a dia, e uma avaliação honesta de onde o Pi substitui bem o Claude Code para criar aplicativos com IA, e onde não substitui.

O que é o Pi

Pi é um "coding harness" minimalista de terminal, descrito pela própria documentação como uma CLI para o Claude e outros modelos. Ele roda no seu terminal, lê e escreve arquivos, executa comandos no shell e mantém uma conversa com o modelo sobre o seu código. Até aqui, igual a qualquer coding agent.

A diferença está na filosofia. O Pi é open-source sob licença MIT e foi criado por Mario Zechner, o mesmo autor do libgdx, framework de jogos amplamente usado em Java. Não existe conta SaaS, dashboard na nuvem nem "workspace" remoto. Você instala um binário de linha de comando, aponta para o provedor de modelo que quiser, e ele fica no terminal trabalhando no seu projeto.

Por padrão, o Pi entrega ao modelo apenas quatro ferramentas:

Ferramenta O que faz
read Lê arquivos
write Cria ou sobrescreve arquivos
edit Modifica arquivos existentes
bash Executa comandos no shell

O argumento do criador é direto: para um coding agent eficaz, essas quatro ferramentas bastam. O system prompt do Pi tem cerca de mil tokens, contra um prompt bem maior no Claude Code. A tese por trás disso é que os modelos de fronteira já foram treinados intensivamente para operar como agentes, e entendem o que é um coding agent sem precisar de instruções verbosas. Tudo além do mínimo (memória, sub-agentes, MCP, temas, skills) entra por extensões que você escolhe.

Pi vs Claude Code: o que realmente muda

Antes do passo a passo, vale entender o que você ganha e o que você perde ao trocar. A comparação abaixo é a parte mais importante para decidir se a migração faz sentido para você.

Dimensão Pi Claude Code
Modelos 15+ provedores, troca no meio da sessão Foco em modelos Anthropic
Ferramentas padrão 4 (read, write, edit, bash) Conjunto mais amplo embutido
System prompt Mínimo (~1.000 tokens) Substancialmente maior
Extensibilidade Módulos TypeScript + skills MCP + hooks + skills
Observabilidade Sessão totalmente visível e editável Sub-agentes funcionam como caixa-preta
Custo da ferramenta Gratuita (você paga o modelo) Assinatura + uso de modelo
Licença Open-source (MIT) Proprietária

Algumas diferenças merecem explicação, porque mudam o seu dia a dia:

Observabilidade. A crítica central do criador ao Claude Code é a opacidade. Quando o Claude Code dispara um sub-agente, você não vê o que ele faz por dentro. O Pi aposta no oposto: a sessão inteira é visível, e o planejamento acontece em arquivos de markdown que você pode ler e editar junto com a IA.

Modelo de segurança. O Pi não finge restringir comportamento malicioso. A posição do criador é honesta: a partir do momento em que um agente pode escrever e executar código, qualquer barreira no nível do prompt é teatro. Na prática, o Pi roda as ferramentas sem camadas pesadas de aprovação por padrão. Você ou confia no agente, ou o isola num container. Voltaremos a esse ponto, porque ele importa quando você aponta o agente para código sério.

O que não vem embutido. O Pi deliberadamente não traz to-do lists, plan mode, bash em background nem MCP por padrão. O raciocínio: modelos lidam mal com estado efêmero (markdown em arquivo é melhor que lista interna), plan mode esconde sub-agentes (planejar em arquivo é mais transparente), processos longos pedem tmux (mais controle e debug), e servidores MCP consomem de 7% a 9% da janela de contexto a cada sessão (ferramentas de CLI com um README são mais econômicas em tokens). Tudo isso existe no Pi, mas como extensão opcional.

Multi-provider de verdade. O Pi foi construído diretamente sobre os SDKs dos provedores, não sobre uma camada genérica. Isso habilita o recurso que o criador considera essencial: trocar de modelo no meio da sessão, levando o contexto junto. Você pode começar com um modelo barato para rascunhar e mudar para um modelo mais forte na hora de fechar.

Vale registrar um dado concreto: em benchmarks como o Terminal-Bench 2.0, o Pi performou de forma competitiva contra Codex, Cursor e Windsurf, sugerindo que a abordagem mínima entrega tanto quanto as alternativas mais sofisticadas.

Tutorial: do zero à primeira sessão

A partir daqui é mão na massa. Os comandos abaixo vêm da documentação oficial em pi.dev.

Passo 1: Instalar

O jeito mais simples no Linux ou macOS é o instalador oficial:

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

Se você prefere o npm (precisa de Node.js), a documentação usa este comando:

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

O --ignore-scripts desativa os scripts de ciclo de vida das dependências durante a instalação. Há também opções com pnpm e bun. Depois de instalar, você roda o agente entrando na pasta do projeto:

cd seu-projeto
pi

Passo 2: Conectar um modelo

O Pi não traz modelo próprio. Você conecta o seu, de duas formas.

Opção A, assinatura (OAuth). Dentro do Pi, rode /login e escolha o provedor. A documentação lista Claude Pro/Max, ChatGPT Plus/Pro e GitHub Copilot. Os tokens renovam sozinhos e ficam salvos em ~/.pi/agent/auth.json. Se você já paga um plano Claude Max, é aqui que ele vira o motor do Pi.

Opção B, API key. Defina a variável de ambiente do provedor antes de subir o Pi:

export ANTHROPIC_API_KEY=sk-ant-...
pi

O Pi suporta mais de 15 provedores via API key, entre eles Anthropic, OpenAI, Google Gemini, DeepSeek, Mistral, Groq, Cerebras, xAI e OpenRouter, além de nuvens como Azure OpenAI, Amazon Bedrock e Google Vertex AI. As variáveis seguem o padrão de cada um (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY e equivalentes).

A ordem de resolução das credenciais é previsível: primeiro a flag --api-key na linha de comando, depois o auth.json, depois variáveis de ambiente, e por fim chaves de provedores customizados.

Dica: se você nunca quer colar a chave no terminal, o auth.json aceita três formatos por campo: o valor literal, uma referência a variável de ambiente, ou um comando de shell prefixado com ! (útil para puxar a chave de um gerenciador de segredos).

Passo 3: A primeira sessão

Com o modelo conectado, é só conversar. Um bom primeiro comando, sugerido pela própria documentação, é pedir ao Pi para se situar no projeto:

Resuma este repositório e me diga como rodar os checks dele.

O Pi vai usar read para ler os arquivos relevantes e bash para inspecionar o projeto, e devolver um resumo. Atalhos essenciais da interface:

Atalho Ação
enter Enviar a mensagem
shift+enter Nova linha
escape ou ctrl+c Interromper o agente
alt+enter Enfileirar uma mensagem de follow-up enquanto ele trabalha
ctrl+o Expandir ou recolher a saída de uma ferramenta

O alt+enter é o que viabiliza o "steering" em tempo real: você corrige o rumo sem esperar o agente terminar. Se mudou de ideia no meio, alt+up traz as mensagens enfileiradas de volta para o editor.

Passo 4: Dar contexto com AGENTS.md

Aqui está o equivalente ao CLAUDE.md. O Pi lê um arquivo AGENTS.md na raiz do projeto com as suas instruções: convenções de código, comandos de build e teste, regras do repositório. Ele também carrega um ~/.pi/agent/AGENTS.md global e procura o arquivo em diretórios pais até a raiz do git.

# na raiz do projeto
echo "# Instruções do projeto" > AGENTS.md

Depois de editar arquivos de contexto, rode /reload dentro do Pi para recarregar sem reiniciar.

Passo 5: Trocar de modelo no meio da conversa

Este é um dos diferenciais práticos. Sem encerrar a sessão, você abre o seletor de modelos com ctrl+l e escolhe outro. Para alternar rápido entre os modelos recentes, use ctrl+p (próximo) e shift+ctrl+p (anterior). O contexto da conversa vai junto, então dá para rascunhar com um modelo econômico e fechar com um modelo mais forte na mesma sessão.

Passo 6: Sessões em árvore

O Pi guarda cada sessão como uma árvore, não como uma lista linear. Cada entrada tem um id e um parentId, e a posição atual marca a folha ativa. Isso permite explorar caminhos diferentes sem perder o que já foi conversado. As sessões ficam em ~/.pi/agent/sessions/, organizadas por diretório de trabalho, em arquivos JSONL.

Os comandos de sessão mais úteis:

Comando O que faz
pi -c Continua a sessão mais recente
pi -r Abre o navegador de sessões anteriores ao iniciar
/tree Navega a árvore da sessão e volta a qualquer ponto
/fork Cria uma nova sessão a partir de uma mensagem anterior
/export [arquivo] Exporta a sessão para HTML
/share Sobe a sessão como gist privado no GitHub, com link compartilhável

Quando você volta a um ponto anterior pelo /tree e digita algo diferente, o Pi cria um novo galho. É a forma natural de testar uma abordagem, não gostar, e voltar para tentar outra sem ruído.

Passo 7: Reaproveitar suas skills do Claude Code

Se você investiu em skills no Claude Code, não precisa recriá-las. O Pi lê skills no mesmo formato (uma pasta com SKILL.md, com frontmatter de name e description, mais scripts/, references/ e assets/ opcionais). Ele descobre skills em vários lugares, incluindo ~/.pi/agent/skills/ e .pi/skills/ no projeto.

Para apontar diretamente para as suas skills existentes do Claude Code, adicione o diretório nas configurações:

{
  "skills": ["~/.claude/skills"]
}

O Pi usa carregamento sob demanda: na inicialização ele só lê nome e descrição de cada skill, e carrega o conteúdo completo via read quando a tarefa casa. É o mesmo princípio de progressive disclosure que você já conhece.

Substituir o Claude Code para criar apps: funciona?

Esta é a pergunta que importa para quem cria aplicativos com IA. A resposta honesta é: depende do que você valoriza.

Para criar um app, o fluxo no Pi é o que você esperaria de qualquer coding agent competente. Você escreve um AGENTS.md com a stack e as convenções, descreve a feature, e o agente lê, escreve, edita e roda comandos. Planejamento complexo você faz em arquivos de markdown que ficam versionados e visíveis, em vez de um plan mode opaco. Para rodar o servidor de desenvolvimento ou processos longos, a recomendação é tmux, que dá controle e logs de verdade, no lugar de um bash em background escondido.

O Pi substitui bem o Claude Code se você:

  • Quer controle e observabilidade totais sobre o que o agente faz
  • Usa, ou quer usar, vários modelos e provedores (inclusive modelos locais ou self-hosted)
  • Se incomoda com a mudança de comportamento a cada release do Claude Code
  • Gosta de montar o próprio fluxo a partir de peças, em vez de desligar o que não usa
  • Trabalha num time regulado que precisa de auditabilidade e de rotear o tráfego do agente

Talvez seja melhor ficar no Claude Code se você:

  • Quer tudo funcionando out-of-the-box, sem montar extensões
  • Prefere um app de desktop ou GUI: o Pi é só terminal
  • Depende de funcionalidades específicas do ecossistema do Claude Code
  • Está começando agora e quer zero configuração

Há trade-offs reais que a comparação não pode esconder. O modelo de segurança "confie ou isole" transfere a responsabilidade inteira para você: conteúdo malicioso num arquivo ou na saída de um comando pode influenciar o agente via prompt injection. Para projetos sérios, rodar o Pi dentro de um container deixa de ser opcional. A API unificada, como qualquer camada que unifica provedores diferentes, tem abstrações que vazam. E montar o seu fluxo a partir de extensões custa tempo de configuração que o Claude Code já entrega pronto.

Não existe ferramenta perfeita. O Pi troca conveniência embutida por controle e transparência. Se essa é a troca que você quer, ele substitui o Claude Code muito bem.

Recepção da comunidade

A recepção tem sido positiva. Em fóruns como Reddit e Hacker News, o Pi virou conhecido como "o minimalista que não atrapalha", a ideia de instalar, apontar para um projeto e começar a trabalhar sem cerimônia. Reviews independentes ecoam o elogio à filosofia: você constrói o agente que quer, em vez de desligar funcionalidades que não usa.

Ao redor do core mínimo já cresceu um ecossistema de extensões mantidas pela comunidade, cobrindo memória persistente entre sessões, exibição de status de modelo e tokens, rastreamento de tarefas em múltiplos passos, sub-agentes e adaptadores de MCP. Para quem não quer pesquisar, há até bundles que adicionam dezenas de skills e temas de uma vez.

A maturidade ainda é a de um projeto jovem comparado ao Claude Code: o ecossistema é menor, as extensões têm graus variados de polimento, e parte do que no Claude Code é nativo, no Pi você instala. Vale entrar com essa expectativa.

Na Prática

Quickstart para sair do zero e ter o Pi rodando no seu projeto:

1. Instale o Pi

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

2. Entre no projeto e suba o agente

cd seu-projeto
pi

3. Conecte um modelo

Dentro do Pi, para assinatura:

/login

Ou, para API key, antes de subir o Pi:

export ANTHROPIC_API_KEY=sk-ant-...

4. Crie o AGENTS.md com as regras do projeto

echo "# Instruções do projeto" > AGENTS.md

5. Reaproveite suas skills do Claude Code

Adicione às configurações em ~/.pi/agent/settings.json:

{
  "skills": ["~/.claude/skills"]
}

6. Trabalhe

Descreva a tarefa, use ctrl+l para trocar de modelo e alt+enter para corrigir o rumo enquanto o agente trabalha.

Dica: para rodar o servidor de desenvolvimento ou qualquer processo longo, abra dentro de uma sessão tmux. O Pi não tem bash em background por design, e o tmux dá logs e controle reais.

Conclusão

O Pi é uma aposta clara: menos é mais. Quatro ferramentas, um system prompt mínimo, e tudo o que sobra você liga por conta própria. Para quem se cansou de ver o coding agent mudar de comportamento a cada atualização, essa estabilidade e transparência valem muito.

O que você leva deste tutorial:

  • O Pi é um coding agent de terminal open-source (MIT), instalável em um comando
  • Conecta mais de 15 provedores, por assinatura (/login) ou API key, com troca de modelo no meio da sessão
  • Usa AGENTS.md para contexto e lê suas skills do Claude Code sem conversão
  • Sessões em árvore deixam você ramificar e voltar atrás sem perder contexto
  • Substitui o Claude Code muito bem quando você prioriza controle, observabilidade e flexibilidade de modelo, e menos bem quando você quer tudo pronto e configuração zero

A melhor forma de decidir é testar. A instalação é um comando, e ele convive com o Claude Code sem conflito: você pode rodar os dois no mesmo projeto por uns dias e ver qual fica.

Referências