Guia Definitivo: Pi — O Agente de Codificação Minimalista

Pi é um agente de codificação CLI que entrega apenas quatro ferramentas base — read, write, edit e bash — e deixa todo o resto por sua conta. Criado por Mario Zechner (o mesmo por trás do libGDX), Pi é o motor que impulsiona o OpenClaw e representa a antítese filosófica de agentes maximalistas como o Claude Code. Se você quer controle total sobre seu harness de codificação, este é o ponto de partida.

Overview

Pi se posiciona como um “terminal coding harness” — não um produto fechado, não um wrapper de chatbot, mas uma estrutura mínima que dá ao LLM quatro ferramentas para interagir com seu filesystem e shell, com você no controle de cada camada.

Posicionamento no Mercado

Enquanto o Claude Code chega com 20+ ferramentas embutidas, system prompt de ~10.000 tokens e opinião forte sobre como você deve trabalhar, Pi vai na direção oposta: system prompt de ~200 tokens, quatro ferramentas, e a filosofia de que tudo que você precisa além disso pode ser construído como extensão.

A analogia que circula na comunidade é precisa: Claude Code é Rails — opinionado, estruturado, com best practices embutidas. Pi é Arch Linux — o menor kernel possível com a maior liberdade.

Modelo de Execução

• Tipo: CLI (terminal-native)
• Linguagem: TypeScript (monorepo npm)
• Licença: MIT (open-source)
• Repositório: earendil-works/pi (anteriormente badlogic/pi-mono)
• Site oficial: pi.dev (anteriormente shittycodingagent.ai)
• Empresa: Earendil Inc.

Preço

Pi é 100% gratuito e open-source. O custo real é o da API do provedor de LLM que você escolher. Como Pi suporta 15+ provedores (incluindo Ollama para modelos locais), o custo pode ser literalmente zero se você rodar modelos locais, ou variar conforme seu uso de APIs como Anthropic, OpenAI, Google, etc.

Diferencial Principal

O diferencial do Pi não é o que ele faz — é o que ele não faz. Ele deliberadamente não inclui:

• MCP (Model Context Protocol)
• Sub-agentes
• Popups de permissão
• Plan mode
• To-dos embutidos
• Background bash

Cada uma dessas features pode ser construída como extensão TypeScript, instalada como package de terceiros, ou simplesmente pedida ao próprio Pi para criar na hora. Essa é a proposta: primitivas, não features.

Quatro Modos de Operação

1. Interactive — TUI completa para uso diário
2. Print/JSON — pi -p "query" para scripts e automação
3. RPC — Protocolo JSON via stdin/stdout para integrações não-Node
4. SDK — Embede Pi em suas aplicações (como faz o OpenClaw)

Tutorial

Instalação

Pré-requisitos: Node.js 20.0.0 ou superior.

node --version  # Deve retornar v20.0.0+

Escolha seu método de instalação:

# Via curl (recomendado)
curl -fsSL https://pi.dev/install.sh | sh

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

# Via pnpm
pnpm add -g @earendil-works/pi-coding-agent

# Via bun
bun add -g @earendil-works/pi-coding-agent

Verifique a instalação:

pi --version

[IMAGEM: Terminal mostrando instalação do Pi via npm com output de sucesso]

Configuração de Provedor

Pi precisa de pelo menos um provedor de LLM configurado. Configure via variáveis de ambiente:

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Google Gemini
export GEMINI_API_KEY=...

# xAI (Grok)
export XAI_API_KEY=...

# Groq
export GROQ_API_KEY=...

Para provedores com assinatura (Claude Pro, ChatGPT Plus, GitHub Copilot), use OAuth:

pi
/login  # Seleção interativa de provedor

Pi suporta 15+ provedores: Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi For Coding, MiniMax, OpenRouter, Ollama, e mais.

Primeiro Uso

Abra o Pi no diretório do seu projeto:

cd meu-projeto
pi

Você entra no modo interativo — uma TUI limpa onde pode conversar com o agente. Teste com algo simples:

> Analise a estrutura deste projeto e me dê um resumo

Pi vai usar suas quatro ferramentas (read para ler arquivos, bash para listar diretórios) e retornar uma análise. Sem popups de permissão, sem confirmações — ele simplesmente executa.

Para uso rápido sem entrar no modo interativo:

pi -p "Liste todos os TODOs neste projeto"

O flag -p (print mode) executa a query e retorna o resultado direto no stdout — perfeito para scripts e pipelines.

Uso Intermediário: Refatorando um Módulo

Vamos a um cenário real. Digamos que você tem um módulo de autenticação que precisa ser refatorado:

> Refatore src/auth/ para usar o padrão repository. 
> Extraia a lógica de banco para src/auth/repository.ts 
> e mantenha os handlers em src/auth/handlers.ts

Pi vai:

1. Ler os arquivos existentes (tool: read)
2. Criar o novo arquivo repository (tool: write)
3. Editar os handlers para usar o repository (tool: edit)
4. Rodar os testes se você pedir (tool: bash)

A beleza está na simplicidade: quatro ferramentas cobrem 95% dos casos de uso de codificação.

Troca de Modelo Mid-Session

Uma feature poderosa: você pode trocar de modelo no meio da sessão sem perder contexto.

Ctrl+L          # Abre seletor de modelo
/model claude   # Troca para Claude
Ctrl+P          # Cicla entre seus modelos favoritos

Isso é útil quando você quer usar um modelo mais barato para tarefas simples e escalar para um modelo mais capaz em momentos críticos.

Steering: Guiando o Agente em Tempo Real

Enquanto Pi trabalha, você pode enviar mensagens de steering:

• Enter — Envia mensagem de steering (entregue após a tool atual, interrompe tools restantes)
• Alt+Enter — Envia follow-up (espera o agente terminar)

Isso significa que você pode corrigir o rumo do agente sem cancelar todo o trabalho em andamento.

Sessões em Árvore

Pi armazena sessões como árvores. Use /tree para navegar a qualquer ponto anterior e continuar de lá. Todos os branches vivem em um único arquivo.

/tree           # Navega pela árvore de sessão
/export         # Exporta para HTML
/share          # Upload para GitHub Gist com URL compartilhável

Configuração Avançada: AGENTS.md e SYSTEM.md

Pi carrega instruções de projeto automaticamente:

• ~/.pi/agent/ — Configurações globais
• Diretórios pai — Instruções herdadas
• Diretório atual — Instruções do projeto

Crie um AGENTS.md na raiz do seu projeto:

# Instruções do Projeto

- Use TypeScript strict mode
- Testes com Vitest
- Commits seguem Conventional Commits
- Nunca modifique arquivos em /config sem perguntar

Para substituir ou estender o system prompt padrão, crie um SYSTEM.md:

Você é um engenheiro sênior especializado em sistemas distribuídos.
Sempre considere race conditions e idempotência.

Deep Dive

Arquitetura Interna

Pi vive em um monorepo TypeScript (earendil-works/pi) com npm workspaces e versionamento lockstep. A arquitetura é em três camadas:

Foundation (zero dependências internas):

• pi-ai — API unificada de LLM (streaming, tool calling, multi-provider)
• pi-tui — Biblioteca de UI terminal (renderização diferencial, componentes)

Core (depende apenas da foundation):

• pi-agent-core — Runtime de agente (state management, event-driven, tool execution loop)

Applications (topo da pilha):

• pi-coding-agent — O CLI que você usa
• pi-web-ui — Interface web
• pi-mom — Bot Slack

[IMAGEM: Diagrama da arquitetura em camadas do Pi mostrando Foundation → Core → Applications]

O Sistema de Extensões

Extensões são módulos TypeScript que rodam no mesmo processo do agente. Elas podem:

• Registrar ferramentas customizadas (chamáveis pelo LLM)
• Subscrever a eventos de lifecycle
• Adicionar comandos e atalhos de teclado
• Criar componentes de UI customizados
• Interceptar e filtrar mensagens
• Implementar compactação customizada de contexto

Uma extensão básica:

// extensions/minha-tool.ts
import { defineExtension } from "@mariozechner/pi-coding-agent";

export default defineExtension({
  name: "minha-tool",
  
  tools: [{
    name: "buscar_docs",
    description: "Busca na documentação interna do projeto",
    parameters: {
      query: { type: "string", description: "Termo de busca" }
    },
    async execute({ query }) {
      // Sua lógica aqui
      const results = await searchDocs(query);
      return { content: results };
    }
  }],

  events: {
    onSessionStart() {
      console.log("Sessão iniciada!");
    }
  }
});

O ponto crucial: você pode pedir ao próprio Pi para criar extensões. Diga “crie uma extensão que faz X”, ele gera o código, você dá /reload, e a extensão está ativa. Sem reiniciar, sem rebuild.

Skills: Contexto Progressivo

Skills no Pi são pacotes de capacidade com instruções e ferramentas, carregados sob demanda. A ideia é progressive disclosure — só carregar no contexto o que é relevante para a tarefa atual, sem estourar o prompt cache.

Uma skill é simplesmente um diretório com um SKILL.md:

# Web Search

Busca informações na web usando a API do Brave Search.

## Ferramentas

- `web_search(query)` — Busca na web e retorna resultados formatados

## Quando usar

- Quando precisar de informações atualizadas
- Quando o contexto do projeto não tem a resposta
- Para verificar documentação de bibliotecas

Prompt Templates: Prompts Reutilizáveis

Prompt templates são arquivos Markdown que você expande com /nome:

<!-- prompts/review.md -->
Revise o código que acabei de escrever:
1. Verifique bugs lógicos
2. Sugira melhorias de performance
3. Aponte violações de estilo do projeto
4. Liste edge cases não tratados

No Pi: /review expande o template completo.

Criando Packages Próprios

Packages são a unidade de distribuição do Pi. Eles empacotam extensões, skills, prompts e temas para compartilhar via npm ou git.

Estrutura mínima de um package:

meu-package/
├── package.json
├── extensions/
│   └── deploy.ts
├── skills/
│   └── kubernetes/
│       └── SKILL.md
└── prompts/
    └── deploy-checklist.md

package.json:

{
  "name": "@meuorg/pi-devops",
  "version": "1.0.0",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"]
  }
}

Publicar:

# Testar localmente
pi -e ./meu-package

# Publicar no npm
npm publish

# Ou via git
git tag v1.0.0
git push origin v1.0.0

Instalar:

# Do npm
pi install npm:@meuorg/pi-devops

# Do git
pi install git:github.com/meuorg/pi-devops

# Projeto-local (compartilhado com o time)
pi install -l npm:@meuorg/pi-devops

Gerenciando Packages

pi list              # Lista packages instalados
pi update            # Atualiza todos (exceto pinados)
pi remove npm:@foo   # Remove package
pi config            # Habilita/desabilita recursos de packages

O Que a Comunidade Já Construiu

O ecossistema de packages do Pi já inclui 50+ extensões de exemplo:

• Sub-agentes — Spawn de instâncias Pi via tmux
• Plan mode — Planejamento antes da execução
• Permission gates — Confirmação antes de ações destrutivas
• Path protection — Proteção de diretórios sensíveis
• SSH execution — Execução remota
• Sandboxing — Isolamento de ambiente
• MCP adapter — Integração com MCP servers
• Interactive shell — Controle de CLIs interativas com PTY emulation
• DOOM — Sim, Pi roda DOOM (porque por que não?)

Navegue packages disponíveis em pi.dev/packages.

Compactação de Contexto

Quando a janela de contexto se aproxima do limite, Pi auto-sumariza mensagens mais antigas. Mas aqui está o diferencial: a compactação é totalmente customizável via extensões. Você pode implementar:

• Compactação baseada em tópicos
• Sumarização code-aware (preserva código, compacta discussão)
• Uso de modelos diferentes para sumarização (modelo barato para compactar, modelo caro para gerar)

Contexto Dinâmico

Extensões podem injetar mensagens antes de cada turno, filtrar o histórico, implementar RAG, ou construir memória de longo prazo. Isso é context engineering de verdade — você controla exatamente o que entra na janela de contexto e como é gerenciado.

Avaliação: Spider Chart

Notas de 1 a 10 baseadas em benchmarks públicos + avaliação prática.

Média geral: 7.0/10

[IMAGEM: Spider chart com 8 eixos mostrando as notas do Pi]

Metodologia: Código baseia-se em SWE-bench Verified + Aider Polyglot (quando disponível para o provider). Autonomia em Terminal-Bench 2.0 + avaliação prática. Demais eixos são avaliação prática comparativa. Escala: 1-4 (fraco), 5-6 (adequado), 7-8 (bom), 9-10 (excelente/líder).

Prós e Contras

Prós

• Controle total — Você decide exatamente o que o agente pode e não pode fazer. Sem caixa preta, sem comportamentos surpresa. O system prompt tem ~200 tokens e é legível em 30 segundos.

• Agnóstico de modelo — 15+ provedores suportados, troca mid-session com Ctrl+L. Use Claude para raciocínio complexo, GPT-4o para velocidade, Ollama para privacidade — tudo na mesma sessão.

• Extensibilidade radical — Tudo que outros agentes embutem, você constrói (ou instala). E o próprio Pi pode criar extensões para si mesmo em tempo real.

• Leve e rápido — Sem overhead de features que você não usa. O core é mínimo, o startup é instantâneo.

• Open-source MIT — Sem vendor lock-in, sem telemetria, sem backend SaaS. Roda 100% local.

• Ecossistema de packages — Compartilhe e instale customizações via npm ou git. O modelo “npm para agentes” funciona.

• Self-modifying — Pi pode modificar a si mesmo. Peça uma feature, ele implementa, dê /reload, e está funcionando. Sem fork, sem PR.

• SDK embeddable — Use Pi como biblioteca em seus próprios projetos (como faz o OpenClaw com 145K+ stars).

Contras

• Curva de aprendizado — Pi não faz nada por você out-of-the-box além do básico. Se você quer sub-agentes, plan mode, ou MCP, precisa configurar. Para quem vem do Claude Code, a sensação inicial é de “falta coisa”.

• Sem guardrails padrão — Não há popups de permissão por padrão. Pi executa o que o modelo decide. Você precisa construir seus próprios gates de segurança (ou instalar um package que faça isso).

• Documentação em evolução — Como projeto relativamente novo e em rápida evolução, a documentação nem sempre acompanha as mudanças. O Discord da comunidade é frequentemente mais atualizado.

• Ecossistema ainda jovem — Comparado ao ecossistema de MCP servers ou extensões do VS Code, o catálogo de Pi packages ainda é pequeno (embora crescendo rápido).

• Requer conforto com TypeScript — Para criar extensões customizadas, você precisa saber TypeScript. Se você só quer usar o agente sem customizar, isso não é problema — mas perde o diferencial principal.

• Sem interface gráfica nativa — É terminal-only. Se você prefere uma IDE visual com painéis e botões, Pi não é para você (embora o pi-web-ui exista como biblioteca).

Veredicto

Pi é ideal para:

• Desenvolvedores que querem controle total sobre seu agente
• Quem já usa terminal como ambiente principal de trabalho
• Times que precisam de customizações específicas (compliance, segurança, workflows internos)
• Quem quer usar múltiplos provedores de LLM sem lock-in
• Builders que querem criar produtos em cima de um agente (via SDK)

Pi NÃO é ideal para:

• Quem quer produtividade imediata sem configuração
• Desenvolvedores que preferem IDEs visuais
• Iniciantes que ainda estão aprendendo a usar agentes de codificação
• Quem não quer pensar em qual modelo usar (Claude Code escolhe por você)

A melhor analogia continua sendo: se Claude Code é o iPhone (funciona perfeitamente out-of-the-box, mas nos termos da Apple), Pi é o Android desbloqueado (requer setup, mas você faz o que quiser).

Começando Hoje

Se Pi despertou seu interesse, o caminho mais rápido é:

curl -fsSL https://pi.dev/install.sh | sh
export ANTHROPIC_API_KEY=sua-chave-aqui
cd seu-projeto
pi

Passe 30 minutos usando as quatro ferramentas base. Depois, peça ao Pi: “crie uma extensão que [algo que você precisa]”. Quando você ver o agente modificando a si mesmo em tempo real, vai entender por que a comunidade está tão entusiasmada.

Para quem quer ir além na especialização de agentes com skills customizadas, o skilldev.pro oferece um catálogo de skills prontas que funcionam com Pi e outros agentes — vale explorar para acelerar seu setup inicial.

Versão do Pi testada: 0.55.x (maio/2026). Pi está em desenvolvimento ativo — features e APIs podem mudar entre versões.