# Guia Definitivo: Pi — O Agente Minimalista

> Pi é o agente de codificação CLI com apenas 4 tools que você customiza do zero. Instalação, packages, extensões e workflow completo.

Source: https://agentify.ia.br/blog/pi/

# 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

- **Interactive** — TUI completa para uso diário

- **Print/JSON** — `pi -p "query"` para scripts e automação

- **RPC** — Protocolo JSON via stdin/stdout para integrações não-Node

- **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:

- Ler os arquivos existentes (tool: `read`)

- Criar o novo arquivo repository (tool: `write`)

- Editar os handlers para usar o repository (tool: `edit`)

- 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](https://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.

 Eixo Nota Justificativa Código (qualidade) 7/10 Depende do provider (15+); sem benchmark próprio, mas competitivo no TerminalBench (2º lugar geral) Contexto (compreensão) 6/10 Apenas 4 tools (read/write/edit/bash); sem indexação de codebase nativa, contexto mínimo por design Autonomia 7/10 Execução autônoma com 4 tools, surpreendentemente capaz; 2º no TerminalBench atrás apenas do Terminus Velocidade 9/10 Minimalista = rápido; sem overhead de features, TypeScript leve, startup instantâneo Custo-benefício 9/10 Open-source MIT gratuito, custo apenas de API; 45K+ stars, adquirido pela Earendil Inc. Especialização (skills) 7/10 Packages como sistema de skills (2.300+ no catálogo), extensível via TypeScript Multi-agente 4/10 Sem multi-agente nativo, single-thread por design; sub-agentes apenas via package de terceiros Ecossistema 7/10 2.300+ packages npm/git, comunidade ativa (45K stars), mas jovem comparado a MCP/VS Code

**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](https://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.*

-->