Claude Code já vem com as baterias, o Pi te entrega os circuitos

Versão original em inglês: Claude Code ships the batteries, Pi hands you the wires.

Dois agentes de programação de terminal. Praticamente o mesmo núcleo de quatro ferramentas. Apostas opostas sobre quem é dono do harness.

O harness é tudo o que envolve o modelo de linguagem para transformá-lo em um agente: as ferramentas que ele pode chamar, as verificações de permissão, o fluxo de planejamento, a forma como sub-tarefas e processos de longa duração são gerenciados. O modelo raciocina; o harness decide o que ele tem permissão de fazer e como. É esse envoltório, não o modelo, o ponto em que essas duas ferramentas discordam.

O Claude Code decide o fluxo de trabalho por você e entrega a maquinaria para rodá-lo: plan mode, subagentes, processos em segundo plano, hooks, permissões. O Pi, de Mario Zechner, não traz quase nada disso de propósito e te entrega os circuitos no lugar.

Eles divergem em oito decisões. Cada uma abaixo é prática, com comandos que você mesmo pode rodar.

A ideia que explica tudo

Todo o design do Pi nasce de um objetivo, nas palavras do próprio Mario Zechner: “build myself a tool where I’m in control as much as possible” (construir para mim uma ferramenta na qual eu tenha o máximo de controle possível). Duas coisas dão a ele esse controle: engenharia de contexto, decidir exatamente o que entra na janela de contexto do modelo, e observabilidade, enxergar a qualquer momento o que o agente e cada auxiliar que ele criou estão fazendo.

A crítica recorrente dele é que a maioria dos agentes abre mão dos dois no instante em que ficam “prestativos”. Um subagente roda e você recebe um resumo, não os passos. Um processo em segundo plano roda e você não consegue consultá-lo. O plan mode raciocina num buffer que você não consegue versionar. A solução dele é direta: recusar o recurso e usar uma ferramenta Unix de verdade que você já consegue observar.

graph LR
    A[Traga os seus circuitos<br/>Pi] -->|você monta mais| M((quem é dono<br/>do harness?))
    M -->|ele decide mais| B[Baterias inclusas<br/>Claude Code]

Guarde esse espectro em mente. Cada seção abaixo é o mesmo espectro, visto a partir de um recurso.

Parte A: o inventário do que o Claude Code decide por você

A superfície opinativa do Claude Code, e a resposta do Pi a cada item. As seções numeradas a seguir colocam a mão na massa nas que valem a pena ver em ação.

Decisão	Claude Code	Pi
Ferramentas padrão	Conjunto amplo (read, write, edit, bash, grep, glob, web, task, todo, MCP)	Quatro ligadas por padrão: read, write, edit, bash. grep, find, ls existem mas ficam desligadas até você habilitá-las
Plan mode	Nativo (Shift+Tab)	Nenhum. Escreva o plano em um arquivo
Subagentes	Nativo (ferramenta Task), o agente pode criá-los sozinho	Nenhum. Suba um Pi numa janela do tmux
Processos em segundo plano	Nativo (run_in_background)	Nenhum. Rode numa janela do tmux
To-dos	Nativo (TodoWrite)	Nenhum. Escreva checkboxes em um arquivo .md
Aprovação	Prompts de permissão nativos	Nenhum. Use um contêiner, ou escreva uma extensão
Hooks	Declarativos, no settings.json	Código, via uma extensão TypeScript
MCP (Model Context Protocol)	Nativo	Não nativo (adicione via extensão)
Formato da sessão	Transcrição linear	Árvore (ramifica no lugar)
Provedores	Claude em primeiro lugar	Mais de 15 provedores, /model para trocar

tmux aparece o tempo todo na metade do Pi desta tabela, então vale definir uma vez: é um multiplexador de terminal, uma ferramenta que roda várias sessões de shell em janelas e painéis dos quais você pode se desanexar e reanexar. Para rodar os exemplos, instale o Pi primeiro.

Instalando o Pi

No macOS, o Homebrew é o caminho mais limpo:

brew install pi-coding-agent

$ pi --version
0.80.3

Depois autentique um provedor, senão o pi -p não tem modelo para chamar:

pi          # inicia o Pi
/login      # OAuth (Claude Pro/Max, ChatGPT) ou cole uma API key
/model      # escolha o modelo destes exemplos (eu escolhi Sonnet 4.6)

Nota sobre cobrança. Se você faz login com uma assinatura do Claude, o Pi avisa que o uso em harness de terceiros consome do “extra usage” e é cobrado por token, não do limite do seu plano Claude. Acompanhe em claude.ai/settings/usage. Uma API key é cobrada por token de qualquer forma.

As credenciais ficam em ~/.pi/agent/auth.json. Outras plataformas: docs de instalação do Pi. Para a outra metade dos exemplos, instale o Claude Code.

1. Uma sessão comum: a caixa de ferramentas com que você começa

Conceito. Antes de qualquer fluxo, um agente entrega ao modelo um conjunto de ferramentas. Esse conjunto é a opinião do agente sobre o que é programar.

O Claude Code entrega ao modelo uma bancada abastecida: read, write, edit, bash, mais grep, glob, web fetch, um lançador de tasks, um rastreador de to-dos e quaisquer servidores MCP que você conectou. Você começa rico.

O Pi entrega ao modelo quatro ferramentas: read, write, edit, bash. Essa é toda a superfície padrão. Você pode até escolher com quais ferramentas começar. Para uma sessão somente leitura, habilite todas as ferramentas de leitura e omita todas as de escrita:

pi --tools read,grep,find,ls -p "Which tools are enabled?"

I have access to the following tools:

1. read - Read file contents (supports text files and images)
2. grep - Search file contents for patterns (respects .gitignore)
3. find - Find files by glob pattern (respects .gitignore)
4. ls - List directory contents

Sem write, edit ou bash: a sessão literalmente não consegue mudar nada.

Modelo mental. O Claude Code é uma bancada totalmente equipada. O Pi são quatro boas ferramentas de mão e uma bancada limpa que você mesmo estende.

Trade-off:

• Claude Code: padrões ricos significam menos configuração e mais coisas que o modelo faz sem você pedir.
• Pi: uma superfície mínima significa menos coisa para raciocinar e um raio de dano menor, mas você monta o resto.

2. Plano: um modo que você aprova vs um arquivo que você commita

Conceito. Planejar é deixar o agente pensar numa abordagem antes de tocar no código.

Claude Code. Aperte Shift+Tab para entrar no plan mode. O agente pesquisa em modo leitura, mostra um plano e espera. Você aprova, e ele executa. O plano vive na sessão e some com ela.

Pi. Não há plan mode. Você roda uma sessão somente leitura que escreve o plano em disco, depois o executa em uma sessão nova.

# Sessão 1: só plano, nenhuma mudança de código é possível
pi --tools read,grep,find,ls -p "Study the auth module. Write a migration plan to PLAN.md."
 
# O plano agora é um arquivo que você revisa, edita e versiona
git add PLAN.md && git commit -m "plan: auth token migration"
 
# Sessão 2: execute contra o artefato, com um contexto limpo
pi -p "Execute PLAN.md step by step. Check off each item as you finish it."

A Sessão 1 deixa um artefato em disco que você pode ler, editar e commitar:

# PLAN.md
- [ ] 1. Inventory every call site of issueToken() (grep)
- [ ] 2. Add AuthV2.issue() beside the legacy path
- [ ] 3. Migrate call sites one file at a time
- [ ] 4. Add an integration test for the V2 flow

A Sessão 2 lê esse arquivo e marca cada item conforme termina.

O raciocínio de Mario é explícito:

“Unlike ephemeral planning modes that only exist within a session, file-based plans can be shared across sessions, and can be versioned with your code.”

E a reclamação dele sobre a versão nativa:

“I need observability for planning and I don’t get that with Claude Code’s plan mode.”

Modelo mental. O plano do Claude Code é uma conversa que você aprova. O plano do Pi é um documento que você commita. Um é um momento; o outro é um artefato.

Trade-off:

• Claude Code: o modo é mais rápido e não exige disciplina.
• Pi: o arquivo sobrevive, gera diff e viaja para a próxima sessão ou o próximo colega.

3. Subagentes: um resumo em que você confia vs um painel que você observa

Conceito. Um subagente é um segundo agente que o agente principal inicia para um trabalho delimitado, grande o bastante para querer o próprio contexto, delimitado o bastante para dispensar uma sessão de planejamento completa:

• mapear cada ponto de chamada de uma função
• migrar uma API obsoleta em dezenas de arquivos
• revisar uma mudança com vários revisores em paralelo, cada um em seu próprio contexto limpo e papel (engenharia, QA, segurança), com o pai agregando os veredictos

Esse último é onde um subagente se justifica. Uma única revisão em contexto limpo precisa só de uma sessão nova; rodar várias de uma vez e juntar os resultados é o que uma sessão sozinha não consegue fazer. E se você quiser esses revisores paralelos em modelos de fornecedores diferentes, Claude, GPT e Gemini lado a lado, essa é a vantagem do Pi: ele é multi-provedor, enquanto os subagentes do Task do Claude Code ficam em modelos Claude.

Claude Code. A ferramenta Task cria um. O Claude pode decidir criá-lo sozinho, ou você pode pedir. Ele roda na própria janela de contexto e entrega ao orquestrador um relatório final, não os passos. Mas esses passos não se perdem. A atividade aparece na UI, e cada passo é escrito num log por agente em ~/.claude/projects/<project>/<session>/subagents/agent-*.jsonl. Então o subagente é observável depois do fato e em disco. O que ele não é: presente no contexto do agente pai, nem inline na sua rolagem principal.

A objeção de Mario mira nessa primeira lacuna, o repasse entre agentes:

“You have zero visibility into what that sub-agent does. It’s a black box within a black box.”

Ele não é contra subagentes por completo, porém. O uso mais comum dele é um único subagente de code review, criado via bash; o anti-padrão, nas palavras dele, é criar vários em paralelo para implementar features.

Pi. Nenhuma ferramenta de subagente. A postura oficial é trazer a sua, citada literalmente do README do Pi:

“No sub-agents. There’s many ways to do this. Spawn pi instances via tmux, or build your own with extensions, or install a package that does it your way.”

A comunidade levou isso a sério. O pi-side-agents, de Petr Baudis, é um pacote real que adiciona um comando /agent. Cada filho roda na própria janela do tmux e no próprio git worktree, e o pai observa ou conduz.

O pacote tem dois pré-requisitos, por causa de como ele isola cada filho:

1. tmux, com o Pi iniciado dentro de uma sessão tmux (cada filho recebe a própria janela). Sem isso, o /agent falha com tmux is required for /agent but was not found.
2. Um repositório git, porque cada filho roda no próprio git worktree, isolando o branch para que pai e filhos nunca colidam. Rode numa pasta comum e o /agent falha com fatal: not a git repository. Rode git init antes, se precisar.

brew install tmux                 # se você não tiver
 
# Opcional, e não obrigatório para o /agent: o tmux remove info de modificadores de tecla,
# então Shift+Enter e Ctrl+Enter viram Enter simples no Pi. Ligue as extended keys para preservá-las:
echo 'set -g extended-keys on' >> ~/.tmux.conf
echo 'set -g extended-keys-format csi-u' >> ~/.tmux.conf
 
tmux                              # inicie uma sessão, DEPOIS suba o Pi dentro dela
pi install npm:pi-side-agents     # instalação única

Depois, dentro do Pi:

/agent Map every call site of parseToken() and write findings to NOTES.md
/agents    # visão ao vivo de cada filho rodando

Cada filho é um pi de verdade rodando na própria janela do tmux. Um subagente do Claude Code entrega ao pai um relatório; um filho do Pi é um processo vivo que você pode acessar, observar ou consultar.

Lendo e conduzindo um filho. Faça isso pelo pai, a partir da sua janela principal do Pi. Comece com /agents:

/agents

[side-agents-report]
side-agents
i-ll-review-2  waiting_user  win:#1  worktree:myapp-agent-worktree-0001
  task: review .../2026-07-01-claude-code-vs-pi.md's section 3. Sub-agents

Isso é uma linha de status, não a revisão. Leia da esquerda para a direita:

• i-ll-review-2 é o id do filho, como você se dirige a ele.
• waiting_user é o status: ele terminou e está bloqueado numa pergunta para você. Outros estados que você verá são running, failed e crashed.
• win:#1 é a janela do tmux dele.
• worktree:... é o git worktree dele: um segundo diretório de trabalho apontando para o branch do próprio filho (uma pasta irmã como ../myapp-agent-worktree-0001), então ele edita arquivos sem tocar no seu checkout principal.
• task: é o prompt que ele recebeu.

waiting_user é uma pausa, não um fim. Uma linha só permanece em /agents enquanto está em andamento ou bloqueada; uma saída limpa se apaga sozinha, então uma linha visível é sempre algo ainda rodando, esperando você, ou quebrado:

stateDiagram-v2
    running --> waiting_user: pergunta algo a você
    waiting_user --> running: você responde
    running --> done: exit 0, removido automaticamente
    running --> failed
    running --> crashed

Para ler a saída de verdade dele, peça ao pai em linguagem natural, e o Pi traz o texto do filho para a sua sessão (limpo, sem captura crua de painel):

Show me side-agent i-ll-review-2's output.

Como ele está em waiting_user, você responde da mesma forma, e o pai repassa a sua resposta ao filho:

Reply to i-ll-review-2: no edits, just summarize your top three findings.

Prefere observar ao vivo? Vá para a janela dele com Ctrl-b 1 (os filhos são as janelas 1, 2, …; o seu Pi é a janela 0). Se o painel ignorar suas teclas, aperte q primeiro: você está no modo de rolagem do tmux, não travado. Ctrl-b 0 volta para o Pi. Não use capture-pane numa janela de agente ao vivo.

Encerrando um filho. Um agente em waiting_user espera indefinidamente, segurando janela, worktree e branch, até você agir. Duas saídas:

1. Encerre de forma limpa. Responda para que ele retome e saia. Ele vai até done (exit 0), some de /agents e fecha a própria janela, sem deixar nada para limpar:

   Reply to i-ll-review-2: no further action, you're done.
   

2. Abandone. Mate a janela e remova os resíduos do git você mesmo:

   tmux kill-window -t @1
   git -C <repo> worktree remove --force myapp-agent-worktree-0001
   git -C <repo> branch -D side-agent/i-ll-review-2
   git -C <repo> worktree prune

Modelo mental.

graph TD
    subgraph Claude Code
      P1[Agente principal] -->|Task| BB[caixa lacrada]
      BB -->|só o relatório final| P1
    end
    subgraph Pi
      P2[Agente principal] -->|janela tmux| GP[painel de vidro]
      GP -->|cada passo visível| You[você: vá para a janela dele]
      GP -->|agent-check, agent-send| P2
    end

Trade-off:

• Claude Code: a caixa lacrada mantém seu contexto limpo e silencioso; a ferramenta Task não exige configuração e não deixa rastro.
• Pi: o painel de vidro te mantém no controle e mostra quando o auxiliar dá errado, mas essa visibilidade é um terminal cru que você precisa montar e cuidar.

O detalhe: isso são circuitos, e circuitos têm pontas. Colocar um único subagente para rodar exigiu:

• instalar um pacote (pi-side-agents)
• instalar o tmux
• um ajuste de extended-keys no ~/.tmux.conf
• subir o Pi dentro do tmux
• git init mais um primeiro commit
• fluência de tmux suficiente para navegar entre janelas

A observabilidade é real, mas é um terminal cru: aponte o comando errado para um painel de agente ao vivo e você pode travar seu terminal. A ferramenta Task do Claude Code não faz nada disso com você, e também não te mostra nada disso.

4. Processos em segundo plano: uma ferramenta que você consulta vs um painel que simplesmente está lá

Conceito. Um processo em segundo plano é um processo de longa duração, como um dev server ou um watcher de testes, que precisa continuar rodando enquanto o agente faz outras coisas.

Claude Code. Você pede em linguagem natural:

Start a static file server on port 8199 in the background.

Ele roda um comando Bash com run_in_background: true, que devolve um id de shell:

Command running in background with ID: bpug4gf33

O agente segue trabalhando e depois lê a saída nova sob demanda com a ferramenta BashOutput, mirando nesse id:

::1 - - [02/Jul/2026 07:46:41] "GET / HTTP/1.1" 200 -
::1 - - [02/Jul/2026 07:46:41] code 404, message File not found
::1 - - [02/Jul/2026 07:46:41] "GET /missing HTTP/1.1" 404 -

Ele encerra o processo com KillShell. Repare no formato disso: a saída não está na tela, está no buffer atrás de uma chamada de ferramenta que você precisa fazer. Você consulta para ver.

A crítica de Mario aponta o custo escondido:

“Background process management adds complexity: you need process tracking, output buffering, cleanup on exit, and ways to send input to running processes.”

Ele também lembra de uma falha concreta:

“in earlier Claude Code versions, the agent forgot about all its background processes after context compaction and had no way to query them.”

Esse bug foi corrigido, mas o ponto permanece: o estado do processo vive dentro do agente, então pode se perder.

Pi. Não há ferramenta de background bash, porque bash puro mais tmux já cobre isso, e você pede na mesma linguagem natural:

Start the dev server in a tmux window called dev so it keeps running.

O Pi coloca o processo numa janela do tmux desanexada (que retorna na hora, então o agente não fica bloqueado), e lê essa janela sempre que você ou ele quiser:

tmux new-window -d -n dev 'npm run dev'   # roda na própria janela, retorna na hora
tmux capture-pane -p -t dev -S -30        # lê as últimas 30 linhas quando quiser

VITE ready in 412 ms
Local:  http://localhost:5173/

O processo é uma janela real do tmux, não estado do agente: você pode abri-la você mesmo com Ctrl-b 1, e ela sobrevive à compactação de contexto porque o Pi nunca teve que lembrar dela.

Trade-off:

• Claude Code: configuração zero, mas o processo é estado do agente. A saída fica escondida até o agente consultar o BashOutput, e o agente precisa lembrar que o processo está rodando.
• Pi: você é dono de uma janela do tmux, mas o processo simplesmente está lá. Olhe quando quiser, nada para consultar, e nada para o agente esquecer.

5. Observabilidade: prove para você mesmo

Essa é a espinha da comparação inteira, então faça na mão.

Com o Claude Code. Peça a ele para criar um subagente e iniciar um dev server, depois pergunte o que cada um está fazendo agora. A informação existe, mas mora em três lugares diferentes:

1. a atividade ao vivo do subagente, transmitida (e recolhível) na UI do chat
2. a transcrição completa desse subagente, escrita num arquivo de log por agente em ~/.claude/projects/<project>/<session>/subagents/agent-*.jsonl
3. a saída do servidor, que você só vê pedindo ao agente no chat para checar (“o que o servidor está imprimindo agora?”); ele roda a ferramenta BashOutput contra o id de shell do processo e devolve um instantâneo único para a conversa

Nenhum dos três é a sua rolagem principal, e o agente orquestrador trabalha a partir do resumo do subagente, não dos passos. A observabilidade está disponível, não é imediata.

Com o Pi. Tudo o que um auxiliar faz é um processo num painel. Um comando lista cada auxiliar que você tem rodando:

tmux ls

dev:       1 windows (created Wed Jul  1 09:14:02 2026)
research:  1 windows (created Wed Jul  1 09:15:20 2026)

Anexe-se a qualquer um deles e você está olhando a coisa real:

tmux attach -t research

Se você usa o pi-side-agents, o comando /agents dá o mesmo resumo de dentro do Pi, e suas ferramentas de pai (agent-check, agent-wait-any, agent-send) deixam o orquestrador consultar e conduzir cada filho sem nunca perdê-lo de vista.

Mario resume o contraste em quatro palavras depois de mostrar o Pi depurando um programa C que quebra num painel: “How’s that for observability?”

Seja justo com o Claude Code. O subagente isolado em contexto e o processo consultado não são bugs. Eles mantêm o contexto do pai pequeno e a sua tela silenciosa, o que importa quando o modelo precisa raciocinar sobre tudo que está à vista. Os passos ainda estão em disco se você precisar. O Pi troca esse silêncio por paredes de vidro, tudo num painel de relance. Escolha o trade-off de propósito.

6. Aprovação: prompts nativos vs um portão que você constrói

Conceito. Aprovação é o portão que barra um agente antes de uma ação arriscada, como rm -rf ou um force push.

Claude Code. Um sistema de permissões já vem na caixa. Ele pergunta antes de ações arriscadas, lembra de uma allowlist e oferece modos que vão do cauteloso ao bypassPermissions.

Pi. Sem popups de permissão por padrão. Você tem duas escolhas honestas.

Isole. Rode o processo pi inteiro dentro de um ambiente isolado que você monta, para que nada que ele faça alcance o host. O Pi não traz um sandbox; você constrói o isolamento. As docs de containerização do Pi dão três padrões, e um DevContainer é um quarto natural:

• Docker puro: construa um Dockerfile.pi e rode o Pi nele (docker build -t pi-sandbox -f Dockerfile.pi .), conforme as docs de containerização
• a extensão de micro-VM gondolin: roteia as ferramentas para uma micro-VM local, a autenticação fica no host
• a ferramenta separada openshell: um sandbox controlado por política
• um DevContainer: o .devcontainer do seu editor rodando o Pi dentro do Docker (não está nas docs do Pi, mas é a mesma fronteira)

Coloque um portão. Adicione aprovação em código, com uma extensão que intercepta as chamadas de ferramenta antes de elas rodarem:

pi.on("tool_call", async (event, ctx) => {
  if (event.toolName === "bash" &&
      event.input.command?.includes("rm -rf")) {
    const ok = await ctx.ui.confirm("Dangerous!", "Allow?");
    if (!ok) return { block: true, reason: "Blocked by user" };
  }
});

Modelo mental. O Claude Code traz as verificações de segurança e as roda por você, perguntando antes de ações arriscadas desde o primeiro dia. O Pi não traz nenhuma e te entrega a matéria-prima: isole o processo inteiro num contêiner que você construiu, ou escreva as verificações você mesmo numa extensão. De qualquer forma, a segurança é sua para projetar e sua para acertar.

Trade-off:

• Claude Code: os prompts nativos são seguros no primeiro dia, com configuração zero.
• Pi: o portão do tipo faça-você-mesmo é silencioso até você construí-lo, mas aí ele é seu e faz exatamente o que você decidiu.

7. Hooks: config que você declara vs código que você escreve

Conceito. Um hook é código que roda automaticamente num ponto definido do ciclo de vida do agente, para você impor uma regra sem ter que pedir toda vez.

Claude Code. Os hooks são declarativos, no settings.json. Você casa um evento e roda um comando de shell. Este aqui guarda toda chamada de Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python3 guard.py" }]
      }
    ]
  }
}

Pi. Sim, o Pi tem hooks, mas como código dentro de uma extensão TypeScript, não como config. A API de eventos cobre o mesmo terreno:

pi.on("before_agent_start", async (event, ctx) => { /* edita o prompt      */ });
pi.on("tool_call",         async (event, ctx) => { /* bloqueia ou permite  */ });
pi.on("tool_result",       async (event, ctx) => { /* reescreve a saída    */ });
pi.on("session_start",     async (event, ctx) => { /* prepara recursos     */ });
pi.on("session_shutdown",  async (event, ctx) => { /* faz a limpeza        */ });

Modelo mental. Um hook do Claude Code é um fio de armadilha que você declara e aponta para um script. Um hook do Pi é uma função que você escreve dentro do próprio runtime do agente, com a API completa ao alcance.

Trade-off:

• Claude Code: config declarativa é rápida e independente de linguagem.
• Pi: código em processo é mais poder e mais responsabilidade, porque a extensão roda com permissões totais de sistema.

8. Histórico da sessão: uma lista que você rola vs uma árvore que você ramifica

Conceito. A sessão é o registro salvo de uma execução. O formato dela decide se você consegue voltar e tentar um caminho diferente.

Claude Code. Uma transcrição linear. É armazenada como JSONL em ~/.claude/projects/<encoded-path>/<uuid>.jsonl, e você a retoma com --continue ou --resume. O histórico é uma lista: uma linha após a outra.

Pi. Uma árvore. O arquivo ainda é JSONL, em ~/.pi/agent/sessions/, mas cada entrada carrega um id e um parentId:

{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello"}}

Esse parentId liga cada entrada à anterior, então o arquivo forma uma árvore em vez de uma lista plana. O /tree deixa você pular para qualquer entrada passada e continuar dali, o que inicia um novo branch dentro do mesmo arquivo:

[user] ── [assistant] ── [user] ── [assistant] ─┬─ [user] <- folha atual
                                                │
                                                └─ [branch_summary] ── [user] <- branch alternativo

graph TD
    subgraph Claude Code: uma lista
      L1[msg] --> L2[msg] --> L3[msg] --> L4[msg]
    end
    subgraph Pi: uma árvore
      T1[msg] --> T2[msg] --> T3[msg]
      T3 --> T4a[branch A]
      T3 --> T4b[branch B]
    end

Trade-off:

• Claude Code: uma lista é simples e combina perfeitamente com rolagem e busca do terminal.
• Pi: uma árvore deixa você explorar uma segunda abordagem sem jogar fora a primeira, ao custo de um modelo mental mais complexo.

Quando escolher cada um

• Escolha o Claude Code quando você quer as baterias: onboarding rápido, padrões seguros e um fluxo já decidido por você para você simplesmente construir.
• Escolha o Pi quando você quer os circuitos: visibilidade total, uma superfície mínima que você entende por completo, e um harness que você molda ao seu próprio fluxo.

Nenhum é “melhor”. Eles otimizam coisas diferentes. O Claude Code otimiza a sessão mediana, pronta para uso. O Pi otimiza o seu controle sobre cada parte dela.

Principais lições

• A divisão é um único valor: o Claude Code troca visibilidade por conveniência; o Pi troca conveniência por visibilidade.
• O núcleo de quatro ferramentas do Pi (read, write, edit, bash) é a definição honesta mais enxuta de um agente de programação. Todo o resto é uma escolha que você faz.
• Todo recurso “faltando” no Pi mapeia para uma primitiva Unix que você já consegue observar: subagentes e processos em segundo plano viram janelas do tmux; planos e to-dos viram arquivos.
• Os subagentes e os processos em segundo plano do Claude Code não são defeitos. Eles mantêm o contexto pequeno. Isso é um benefício real, e um ponto cego real.
• Hooks existem nos dois, mas como config no Claude Code e como código em processo no Pi. Isso espelha o design inteiro: declarado por você, ou escrito por você.
• O formato da sessão é a pista silenciosa: uma lista otimiza para um caminho, uma árvore otimiza para explorar muitos.

Experimente você mesmo

1. Instale o Pi: brew install pi-coding-agent (ou o instalador).
2. Rode uma sessão de planejamento somente leitura e commite o PLAN.md que ela escreve.
3. Abra uma segunda janela do tmux, suba um Pi para executar o plano, e observe ao vivo indo para a janela dele.
4. Depois rode a mesma tarefa no Claude Code com plan mode e um subagente Task, e repare no que você consegue e no que não consegue ver.
5. Decida, para o seu trabalho, se você quer as baterias ou os circuitos.

Referências

• Docs do Pi: pi.dev/docs/latest (tools, extensions, session-format).
• Mario Zechner, “What I learned building an opinionated and minimal coding agent” (fonte das citações de Mario neste texto).
• Pacotes da comunidade que trazem as receitas de tmux que o próprio Pi não traz: pi-side-agents (Petr Baudis), pi-tmux (offline-ant), pi-interactive-subagents (HazAT).
• Docs do Claude Code: hooks, subagentes e background bash.