pi agent toolkit: cinco pacotes, receita de SDK, tabela de vereditos e checklist

TL;DR

• O pi é um monorepo com licença MIT que entrega um harness de agente de código em cinco pacotes separados: uma camada de API de modelos, o loop do agente, uma biblioteca de interface de terminal, o agente de código em si e um pacote de telemetria. Você pode pegar uma peça só ou as cinco.
• O CLI é um agente de código completo desde o primeiro dia: quatro ferramentas por padrão, histórico de sessões em árvore com fork e resume, contador de custo ao vivo, e ele lê o AGENTS.md ou CLAUDE.md que já está no seu repo.
• O valor de verdade está no SDK: createAgentSession mais um runtime de modelo mais um gerenciador de sessões dão um agente funcional em cerca de dez linhas de TypeScript, e defineTool adiciona uma ferramenta customizada tipada sem processo separado nem protocolo.
• O preço dessa transparência é trabalho: sem pedidos de permissão embutidos, o isolamento fica por sua conta, uma versão pre-1.0 (v0.84) e cerca de cem issues abertas.
• Mantenha seu harness do dia a dia e use o pi como bancada de testes que mostra o que esse harness esconde. Construa produtos em cima dele só se aceitar cuidar das proteções.

O que as fontes dizem

O pi é um monorepo: um único repositório que hospeda cinco pacotes publicados separadamente, cada um cobrindo uma camada do harness s2. O pi-ai é a API unificada para os provedores de modelos (OpenAI, Anthropic, Google e outros atrás de uma só interface), cuidando do streaming de respostas, dos blocos de raciocínio com seus níveis de thinking e da descoberta dinâmica dos modelos que cada provedor oferece s2. O pi-agent-core é o loop do agente em si: o estado da conversa e o ciclo que envia uma mensagem, lê as chamadas de ferramenta, executa e devolve os resultados s2. O pi-tui é uma biblioteca de renderização de terminal com renderização diferencial, então só redesenha o que mudou na tela s2. O pi-coding-agent junta essas peças no CLI que você instala, e o pi-telemetry permite ligar suas próprias métricas de uso sem depender de um fornecedor s3.

Os números de adoção sustentam o desenho: 92 123 estrelas, 11 400 forks e mais de 5 700 commits, tudo sob licença MIT, que permite usar, modificar e redistribuir, inclusive dentro de um produto comercial s1. O ritmo de lançamentos se manteve no verão: três versões nas duas primeiras semanas de agosto, com a v0.84.2 publicada no dia 14 s4.

A instalação é um comando só, npm install -g --ignore-scripts @earendil-works/pi-coding-agent, e a flag ignore-scripts importa: ela impede que as dependências rodem seus scripts de instalação, uma das superfícies de ataque mais usadas no npm s3. Depois de conectar a um provedor com o comando login, a barra inferior mostra a pasta atual, a sessão, os tokens consumidos e o custo em tempo real, então cada requisição é precificada na hora em que sai, e não no fim do mês s3.

As sessões são o diferencial. Cada conversa é salva como JSONL na sua pasta pessoal, organizada por projeto, e o histórico é uma árvore, não uma linha: fork volta a qualquer ponto e abre outra ramificação, tree navega entre as ramificações, e resume reabre qualquer sessão antiga, semanas depois, porque tudo fica guardado localmente s3. O modelo recebe só quatro ferramentas por padrão: read, write, edit e bash, bem poucas perto dos agentes do mercado, e de propósito s3. A configuração segue a mesma lógica: um settings.json global na sua pasta pessoal, outro por projeto que o sobrescreve, e um sistema de confiança que pergunta antes de aplicar as configurações locais de uma pasta aberta pela primeira vez. O CLI também carrega o AGENTS.md ou CLAUDE.md do seu projeto como contexto, então as instruções que você já tem funcionam sem reescrever nada s3.

No lado do SDK, createAgentSession recebe um ModelRuntime e um SessionManager e devolve um agente funcional. O SessionManager é a escolha de persistência: em memória para um script descartável, em disco para reencontrar suas conversas entre execuções, e as sessões criadas pelo SDK compartilham a estrutura das sessões do próprio CLI s8. A lista de opções do createAgentSession também deixa você escolher o conjunto exato de ferramentas expostas, e até o prompt de sistema inteiro por meio de um ResourceLoader quando quer começar do zero s8. As ferramentas customizadas passam pelo defineTool: um nome, uma descrição, um schema de parâmetros tipado e uma função execute, passados ao createAgentSession em customTools. A ferramenta aparece para o modelo exatamente como read ou bash, o schema tipado dá autocompletar no editor e o agente recebe entradas já validadas. É o mesmo mecanismo de um servidor MCP, só que tudo mora no seu arquivo, sem processo separado nem protocolo no meio s8.

O próprio CLI é personalizado por quatro mecanismos, todos em pastas do seu projeto ou da sua pasta pessoal: extensões (módulos TypeScript que registram ferramentas, comandos slash, atalhos de teclado ou elementos de interface, carregados na inicialização a partir da pasta extensions), skills (pacotes de capacidades que seguem o padrão Agent Skills, invocados pelo modelo ou chamados à mão, então os skills que você já tem são reaproveitados como estão), templates de prompt e temas recarregados com o CLI rodando s3. O README resume a filosofia numa linha: adapte o pi aos seus fluxos de trabalho em vez do contrário, sem fazer fork nem mexer nos internos s3. Onde os grandes harnesses embutem subagentes, modo plano e permissões no produto, o pi os deixa de fora de propósito, para serem escritos como extensões ou instalados pela comunidade s3.

Os limites são documentados pelo próprio projeto. Não há pedidos de permissão embutidos: por padrão o agente pode rodar um comando bash sem perguntar. O guia oficial de containerização assume isso e propõe três padrões de isolamento, Docker entre eles, mas montar um antes de soltar o agente numa máquina que importa é tarefa sua s5. A maturidade é o outro custo: v0.84 e não 1.0, cerca de cem issues abertas e APIs ainda marcadas como experimentais, como o cliente de sessão remota adicionado nas últimas semanas s7. As mesmas peças já servem a outro produto: o pi-chat as aplica à automação de conversas s6.

Veredito: manter, testar ou pular

Faça isto na segunda

• Instale o CLI com npm install -g --ignore-scripts @earendil-works/pi-coding-agent, rode pi, conecte um provedor com o comando login e acompanhe a barra de custo durante uma tarefa real.
• Abra um repo que já tenha um AGENTS.md ou CLAUDE.md e confira se o pi o reconhece; compare as primeiras respostas do agente com as do seu harness habitual com o mesmo prompt.
• Faça uma conversa, depois um fork a partir de um nó anterior e siga numa direção diferente; liste ~/.pi/agent/sessions/ para ver os arquivos JSONL e suas pastas de projeto.
• Escreva um our-agent.ts de vinte linhas: importe createAgentSession, passe um ModelRuntime e um SessionManager em memória, pergunte o que a pasta atual contém e rode com npx tsx.
• Adicione um defineTool que leia algo do seu próprio sistema (uma API interna, uma view de banco, um CSV) e passe em customTools; confirme que o agente o chama sozinho diante de uma pergunta relevante.
• Antes de qualquer execução com bash habilitado numa máquina que você valoriza, escolha um dos três padrões de isolamento do guia de containerização e monte.
• Rascunhe uma primeira extensão que intercepte as chamadas de bash e peça confirmação em comandos destrutivos; deixe na pasta extensions do projeto, sob controle de versão.
• Dê uma passada na lista de issues abertas para saber quais partes mudam antes de construir em cima.

Para ir além

• Leia a documentação do SDK para ver a lista completa de opções do createAgentSession: conjunto de ferramentas, prompt de sistema via ResourceLoader, gerenciadores de sessão s8.
• Estude os três padrões de isolamento do guia de containerização antes de entregar qualquer coisa que rode bash na máquina de um usuário s5.
• Veja o pi-chat para entender como os mesmos cinco pacotes são rearranjados para automação de conversas em vez de código s6.
• Navegue pela pasta packages e leia o pi-agent-core sozinho: é a menor versão legível do loop que todo harness embutido executa s2.
• Acompanhe a página de releases: da v0.84.0 à v0.84.2 saíram em duas semanas de agosto, então espere notas de mudança que afetam as extensões s4.
• Use as issues abertas como mapa do que ainda é experimental, começando pelo cliente de sessão remota s7.
• Reaproveite os skills que você já escreveu para outras ferramentas: a pasta de skills do pi segue o padrão Agent Skills s3.

Fontes

• pi: the agent toolkit (repository), Earendil Works. Por que ler: o README com a lista de pacotes, o número de estrelas e forks e a licença MIT.
• pi monorepo packages, Earendil Works. Por que ler: os cinco pacotes lado a lado, o jeito mais rápido de ver qual camada cada um cuida.
• pi-coding-agent package README, Earendil Works. Por que ler: comando de instalação, ferramentas padrão, sessões e os quatro mecanismos de extensão.
• pi releases, Earendil Works. Por que ler: o ritmo e o changelog da linha v0.84.
• pi containerization guide (isolation patterns), Earendil Works. Por que ler: os três padrões de isolamento para aplicar antes de habilitar bash onde importa.
• pi-chat: the same bricks applied to conversation automation, Earendil Works. Por que ler: um segundo produto feito com os mesmos pacotes, útil para avaliar o quanto são reutilizáveis.
• pi open issues, Earendil Works. Por que ler: a lista ao vivo do que é instável ou experimental na versão atual.
• pi-coding-agent SDK documentation (createAgentSession options), Earendil Works. Por que ler: os nomes exatos das opções do createAgentSession, do defineTool e dos gerenciadores de sessão.

FAQ

O pi pode substituir meu agente de código do dia a dia hoje?

Não como substituto direto. Ele vem sem pedidos de permissão, o isolamento fica por sua conta, e a versão é pre-1.0 com cerca de cem issues abertas. Mantenha seu harness atual para trabalhar e rode o pi ao lado.

Preciso de MCP para dar uma ferramenta customizada ao pi?

Não. O defineTool recebe um nome, uma descrição, um schema de parâmetros tipado e uma função execute, e a ferramenta é passada ao createAgentSession em customTools. Ela se comporta como uma ferramenta embutida, sem processo separado nem protocolo.

Meus AGENTS.md, CLAUDE.md e skills atuais vão funcionar?

Sim. O CLI carrega automaticamente o AGENTS.md ou CLAUDE.md do seu projeto, e a pasta de skills segue o padrão Agent Skills, então os skills existentes carregam sem mudanças.

Por que só quatro ferramentas por padrão?

read, write, edit e bash são todo o conjunto padrão, bem menos que os agentes do mercado, e o projeto apresenta isso como uma escolha. Todo o resto é adicionado de forma deliberada via customTools ou uma extensão.