SoL-Pi no macOS: instalar o harness Pi e poupar tokens com Claude

O SoL-Pi não é um modelo novo. É uma extensão que faz o teu agente gastar menos tokens para chegar ao mesmo trabalho feito.

Instalei o SoL-Pi num Mac com Apple Silicon, Node v26, e passei a correr o Claude através do harness Pi em vez do Claude Code. A ideia parecia prometedora no papel: uma extensão da NVIDIA que promete reduzir a repetição de trabalho num coding agent, sem cortar a validação nem esconder evidência.

Depois de algumas horas a testar, a promessa confirma-se, mas com letras pequenas que convém ler antes de instalar. O SoL-Pi é uma extensão para o Pi, um harness de agentes concorrente do Claude Code, escrito em TypeScript puro. Não é um modelo de linguagem nem uma ferramenta de áudio. O nome completo é Scaling Auto-Research Loops for Efficient Agent Harnesses.

O que é, ao certo, o SoL-Pi

O SoL-Pi é uma extensão de eficiência de tokens para o harness de agentes Pi. Empacota quatro mecanismos de eficiência que a NVIDIA descobriu através de ciclos de auto-investigação. A ideia central é simples: antes de escalar mais loops de agentes, faz o próprio harness ser mais barato de correr.

Não precisas de GPU, CUDA nem Python. Só de Node. A extensão importa as APIs públicas do Pi e não faz patches ao Pi. O projeto está sob licença MIT e foi publicado pela primeira vez em setembro de 2026. É jovem, está ativo no GitHub e tem dezenas de issues abertas, o que diz logo muito sobre o estado da API.

O ponto que confunde muita gente: o SoL-Pi não corre dentro do Claude Code. Quem quer usar isto tem de usar o Pi como harness, e ligar o Claude por API. É o conjunto Pi + Claude (API Anthropic) + SoL-Pi, não uma extensão que se instala no Claude Code.

Requisitos

• macOS, Apple Silicon ou Intel. Não é preciso GPU.
• Node.js 22.19 ou superior. Eu testei com Node v26.
• npm.
• O harness Pi, fixado na versão 0.85.1.

O Pi é distribuído como pacote npm em @earendil-works/pi-coding-agent. A parte crítica está na versão. O SoL-Pi é testado com o Pi 0.85.1 e 0.84.2. O npm latest do Pi já vai noutra versão (1.1.0 no momento em que escrevo) e parte a extensão. Isto não é teoria, há uma issue aberta sobre isso por causa de uma incompatibilidade depois da atualização.

Instalação passo a passo

O processo completo, tal como o corri. Confirma primeiro o Node:

node -v
# tem de ser >= 22.19

A seguir, instala o harness Pi na versão compatível. Repara no pin. É de propósito:

npm install -g @earendil-works/[email protected]

Com o Pi instalado, adiciona a extensão SoL-Pi a partir do repositório oficial. Este comando instala-a para o teu utilizador:

pi install git:github.com/NVlabs/SoL-Pi

Se a quiseres só para um projeto, o README prevê o âmbito local:

pi install git:github.com/NVlabs/SoL-Pi --local --approve

Aviso importante: nunca corras pi update depois disto. Atualizar o Pi para uma versão mais recente quebra a extensão até esta ser ajustada. Fica na 0.85.1.

A configuração sol-pi.json

O SoL-Pi usa um único ficheiro de configuração. O Pi procura-o, por ordem, em .pi/sol-pi.json no projeto atual (se o projeto for de confiança) e, caso não exista, em ~/.pi/agent/sol-pi.json. O ficheiro de projeto tem precedência e não é fundido com o de utilizador.

Comecei pela configuração conservadora, que liga só os mecanismos locais, sem chamadas extra ao modelo. Cria ~/.pi/agent/sol-pi.json com este conteúdo:

{
  "version": 1,
  "actionFusion": true,
  "observationPack": true,
  "evidencePreservingReducer": false,
  "onlineContextCompact": false,
  "cacheWriteReadRatio": 12.5
}

O que cada flag faz:

• actionFusion (ligado): junta uma edição e o comando de validação que se segue na mesma tool call. Menos turns por edição.
• observationPack (ligado): resultados de ferramenta grandes e repetidos passam a ser handles estáveis com recall paginado, em vez de serem reenviados ao modelo vezes sem conta.
• evidencePreservingReducer (desligado): transforma logs de diagnóstico longos em “receipts” compactos, mas só quando cada citação bate com o log arquivado. Envia logs para um modelo remoto, daí estar desligado e daí a nota de segurança mais abaixo.
• onlineContextCompact (desligado): marca passos de plano concluídos como candidatos à compactação nativa do Pi; depois de compactar, o Pi continua a tarefa numa nova turn.
• cacheWriteReadRatio: a razão escrita/leitura de cache usada nas decisões de compactação.

Esta configuração é a mesma que o README classifica como conservadora: só os dois mecanismos que não fazem chamadas adicionais ao modelo. Só deves ligar os outros depois de leres a configuração e as implicações de segurança de cada um.

Primeiro arranque com o Claude

Falta autenticar. Arranca o Pi e, na TUI, usa /login, escolhe o provider Anthropic e introduz a API key (ou faz OAuth). A alternativa é exportar a chave antes de arrancar:

export ANTHROPIC_API_KEY=sk-ant-...

Com a autenticação feita, corre o agente indicando o provider e o modelo:

pi --provider anthropic --model anthropic/sonnet

Para modo não interativo, ou seja, um prompt único e output direto:

pi -p --provider anthropic --model anthropic/sonnet "faz o resumo deste repositório"

O modelo é escolha tua. Eu usei o Sonnet como ponto de partida, mas o Pi aceita outros modelos Anthropic. A autenticação e o modelo continuam a ser geridos pelo Pi, não pela extensão.

Como validar a instalação

Depois de instalar, confirma que a extensão está registada:

pi list

A extensão SoL-Pi deve aparecer na lista. E valida o ficheiro de configuração com o script incluído no repositório:

node scripts/check-sol-pi-config.mjs --config ~/.pi/agent/sol-pi.json

Se a configuração estiver mal formada, o script avisa antes de arrancares uma sessão. É mais rápido do que descobrir o erro a meio de um trabalho.

Onde é que isto poupa, na prática

O ganho não está em fazer o agente trabalhar menos, mas em cortar o desperdício que se acumula em sessões longas. Há quatro frentes:

• Action Fusion reduz o número de turns. Uma edição de ficheiro é quase sempre seguida de um comando de validação previsível; juntar os dois evita uma ida e volta ao modelo.
• ObservationPack ataca a fatura maior do contexto. Um resultado grande de ferramenta, depois de usado, continua a ser reenviado em cada turn seguinte. Passar a guardá-lo localmente e a devolver um handle com recall exato elimina esse replay.
• Evidence-Preserving Reducer resolve o caso do log gigante. Como diz o README, um modelo de fronteira pode gastar um pedido inteiro a ler um log quando só umas linhas afetam a próxima decisão. O reducer delega a primeira leitura a um agente mais barato e só aceita o resumo verificado.
• Online Context Compact deixa a sessão continuar sozinha depois de compactar, em vez de ficar à espera de um novo input.

Um cenário concreto: um refactor que toca em vários ficheiros, corre testes e lê logs de falha. É aqui que os mecanismos se notam. Numa sessão curta de dez minutos, a diferença quase não se sente, porque há poucos turns para acumular repetição. O ganho real aparece em tarefas longas, com muitas iterações.

A NVIDIA publicou números no blog e no paper (não os confirmei). Em EdgeBench, o SoL-Pi mantém cerca de 94% da pontuação média do Pi nos dois backends testados, usando 45 a 49% menos tokens e custando cerca de um terço menos. Comparado com harness nativos dos modelos, usa 35 a 64% menos tokens, com um custo de API a preço de lista 50 a 54% mais baixo. No Terminal-Bench 4, em 63 tarefas, resolveu 15 tarefas (contra 18 do Pi e 18 do Codex), mas com um custo total de $211.12, abaixo dos $286.45 do Pi e dos $272.35 do Codex. Os números passam sempre pela mesma leitura: menos tokens e menos custo, com alguma perda de resultados em tarefas difíceis.

Vantagens e considerações

O que ganhas:

• Menos tokens e menos custo em sessões longas de coding agent com o Claude via API.
• Menos turns por edição (Action Fusion) e fim do replay de leituras grandes (ObservationPack).
• Logs pesados deixam de poluir a decisão, com a garantia de que a compactação é verificada contra o original.
• Setup leve: sem GPU, sem Python, sem CUDA. Cerca de 20 a 60 minutos no macOS.
• Licença MIT e caminho de contribuição aberto.

O que tens de aceitar:

• Isto não é uma extensão do Claude Code. É o harness Pi a usar o Claude por API, mais o SoL-Pi. Se querias usar dentro do Claude Code, não dá sem portar, e portar dá trabalho.
• A versão do Pi tem de ficar pinada. O SoL-Pi só é testado com o Pi 0.85.1 e 0.84.2. Uma atualização normal do Pi quebra-o. Nunca corras pi update.
• Projeto jovem (primeiro lançamento em setembro de 2026), com a API ainda a mexer. É possível que uma futura versão do Pi parta a extensão antes de haver correção.
• O Evidence-Preserving Reducer envia logs para um modelo remoto. Só o atives depois de leres o SECURITY.md. Não o ligues para logs que tenham de permanecer locais.
• Na configuração conservadora, o Reducer e o Online Context Compact ficam desligados. Isto é intencional.
• As poupanças são incrementais. Como o próprio blog da NVIDIA admite, sessões curtas quase não sentem a diferença.

Conclusão

O SoL-Pi é uma proposta interessante e honesta: pega num harness de agentes e torna-o mais económico sem esconder evidência nem saltar validação. No macOS, a instalação é simples, e o único ponto verdadeiramente crítico é pinar a versão do Pi e nunca a atualizar.

Se trabalhas com o Claude via API em sessões longas, vale a pena experimentar com a configuração conservadora. Se o teu fluxo passa pelo Claude Code, isto ainda não é para ti, porque a extensão vive no Pi. Como o projeto é jovem, trata-o como algo para avaliar, não como infraestrutura de produção.

Recursos adicionais

• NVlabs/SoL-Pi — repositório oficial (GitHub)
• SoL-Pi blog — NVIDIA
• SoL-Pi: Recursively Scaling Auto-Research Loops for Efficient Agent Harness (arXiv 2609.20519)
• Pi — harness de agentes (earendil-works)