Revisão do Agente de Codificação Pi: CLI de IA Minimalista e Hackeável

O Pi Coding Agent é um harness de codificação minimalista e de código aberto para terminal que é fornecido com quatro ferramentas padrão e deixa a maior parte do comportamento para extensões, habilidades e o seu próprio fluxo de trabalho.

A maioria dos agentes de codificação com IA está se tornando em produtos maiores. Eles adicionam modos de planejamento, subagentes, camadas de permissão, integrações com IDEs, trabalhadores em segundo plano e orquestração cada vez mais elaborada em torno do modelo. O Pi adota quase a abordagem oposta: o agente padrão começa com quatro ferramentas básicas — read, write, edit e bash — enquanto a maior parte do comportamento interessante é deliberadamente deixada para extensões, habilidades, pacotes e o seu próprio fluxo de trabalho.

Esta revisão está alinhada com o Pi v0.84.2, lançado em 14 de agosto de 2026. Mario Zechner criou o projeto; ele se moveu para a Earendil Works em maio de 2026, o que é por isso que os pacotes atuais usam o escopo @earendil-works em vez dos nomes mais antigos @mariozechner. O Pi tem mudado rapidamente, portanto, as APIs de configuração e extensão merecem uma verificação de versão antes que você as padronize em toda uma equipe.

A ressalva é igualmente importante: o Pi lhe dá consideravelmente mais controle do que muitos agentes de codificação e, correspondentemente, mais responsabilidade. Ele não fornece um sandbox de segurança integrado nem o tipo de sistema de permissão que os desenvolvedores podem esperar após usar o Claude Code ou ferramentas similares. Abaixo, cubro o início rápido, a arquitetura, o suporte a modelos, as extensões, o modelo de sessão, as implicações de segurança e onde acredito que o Pi se encaixa entre as ferramentas modernas de codificação com IA.

O que é o Pi Coding Agent?

O Pi é melhor entendido como um harness de agente do que como um ambiente de codificação acabado e opinativo. Essa distinção é importante: um modelo de codificação responde a prompts, enquanto um harness de agente decide qual contexto esse modelo vê, quais ferramentas ele pode chamar, como os resultados das ferramentas retornam a ele, como as sessões persistem e o que acontece entre as turnos. O Pi torna quase todas essas camadas acessíveis, o que é por isso que ele se situa na extremidade de construção de kit do campo de ferramentas de desenvolvimento com IA em vez de entre os produtos de codificação com tudo incluído.

O motivo mais forte para usar o Pi não é que ele tenha mais recursos do que os agentes de codificação concorrentes — ele não tem. O motivo é que o Pi expõe mais do próprio agente. Isso o torna particularmente atraente para desenvolvedores seniores, engenheiros de plataforma, equipes de ferramentas de IA e qualquer pessoa que tenha alcançado o ponto em que as limitações do seu agente de codificação são causadas pelo harness em vez do modelo subjacente. O Pi é menos convincente para alguém que deseja instalar um agente, aprovar alguns padrões seguros e nunca mais pensar na sua arquitetura novamente: o seu minimalismo é produtivo apenas se você valoriza o controle que esse minimalismo cria.

O que o Pi realmente lhe dá

O conjunto de ferramentas padrão voltado para o modelo é intencionalmente pequeno:

read
write
edit
bash

Ferramentas adicionais somente de leitura, incluindo grep, find e ls, estão disponíveis, e as versões recentes do Pi permitem que a seleção inicial de ferramentas integradas seja configurada.

O padrão parece escasso, e esse é o ponto. Cada ferramenta adicional aumenta o número de decisões que o modelo tem que tomar, expande o prompt do sistema e cria outra superfície comportamental que pode precisar de depuração. O Pi, em vez disso, começa de um conjunto primitivo capaz e permite que você adicione ferramentas especializadas quando o seu fluxo de trabalho realmente as precisar.

A filosofia vai além das ferramentas. O Pi deliberadamente não torna subagentes integrados ou um modo de plano obrigatório central para o produto; esses comportamentos podem ser implementados através de extensões ou pacotes instalados. Isso torna o Pi menos conveniente fora da caixa, mas dá aos desenvolvedores mais controle sobre como esses mecanismos são implementados. Se você está acostumado com os subagentes integrados do Claude Code, o guia de subagentes do Claude Code é uma referência útil para o que você estaria reimplementando. Acho essa abordagem um pouco refrescante: o Pi não finge que há uma forma correta de operar um agente de codificação com IA.

Como instalar o Pi Coding Agent e iniciar uma sessão

Instale o pacote atual do escopo @earendil-works. Tutoriais mais antigos podem ainda mostrar pacotes @mariozechner de antes da mudança de maio de 2026; esses nomes estão desatualizados para novas instalações.

O nome também conflita com oh-my-pi, um fork da comunidade do harness Oh My Opencode. Esse projeto não tem relação com este agente de codificação; a revisão do Oh My Opencode explica o fork caso você tenha chegado ao Pi errado.

Instalar e autenticar

1. Instale o Pi globalmente com npm:

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

   --ignore-scripts desativa scripts de ciclo de vida de dependências durante a instalação. O Pi não precisa desses scripts para uma instalação npm normal, e ignorá-los reduz um risco comum de cadeia de suprimentos.

2. Verifique a instalação:

   pi --version
   

3. Entre em um projeto e inicie-o:

   cd /path/to/project
   pi
   

O Pi espera um ambiente com capacidade bash. No Windows, use WSL ou Git Bash em vez de cmd.exe.

O Pi suporta autenticação por assinatura interativa, bem como provedores baseados em chave de API. Dentro do Pi, a rota mais simples é:

/login

Após a autenticação, selecione um modelo com:

/model

Você também pode fornecer credenciais do provedor através de variáveis de ambiente. Por exemplo:

export ANTHROPIC_API_KEY="your-api-key"
pi

O Pi atualmente suporta uma ampla coleção de provedores de modelos, incluindo OpenAI, Anthropic, Google, Azure OpenAI, Amazon Bedrock, NVIDIA NIM, DeepSeek, Mistral, Groq, Cerebras, Cloudflare, xAI, OpenRouter e vários outros. Um roteador llama.cpp também é suportado para modelos servidos localmente: o início rápido do llama.cpp cobre o serviço de modelos GGUF com uma API compatível com OpenAI, e o guia de hospedagem de LLM mapeia os tempos de execução locais, auto-hospedados e em nuvem circundantes se você quiser comparar esse caminho com Ollama, vLLM ou um provedor hospedado. Provedores personalizados que falam uma API suportada podem ser adicionados através de ~/.pi/agent/models.json, e APIs ou fluxos OAuth personalizados podem ser conectados com extensões.

Este design multi-provedor é uma das vantagens práticas do Pi. O modelo e o harness de codificação são variáveis separadas: com o Pi, você pode mudar o modelo mantendo essencialmente o mesmo conjunto de ferramentas e ambiente de sessão, o que torna as comparações de modelos consideravelmente mais significativas do que comparar produtos de codificação completamente diferentes.

Começar com uma primeira sessão controlada

Eu não faria o seu primeiro prompt do Pi ser “refatore minha aplicação”. Comece pedindo para inspecionar em vez de modificar:

pi --tools read,grep,find,ls -p "Inspect this repository. Explain its architecture, identify the main entry points, and list the commands you would run before making a change. Do not modify files."

Quando eu executei esse prompt somente de leitura em um repositório existente, o resultado útil não foi um ensaio inteligente sobre arquitetura. Foi se o modelo nomeou pontos de entrada reais e os comandos que eu realmente executaria antes de pedir acesso de escrita. Isso lhe dá uma visão de como o modelo selecionado navega pela sua árvore sem imediatamente lhe conceder um caminho de escrita através do conjunto de ferramentas normal.

Para trabalho interativo, eu também criaria primeiro um ramo Git descartável:

git switch -c ai/pi-evaluation
pi

O Pi pode modificar arquivos no diretório de trabalho e pode executar comandos de shell através de bash, portanto, o Git permanece uma das camadas de rollback práticas mais simples ao avaliá-lo. Se você quiser uma sessão de teste que não persista, pi --no-session executa em modo efêmero.

As instruções do projeto pertencem ao AGENTS.md. Um arquivo inicial útil poderia se parecer com isto:

# Project Instructions

- Read the existing implementation before modifying files.
- Keep changes narrowly scoped to the requested task.
- Run `npm test` after code changes.
- Run `npm run lint` before declaring the task complete.
- Do not modify database migrations unless explicitly requested.
- Do not access production infrastructure.
- Explain any destructive command before running it.

O Pi também entende CLAUDE.md ao percorrer diretórios de projeto, e AGENTS.override.md pode sobrescrever as instruções normais do projeto para um diretório.

Então, dê a ele uma tarefa concreta:

Read the authentication module and its tests.

Find one maintainability problem that can be fixed without changing public behaviour. Explain the proposed change first, then implement it and run the relevant tests.

Esta é uma melhor avaliação de agente do que pedir para gerar uma nova aplicação de brinquedo. Código existente força o agente a descobrir restrições, preservar comportamento, escolher arquivos relevantes e verificar seu trabalho.

Por que o Pi Coding Agent é um harness editável

A ideia arquitetônica mais importante do Pi é que o próprio agente de codificação deve permanecer editável. O sistema de extensões usa módulos TypeScript que podem registrar ferramentas, assinar eventos de ciclo de vida, interceptar chamadas de ferramentas, injetar ou transformar contexto, adicionar comandos e modificar a interface do terminal. Extensões locais do projeto também podem ser recarregadas com /reload, o que torna a experimentação com o harness surpreendentemente imediata.

Em forma simplificada, o Pi se parece com isto:

O diagrama é simples porque o Pi está tentando manter o plano de controle simples. Isso lhe dá uma opção incomum: quando o agente carece de uma capacidade, você não necessariamente tem que esperar os mantenedores do Pi adicionarem — você pode adicionar o comportamento você mesmo. Uma extensão pode criar uma nova ferramenta chamável pelo modelo, inspecionar uma chamada bash proposta e bloquear comandos que correspondam à sua própria política, inserir informações dinâmicas do projeto antes de um turno, alterar o comportamento de compactação ou expor um comando personalizado dentro da interface do terminal. Essa é uma superfície de extensão muito mais profunda do que mudar um prompt do sistema.

A integração MCP não é tratada como uma parte obrigatória integrada do núcleo minimalista do Pi. Ela pode ser adicionada através do mesmo modelo de extensibilidade, o que é consistente com o design mais amplo: integrações especializadas vivem acima do pequeno harness padrão em vez de expandi-lo permanentemente.

O mesmo harness também é reutilizável fora do terminal interativo. O Pi fornece um SDK para incorporar a sessão do agente em aplicações Node.js, e um modo RPC (pi --mode rpc) que fala JSON sobre stdin/stdout para hosts não-Node, IDEs e interfaces personalizadas.

A ideia das quatro ferramentas é mais séria do que parece

Inicialmente, eu pensava nas ferramentas de agentes de codificação em dois grupos. O primeiro contém primitivas: ler um arquivo, modificar um arquivo e executar um comando. O segundo contém conveniências: busca de repositório, executadores de teste, rastreadores de problemas, ferramentas de navegador, ferramentas de implantação, auxiliares de banco de dados, inteligência de código e planejadores especializados. O Pi mantém a camada primitiva pequena e permite que a camada de conveniência permaneça opcional.

Há uma vantagem arquitetônica para isso. Uma equipe trabalhando em infraestrutura Kubernetes pode construir um Pi muito diferente de uma equipe mantendo um monorepo TypeScript, sem que ambas as equipes carreguem as ferramentas da outra no mesmo agente padrão. É aqui que o Pi deixa de parecer uma alternativa simplificada do Claude Code e começa a parecer um framework para construir o seu próprio agente de codificação.

O preço é manutenção. Uma vez que você dependa de extensões personalizadas, o seu comportamento se torna parte da sua plataforma de desenvolvedor: você precisa revisá-los, versioná-los e ocasionalmente atualizá-los conforme o Pi evolui. Essa é a taxa oculta do Pi — você ganha a propriedade do agente, e a propriedade vem com manutenção.

Habilidades e pacotes mantêm a personalização modular

Nem todo comportamento personalizado precisa se tornar uma extensão. O Pi suporta habilidades que empacotam instruções, scripts e material de referência em torno de uma capacidade. As habilidades usam divulgação progressiva: o Pi pode anunciar a habilidade disponível para o modelo enquanto carrega as instruções completas apenas quando a capacidade é necessária. Isso é útil para fluxos de trabalho como revisões de implantação, migrações de banco de dados, preparação de lançamento ou revisão de código específica de framework; em vez de injetar permanentemente páginas de instruções em cada conversa, o agente pode carregar orientações especializadas sob demanda. Se você já constrói Claude Skills, a mecânica será familiar — veja Claude Skills e SKILL.md para desenvolvedores para o layout do SKILL.md e o ajuste de gatilhos.

Os Pacotes do Pi vão mais longe ao agrupar extensões, habilidades, modelos de prompt e temas. Pacotes podem ser instalados do npm ou repositórios Git e podem ser fixados em versões específicas:

pi install npm:@foo/pi-tools@1.2.3
pi list

O modelo de pacote é poderoso, mas trate pacotes mais como ferramentas de desenvolvedor executáveis do que como coleções de prompts inofensivas. Uma extensão do Pi pode executar código com as permissões do processo do Pi, e uma habilidade também pode instruir o modelo a executar código, portanto, instalar um pacote desconhecido merece essencialmente a mesma suspeita que instalar uma dependência de desenvolvimento desconhecida.

Árvores de sessão no Pi Coding Agent

Muitos assistentes de codificação tratam uma conversa como um transcrito majoritariamente linear. O Pi armazena sessões como uma árvore, o que significa que você pode retornar a um ponto anterior, tentar outra abordagem e reter ambos os caminhos dentro da sessão em vez de destruir um histórico ou criar uma pilha de chats não relacionados.

Os principais comandos são diretos:

/resume
/tree
/fork
/clone
/compact

/tree permite que você navegue dentro da árvore de sessão atual. /fork cria uma nova sessão a partir de uma mensagem de usuário anterior, enquanto /clone duplica o ramo atualmente ativo em uma sessão separada. Da linha de comando, pi -c continua a sessão mais recente e pi -r navega pelas passadas.

A distinção ficou óbvia pela primeira vez que eu usei o Pi em uma passada de depuração em vez de um prompt de campo verde. Eu deixei que ele seguisse uma hipótese de camada de cache para um teste de integração falho, então bifurquei a partir da mensagem onde essa teoria havia sido escolhida e comecei um segundo ramo no isolamento de transação. A investigação falhou permaneceu disponível para contraste em vez de contaminar o novo caminho ou forçar um novo chat, o que é uma representação útil de como a depuração realmente funciona: múltiplas explicações plausíveis frequentemente existem ao mesmo tempo.

O Pi persiste sessões como JSONL e pode compactar automaticamente o contexto mais antigo conforme as conversas se aproximam dos limites do modelo; ramos também podem ser resumidos quando você se move entre eles. Eu classificaria isso acima de vários recursos mais visíveis de agentes de codificação: uma boa gestão de contexto geralmente importa mais do que outro botão na interface.

Engenharia de contexto é uma capacidade de primeira classe

O Pi também torna possível personalizar o que chega ao modelo. Extensões podem injetar informações antes dos turnos, alterar o histórico e participar da compactação. O sistema de compactação padrão resume o material mais antigo enquanto retém a conversa recente, mas o mecanismo pode ser substituído ou personalizado.

Para equipes avançadas, isso abre possibilidades interessantes. Um monorepo grande poderia injetar informações de propriedade apenas para os arquivos que o agente está tocando atualmente. Um projeto de backend poderia trazer metadados de esquema quando arquivos de banco de dados entram no contexto. Um agente de migração de longa duração poderia manter estado estruturado fora da conversa em vez de pedir repetidamente ao modelo para redescobri-lo. É isso que eu considero a força de longo prazo real do Pi: a qualidade dos agentes de codificação é cada vez mais limitada pela engenharia de contexto, design de ferramentas e orquestração em vez da inteligência bruta do modelo, e o Pi dá aos desenvolvedores acesso incomumente direto a essas camadas.

Segurança do Pi Coding Agent: sem sandbox integrado

O ponto negativo mais importante nesta revisão é simples: o Pi não fornece um sandbox de segurança integrado. Por padrão, o Pi executa com as permissões do usuário e processo que o iniciou. Suas ferramentas podem ler e modificar arquivos acessíveis e executar comandos de shell dentro desse contexto de sistema operacional.

O Pi tem confiança de projeto, mas a confiança de projeto não é um sandbox. A confiança de projeto controla se as configurações locais do projeto do Pi, extensões, habilidades, prompts e recursos similares são carregados. Uma vez que você está trabalhando em um projeto, ela não cria uma fronteira de sistema de arquivos, rede, processo ou credencial em torno das chamadas de ferramentas direcionadas pelo modelo. Eu realmente aprecio que a documentação do Pi seja explícita sobre essa distinção: um pseudo-sandbox fraco pode ser mais perigoso do que nenhum sandbox porque os usuários podem confiar em uma fronteira que não realmente existe. O Pi, em vez disso, espera que o isolamento significativo venha de contêineres, máquinas virtuais, micro-VMs ou outro tempo de execução controlado por política.

Para projetos pessoais descartáveis, você pode decidir que Git e permissões normais do sistema operacional são suficientes. Para repositórios não confiáveis, agentes não supervisionados, estações de trabalho contendo credenciais de produção ou agentes processando conteúdo fornecido externamente, eu usaria isolamento mais forte. A documentação do Pi descreve três padrões:

A fronteira importante não é apenas o diretório de origem. Um agente que pode executar comandos de shell pode potencialmente interagir com configuração SSH, credenciais de nuvem, registros de pacotes, serviços locais, estado do navegador e qualquer outra coisa disponível para o processo. Uma configuração de qualidade de produção, portanto, precisa pensar sobre montagens de sistema de arquivos, variáveis de ambiente, acesso à rede e credenciais juntos. Meu padrão de avaliação preferido é:

Montar o repositório real para leitura/escrita em um contêiner ainda permite que o agente modifique esse repositório; contêineres ajudam apenas na extensão em que suas montagens, credenciais, capacidades e acesso à rede são realmente restritos. O Gondolin tem uma ressalva relacionada: ferramentas de extensão personalizadas ainda executam no host a menos que também deleguem para a VM.

Há outra superfície de segurança que vale a pena lembrar: extensões e pacotes. Uma extensão de terceiros é código executando dentro do ambiente do agente. Revise-a antes da instalação, fixe dependências importantes e evite tratar uma galeria pública de pacotes como uma revisão de segurança implícita.

Duas verificações práticas antes de você executar o Pi em uma máquina sobre a qual se importa:

# Confirm the version you actually have
pi --version

# Disable startup network operations (update checks and install telemetry)
export PI_OFFLINE=1
pi

PI_OFFLINE=1 desativa todas as operações de rede de inicialização, incluindo verificações de atualização, verificações de atualização de pacotes e telemetria de instalação/atualização. Se você quiser uma divisão mais fina, PI_SKIP_VERSION_CHECK=1 desliga apenas a verificação de versão, e PI_TELEMETRY=0 desativa a telemetria de instalação/atualização mantendo as verificações de atualização habilitadas.

Este modelo de segurança é o principal motivo pelo qual eu hesitaria antes de dar o Pi a uma grande organização de engenharia como padrão não gerenciado. O Pi fornece as peças para construir um ambiente forte, mas intencionalmente deixa muito desse ambiente para você.

Pi Coding Agent vs Claude Code e OpenCode

O Pi faz mais sentido quando comparado por filosofia em vez de por contagem de recursos. Entre agentes de terminal, OpenHands é o parente mais próximo: ele também executa a partir da CLI, mas fornece sandbox e um fluxo de trabalho integrado maior em vez de pedir para você montar um. Claude Code tem permissões, hooks e subagentes integrados cada vez mais sofisticados. OpenCode expõe regras configuráveis de permitir, perguntar e negar, além de conceitos integrados de agente ou subagente. O Pi começa mais baixo na pilha.

É por isso que chamar o Pi de “clon do Claude Code” perde a parte interessante. Se você está satisfeito com o fluxo de trabalho do Claude Code, o Pi não o melhora automaticamente: o Claude Code lhe dá mais segurança e comportamento de orquestração de agente sem exigir que você monte essas peças você mesmo. O Pi se torna interessante quando você quer mudar as premissas sob o produto. Talvez você queira o mesmo harness através de Anthropic, OpenAI e modelos locais. Talvez a sua organização tenha o seu próprio sandbox. Talvez você precise de uma ferramenta que injete metadados de arquitetura interna antes de cada turno. Talvez você queira que a compactação produza estado de engenharia estruturado em vez de um resumo de conversa genérico. Esse é o território do Pi.

O OpenCode é argumentavelmente mais próximo filosoficamente porque também oferece configuração substancial. Mesmo lá, o Pi se sente mais como um kit para construir o próprio harness, enquanto o OpenCode expõe mais conceitos de agente e permissão prontos.

Não há um vencedor universal aqui. Para muitos desenvolvedores, os padrões opinativos do Claude Code são uma vantagem. Para outros, o OpenCode pode oferecer um meio-termo melhor. O Pi é a opção que eu investigaria quando a frase “eu gostaria que o meu agente de codificação funcionasse de forma diferente” se tornou mais importante do que “eu gostaria que o meu agente de codificação tivesse outro recurso”.

Você deve usar o Pi Coding Agent?

O Pi Coding Agent é um dos agentes de codificação mais tecnicamente interessantes porque ele se recusa a esconder o harness. A implementação padrão é deliberadamente pequena, mas a API de extensões, habilidades, pacotes, camada de provedor, SDK, modo RPC e árvore de sessão lhe dão uma superfície efetiva muito maior do que as suas quatro ferramentas padrão sugerem.

Eu recomendaria o Pi mais fortemente para desenvolvedores experientes que gostam de construir as suas próprias ferramentas. É particularmente convincente para trabalho de plataforma de IA, pesquisa experimental de agentes de codificação, fluxos de trabalho de engenharia especializados e equipes que já têm infraestrutura de execução segura. Também é útil para desenvolvedores que querem comparar modelos sem mudar todo o seu ambiente de codificação cada vez. Eu seria mais cauteloso para iniciantes e para organizações esperando controles de política estilo empresa imediatamente após a instalação.

O sandbox ausente muda como o Pi deve ser implantado, especialmente quando um agente é permitido operar não supervisionado ou pode encontrar instruções não confiáveis. Trate o Pi como um poderoso processo local de desenvolvedor em vez de uma fronteira de segurança: para repositórios não confiáveis, operação não supervisionada ou ambientes contendo credenciais valiosas, use um sandbox de sistema operacional, contêiner, VM ou baseado em política e exponha apenas os recursos necessários para a tarefa.

A minha avaliação geral é 8.4/10. Esse é um veredito editorial em vez da média da tabela acima, e poderia facilmente se tornar mais alto para o usuário certo. A maior fraqueza e a maior força do Pi são a mesma coisa: ele não termina o agente para você.

Você deve mudar para o Claude Code? Não automaticamente. Use o Claude Code quando as suas permissões, subagentes, hooks e fluxo de trabalho integrados se encaixam na forma como você já trabalha. Avalie o Pi quando você quiser propriedade mais ampla do harness, seleção de provedor, construção de contexto e arquitetura de ferramentas. Para desenvolvedores avançados, eu nem assumiria que a escolha tem que ser exclusiva: o Claude Code pode permanecer o carro diário polido enquanto o Pi se torna o laboratório de agente programável. Após personalização suficiente, esse laboratório pode se tornar a ferramenta que você realmente prefere.

Licenciamento e custo

O próprio Pi é de código aberto e lançado sob a licença MIT. Isso não torna a inferência do modelo gratuita: o seu custo real depende do provedor do modelo, uso da API, autenticação por assinatura suportada, computação local e qualquer infraestrutura de sandbox que você escolha executar.

Referências

• Repositório do Pi Coding Agent: https://github.com/earendil-works/pi
• Site e instalador do Pi: https://pi.dev
• Pacote npm: https://www.npmjs.com/package/@earendil-works/pi-coding-agent
• Micro-VM Gondolin: https://github.com/earendil-works/gondolin
• NVIDIA OpenShell: https://docs.nvidia.com/openshell/about/overview
• Licença: MIT