Por dentro do pi: 92.000 estrelas para criar seu agente

Claude Code, Codex e Gemini CLI são harnesses de agente projetados por outra pessoa — e se você passa sua jornada de trabalho dentro de um deles, convive com essa decisão de design. Quer mudar um comportamento, adicionar uma ferramenta, apertar uma regra de permissão? Espera o fornecedor lançar. Você não sabe o que tem no system prompt, não vê o loop que executa as ferramentas, e não pode mudar nada disso, mesmo essas ferramentas já sendo o posto de trabalho principal de milhares de desenvolvedores.

Um projeto open source faz o oposto exato: o pi, um toolkit que entrega as peças soltas pra montar seu próprio agente, do conector do modelo até a interface. Ele conquistou 92 mil estrelas no GitHub no primeiro ano e lança um release quase toda semana. Este artigo cobre o que o pi realmente entrega na caixa, como construir seu próprio agente com o SDK dele, e um veredito honesto contra os harnesses prontos.

Um harness é toda a engrenagem em volta de um modelo de linguagem que o transforma num agente funcional. Um modelo sozinho só faz uma coisa: ler texto e produzir texto. Ele não lê seus arquivos, não roda um único comando, e não lembra de nada de uma sessão pra outra. Tudo o mais é o harness — o system prompt que enquadra o modelo, as ferramentas expostas a ele, o loop que executa as chamadas de ferramentas e devolve os resultados, e a interface no seu terminal.

O harness também decide os detalhes que importam no dia a dia: como o histórico é compactado quando o contexto transborda, como um erro de ferramenta volta ao modelo, o que é logado e o que não é. Claude Code é um harness. Codex também. Quando um agente te impressiona, boa parte do mérito vai pra essa engrenagem, não pro modelo — coloque o mesmo modelo em dois harnesses diferentes e você terá dois agentes que não estão no mesmo nível.

O pi, feito pela Earendil Works, corta essa engrenagem em blocos reutilizáveis. Você pode usar o agente de código dele assim mesmo, ou pegar os blocos um a um e montar o seu. A segunda opção é a que nos interessa.

pi é um monorepo — um único repositório que hospeda cinco pacotes publicados separadamente — e cada pacote cobre um andar do harness:

Pacote	O que faz
pi-ai	API unificada pra OpenAI, Anthropic, Google e o resto: streaming de respostas, blocos de raciocínio com seus níveis, descoberta dinâmica dos modelos de cada provedor. Troca de laboratório mudando um argumento.
pi-agent-core	O loop de agente em si: estado da conversa, mais o ciclo que envia a mensagem, lê as chamadas de ferramentas, executa e devolve os resultados até a tarefa acabar. Os casos complicados — uma ferramenta que falha, uma resposta cortada, chamadas em paralelo — já estão resolvidos.
pi-tui	Biblioteca de renderização de terminal com render diferencial: só redesenha o que muda na tela.
pi-coding-agent	O agente de código completo, montado a partir dos blocos acima — prova de que o toolkit basta pra construir um produto pronto.
pi-telemetry	Plugue suas próprias métricas de uso sem depender de um provedor.

O loop de agente é exatamente a peça que você reescreveria mal do zero; escrevê-lo direito são semanas de trabalho que você ganha num import. O time aplica a mesma receita em outro lugar: um repositório à parte, pi-chat, reaproveita os mesmos blocos pra automação de conversas.

Os números mostram que a fórmula funciona:

Métrica	Valor
Estrelas no GitHub	92.123
Forks	11.400
Commits	5.700+
Licença	MIT
Lançamentos nas duas primeiras semanas de agosto de 2026	3 (v0.84.2 saiu em 14 de agosto)

A licença MIT significa que você pode usar, modificar e redistribuir o pi sem restrição, até num produto comercial. pi não é só mais um framework: é um harness completo entregue em peças soltas, mantido num ritmo firme.

O CLI do pi é o agente de código já montado que você recebe antes de mexer em qualquer código, e é por ali que você vai começar. A instalação é uma linha, e a flag --ignore-scripts não é um detalhe: ela impede que suas dependências rodem scripts de instalação, uma das brechas mais exploradas no npm. Abra o pi, conecte seu provedor com o comando de login, e você tem um agente de código ali mesmo no seu terminal. A barra de status mostra a pasta atual, a sessão, os tokens gastos e o custo em tempo real — você vê cada requisição precificada no momento em que sai, em vez de descobrir a fatura no fim do mês.

Os comandos slash cobrem o dia a dia: model pra trocar de modelo sobre a marcha, compact pra resumir o histórico quando o contexto incha, export pra extrair a conversa, settings pro resto. Um arquivo markdown na pasta de prompts vira um comando que você aciona digitando o nome dele.

A verdadeira marca registrada do pi é a gestão de sessões. Cada conversa é salva em JSONL na sua pasta home, organizada por projeto — e o histórico é, na verdade, uma árvore, não uma linha. Você pode voltar a qualquer ponto de uma conversa e seguir por outro caminho com fork, depois navegar entre ramos com tree. Um prompt que falhou não custa mais nada: volte pro nó anterior e tente de novo sem perder o ramo anterior. Como tudo fica salvo localmente, resume te devolve a qualquer sessão passada, mesmo semanas depois. Nem Claude Code nem Codex oferecem uma navegação de histórico assim.

Por padrão, o modelo só recebe quatro ferramentas: read, write, edit e bash. Isso é muito pouco perto dos agentes do mercado, e é proposital (voltamos nisso mais adiante). A configuração segue a mesma lógica: um arquivo global na sua pasta home, um por projeto que sobrescreve, e um sistema de confiança que pergunta antes de aplicar as configs de uma pasta aberta pela primeira vez. Se você migrar, o pi carrega automaticamente seus arquivos AGENTS.md ou CLAUDE.md existentes como contexto, então suas instruções funcionam sem reescrever nada.

Construir um agente com o SDK do pi começa com um único import: createAgentSession, ao qual você passa um runtime de modelo e um gerenciador de sessão, devolve um agente funcional. O gerenciador de sessão é a escolha de persistência — em memória pra um script descartável, ou em disco pra reencontrar suas conversas de uma vez pra outra.

A gente testou num projeto local. Nosso script pergunta o que tem na pasta atual; o agente chama sua ferramenta read, lê a pasta e responde. Esse é o loop completo, escrito por nós, em umas dez linhas de TypeScript. As sessões que o SDK cria têm a mesma estrutura em árvore do CLI — cada mensagem está ligada à anterior — então o ramificar de histórico funciona no seu próprio código também.

As ferramentas custom são onde fica interessante. defineTool pega um nome, uma descrição, um esquema de parâmetros tipado e uma função de execução, e sua ferramenta aparece pro modelo exatamente como read ou bash. Escrevemos uma que consulta a lista de vídeos do canal, passamos em customTools, e o agente a chamou sozinho desde a primeira pergunta relevante. É basicamente o mesmo mecanismo de um servidor MCP, só que tudo mora no seu arquivo — sem processo separado, sem protocolo no meio. Como o esquema de parâmetros é tipado, seu editor autocompleta os argumentos e o agente recebe entradas já validadas.

Você também controla o modelo, o nível de raciocínio (de totalmente desligado até máximo), a lista exata de ferramentas que o modelo vê, e até todo o system prompt via um carregador de recursos se quiser começar do zero absoluto. Pra exibição, session.subscribe te entrega cada evento — texto em streaming, chamadas de ferramentas, erros — pra redirecionar pra onde quiser: um terminal, um bot de mensagens, ou um pipeline de CI que comenta seus pull requests. Numa tarde você passa de usar um agente pra ter escrito um, e finalmente sabe o que acontece a cada volta do loop.

O CLI do pi é personalizado por quatro mecanismos, todos em pastas simples no seu projeto ou na sua home:

• Extensions — módulos TypeScript que registram ferramentas, comandos slash, atalhos de teclado ou elementos de UI. Você põe o arquivo na pasta de extensions e ele carrega ao iniciar. É ali que você escreveria uma trava de permissão, por exemplo: uma extensão que intercepta comandos bash e pede confirmação antes dos mais perigosos.
• Skills — pacotes de capacidades seguindo o padrão Agent Skills, o mesmo que a Anthropic popularizou, então suas skills existentes são reaproveitadas assim mesmo.
• Prompts — prompts reutilizáveis como simples arquivos markdown.
• Temas — recarregam na hora enquanto o CLI roda.

Tudo isso se instala como qualquer pacote: pi install pega um pacote npm ou um repositório git, e um único comando atualiza tudo. Os docs resumem a filosofia numa frase: adapte o pi aos seus workflows, não o contrário, sem forkar nem mexer no interno.

É o inverso dos grandes harnesses. Onde o Claude Code traz sub-agents, plan mode e permissões dentro do produto, o pi deixa isso de fora de propósito, pra ser construído como extensão ou instalado da comunidade. A aposta é clara: um núcleo mínimo que quase não muda, e toda a personalização morando do seu lado, em arquivos versionados com seu projeto.

A transparência do pi se paga com trabalho, e esse custo vem em três partes.

Primeiro as travas: por padrão não há pedido de permissão nenhum, então o agente pode rodar um comando bash sem te perguntar nada. Os docs oficiais assumem isso e propõem três padrões de isolamento, Docker incluso — mas colocar isso em prática antes de soltar o agente numa máquina importante é com você.

Depois a maturidade: isso é v0.84, não 1.0, com uns cem issues abertas e algumas APIs ainda marcadas como experimentais, como o cliente de sessão remota adicionado nas últimas semanas. O que funciona hoje pode quebrar no próximo lançamento; esse é o preço normal de um projeto avançando tão rápido.

Por fim, o tempo. Todo conforto que o Claude Code te dá de fábrica — plan mode, sub-agents, permissões finas — é um projeto que você constrói sozinho aqui, ou um pacote da comunidade que você caça na esperança de que se mantenha. O ecossistema de extensões tem um ano: você vai achar menos pacotes prontos do que buracos pra tapar. Até a instalação te ensinou o nível de cuidado que isso exige, com sua flag --ignore-scripts, e você vai ter que manter isso em toda a cadeia. Se sua meta é entregar código hoje à noite, o pi vai te atrasar antes de te acelerar — não troque seu harness principal essa semana só com base neste vídeo.

pi é pra desenvolvedores que constroem produtos com agentes, não só com um agente. Pra eles, é provavelmente o melhor investimento de aprendizado do momento: instale o CLI, escreva um agente de vinte linhas com o SDK, e dê a ele uma ferramenta sua. Faça isso e você vai entender o Claude Code melhor que a maioria dos usuários dele.

Se você só quer um assistente produtivo hoje, fique com seu harness integrado e volte quando o 1.0 trouxer as travas: o valor do pi está em entender e controlar, não no conforto imediato. Entre os dois há um meio-termo sem risco — fique com Claude Code pro trabalho, e use o pi como banco de testes pra ver o que seu harness principal esconde.

O principal que fica é que os harnesses não são mais caixas-pretas: as peças estão na mesa, documentadas, sob licença MIT. Na próxima vez que um agente te impressionar ou irritar, você vai saber exatamente qual peça olhar.