Depois do setup para rodar IA em ambiente local, eu resolvi trocar meu agente (harness) — eu usava o Opencode e agora estou usando o PI.

Nunca escrevi nada sobre o Opencode, porque tudo sempre me pareceu meio mágico: instalar, escolher o modelo e usar. Embora isso seja muito cômodo, me incomodava demais.

• Embora não seja obrigatório, tem um modelo de assinatura
• Caixa preta entre o modelo e o agente — que diabo acontece com o contexto das tuas alterações?

PI Agente

Vou começar dizendo o que ele te oferece:

• read: Lê arquivos
• write: Cria arquivos
• edit: Edita arquivos
• bash: Executa comandos no terminal

Agora o que não tem:

• Não tem MCP
• Não tem proteção: o agente pode fazer as mesmas alterações que o seu usuário atual pode fazer
• Não tem TODO list
• Não tem sub-agentes

Essa simplicidade é o que faz do PI um excelente agente, porque agora eu tenho acesso à minha janela de contexto de forma cristalina. Com esse acesso, eu descobri que nosso contexto é uma árvore de decisões e que eu posso andar nessa árvore, refazer os passos e alterar os rumos... ou seja, tenho o controle novamente, SEM CAIXA PRETA!

A árvore de contexto

Isso de "andar na árvore" não é força de expressão: cada sessão do PI é salva literalmente como uma árvore, num arquivo JSONL. Cada mensagem — minha, do modelo, resultado de uma ferramenta — vira um nó com um id e um parentId; o ponto onde estou agora é só a folha ativa dessa árvore. Rodando /tree eu vejo essa estrutura inteira na tela: os galhos que segui, os que abandonei, e onde exatamente cada decisão puxou a conversa pra um lado ou pro outro.

E aqui mora o pulo do gato: eu posso selecionar qualquer mensagem antiga minha, editar o texto e reenviar — o PI cria um novo galho a partir dali, sem apagar o que eu já tinha explorado no galho anterior. Se três passos atrás eu pedi pro modelo seguir por um caminho ruim (uma abordagem errada, um arquivo errado, um raciocínio torto), eu não preciso "consertar" a conversa inteira nem começar do zero: volto pro nó certo e sigo por outro galho. Quando quero isolar uma ideia mais arriscada sem mexer na linha principal, uso /fork (abre um arquivo de sessão novo a partir daquele ponto) ou /clone (duplica o galho ativo inteiro antes de continuar).

Isso é exatamente o oposto da caixa preta que me incomodava no Opencode. Lá, se o contexto desandava, minha única saída era começar de novo e torcer pra não repetir o mesmo erro — sem saber direito o que tinha sido mandado pro modelo até aquele ponto. Aqui, contexto vira uma coisa que eu manipulo de verdade: reviso decisão por decisão, podo o que não presta, enxerto de novo a partir de qualquer ponto da história. É controle de versão pro meu próprio raciocínio, não só pro código.

Conceito

No PI temos:

• Extensões: escritas em TypeScript, elas expandem as capacidades do agente
• Skills: escritas no formato Markdown, são diretivas de comportamento, do tipo: "faça isso, depois aquilo..."
• Templates: para ações repetitivas

Extensões na inicialização

Antes do primeiro turno de cada sessão, as extensões já deixam prontos:

• ferramentas de trabalho;
• regras de segurança/comportamento;
• políticas do projeto (AGENTS.md);
• skills especializadas (ativadas por contexto);

Extensões que eu instalei:

a) confirm-destructive.ts Pede confirmação antes de ações destrutivas de sessão (ex.: limpar/trocar/forkar sessão).

b) dirty-repo-guard.ts Verifica se há mudanças não commitadas no Git e pode bloquear troca/fork de sessão até a confirmação.

c) git-checkpoint.ts Cria checkpoints do estado do código com git stash create por turno e pode restaurar no fork.

d) permission-gate.ts Intercepta comandos bash perigosos (ex.: rm -rf, sudo, chmod/chown 777) e pede confirmação.

e) protected-paths.ts Bloqueia write/edit em caminhos protegidos (ex.: .env, .git/, node_modules/).

f) preset.ts Permite presets para trocar modelo, nível de raciocínio, ferramentas e instruções via --preset, /preset e atalho de teclado.

E usei o próprio PI para criar a minha própria extensão de memória. No Opencode, eu tinha um MCP que conversava com o Obsidian e adicionava notas no vault (decisões, logs, etc.).

Trocando o Obsidian por uma CLI

Essa extensão de memória guarda tudo em Markdown puro, num repositório git separado (meu "vault"). No começo eu usava o Obsidian só pra dar uma folheada nessas notas de vez em quando. O problema é que o Obsidian é um app Electron, pesado, e toda vez que eu queria buscar algo ou seguir um link entre notas, eu tinha que abrir a janela dele — o que quebrava completamente o fluxo de ficar 100% no terminal com o PI.

A única coisa que eu realmente usava do Obsidian era a busca e os links entre notas (tipo [[esse-outro-assunto]], que viram um mapa de "quem fala sobre o quê"). Troquei o Obsidian por uma ferramenta de linha de comando chamada zk: ela lê exatamente os mesmos arquivos Markdown, entende esses mesmos links entre notas e faz busca rápida sem precisar de nenhuma janela aberta. Pra mim, virou só mais um comando no terminal; pro PI, virou uma forma de consultar decisões e descobertas antigas sem sair do bash. Resultado: continuo com meu "segundo cérebro" de notas — decisões, descobertas, logs de sessão, tudo linkado — só que agora sem nenhum bloat de app rodando no fundo, e com o próprio PI conseguindo ler e escrever nesse vault durante a conversa, sem eu precisar copiar e colar nada manualmente.

E era isso, total controle do que está acontecendo.