Parece que há poucos recursos, mas o agente fundamentalmente só lê, escreve, edita e executa. Muitas capacidades mais complexas podem, na verdade, surgir destes primitivos.

Muitos produtos de agente irão configurar planos, sub-agentes, MCP, aprovações de permissão e listas de tarefas, tudo pronto, para que o usuário apenas configure.

O PI lhe dá um esqueleto de agente funcional para personalizar. Deseja o modo de plano? Use o arquivo de escrita ou instale uma extensão. Deseja sub-agentes? Use tmux para iniciar múltiplos Pi ou escreva sua própria extensão. Deseja conectar-se ao MCP? Instale a extensão correspondente.

Parece mais uma casa de alvenaria com água e eletricidade já instaladas. O conforto de morar nele depende do seu trabalho de acabamento posterior.

Instalação

Metodo 1: Deixar o agente instalar para você

Se você já estiver usando Codex, Claude Code ou outros agentes que podem operar terminais, envie o seguinte trecho completo para ele:

Instale e verifique o Pi Coding Agent com base no ambiente atual do seu computador:

1. Primeiro, verifique o sistema operacional, a arquitetura do CPU, Node.js, npm e o node e o npm realmente ativos no PATH atual;
2. O Pi requer Node.js >= 22.19.0. Se não for atendido, primeiro descreva a solução de atualização, não altere diretamente o meu ambiente;
3. Instale o pacote npm oficial @earendil-works/pi-coding-agent, mantendo o --ignore-scripts sugerido pela equipe;
4. Após a instalação, execute `pi --version` e `pi --help` para validação;
5. Não leia, imprima ou modifique qualquer chave de API ou credenciais de login;
6. Diga-me como acessar `/login` para logar em assinaturas existentes e como fazer uma verificação de leitura apenas em um diretório de teste vazio;
7. Se houver problemas, verifique primeiro o repositório oficial do projeto e a documentação do site atual, não adivinhe os parâmetros.

Metodo 2: Instale por conta própria, passo a passo

Passo 1: Verifique Node.js e npm

Em macOS, Linux, abra o terminal. Em Windows, abra o PowerShell. Execute primeiro:

node -v
npm -v

O Node.js requerido pelo pacote npm do Pi é:

>= 22.19.0

Se node -v estiver abaixo desse nível, atualize o Node.js primeiro. Para amigos que tiveram nvm, Homebrew e o Node.js do sistema instalado, dê uma olhada mais atenta:

which node
which npm

Às vezes, você acha que atualizou, mas o terminal ainda está chamando a versão antiga. Este é um buraco comum em ferramentas CLI. Em Windows, há um requisito adicional. O Pi roda comandos Bash por padrão através do Git Bash, então instalar o Git for Windows basta.

Passo 2: Instale o Pi

Comando de instalação oficial via npm:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Lembre-se de que o --ignore-scripts precisa ser mantido. Ele proibirá que os dependentes execute scripts de ciclo de vida na fase de instalação, e a instalação normal do npm do Pi não precisa desses scripts.

O site oficial também fornece um script de instalação em um clique:

curl -fsSL https://pi.dev/install.sh | sh

Todos esses métodos funcionam. Mas curl | sh é realmente o mais fácil.

Após a instalação, verifique:

pi --version
pi --help

Até 12 de setembro de 2026, a versão atual do repositório oficial é 0.85.1. O projeto é iterativo rapidamente, então a versão não corresponder não é necessariamente falha de instalação. Você pode primeiro verificar os Releases do GitHub e a versão local pi --version.

A documentação oficial do Quick start também é este comando npm.

Por que não consigo iniciar mesmo após a instalação?

Uma das situações mais comuns é que o terminal mostre:

pi: command not found

Você pode primeiro fechar e reabrir o terminal, e verificar o local de instalação global do npm:

npm config get prefix
npm list -g --depth=0

Se a lista já tiver @earendil-works/pi-coding-agent, o pacote provavelmente foi instalado, mas o diretório de executáveis globais do npm não está no PATH. Em macOS e Linux, geralmente é preciso verificar o diretório bin no prefixo global, e em Windows, verificar o diretório global do npm.

Outro problema é que a versão do Node.js parece estar correta, mas ao executar o Pi, ele ainda está usando o ambiente antigo. Verifique as seguintes opções juntas:

which node
which npm
which pi
node -v
pi --version

Se pi abrir, mas a lista de modelos estiver vazia, execute /login primeiro, selecione o modelo com /model. Você também pode sair e verificar no comando de linha:

pi --list-models

Passo 3: Faça login no modelo

Inicie diretamente:

pi

Após abri-lo, a interface é relativamente simples: no meio está a caixa de entrada, e na parte inferior exibe o diretório atual, o contexto e o modelo.

Após entrar na interface de terminal, digite:

/login

O Pi solicitará que você escolha o provedor de modelo. Oficialmente, atualmente suporta mais de 15, tanto com chaves de API quanto com logins em assinaturas existentes.

Se você tiver ChatGPT Plus ou Pro, pode escolher o OpenAI Codex; também suporta GitHub Copilot. Embora o Claude Pro/Max possa ser logado, o site oficial lembra que as chamadas de Harness terceirizadas seguirão o uso extra do Anthropic, com cobrança extra por token, e não consumirá diretamente a cota dentro do pacote. Este é um ponto a ser cuidado.

Para amigos que usam a API do DeepSeek, também podem fornecer no ambiente de variáveis:

export DEEPSEEK_API_KEY=seu_chave
pi

No entanto, para iniciantes, ainda prefiro usar /login no Pi. As credenciais serão salvas em ~/.pi/agent/auth.json.

Após o login bem-sucedido, use os seguintes comandos para alternar o modelo e o nível de pensamento:

/model
/thinking

Ctrl+L também pode abrir rapidamente o seletor de modelos, e Shift+Tab pode alternar o nível de pensamento.

Passo 4: Execute uma verificação de leitura apenas

Entre em um diretório de projeto que você está testando, e execute o seguinte comando:

pi --tools read,grep,find,ls -p "Leia o diretório atual, me diga o que o projeto faz, onde está o arquivo de entrada e qual verificação deve ser executada. Não modifique nenhum arquivo."

Aqui usou o modo Print do Pi, e após a conclusão da tarefa, ele sairá diretamente; --tools limita as ferramentas disponíveis apenas no escopo de leitura. Em seguida, verifique três coisas: o modelo pode se conectar, o Pi pode ler o workspace e as restrições de ferramentas estão em vigor.

Se você só quiser ver alguns arquivos, também pode colocá-los diretamente nele:

pi -p @README.md "Explica de forma simples a forma de instalação e inicialização deste projeto"

O Pi também suporta ver imagens:

pi -p @screenshot.png "Vê este página de erro, para eu identificar a sequência"

Passo 5: Verifique a capacidade de escrita

Crie um diretório de teste dedicado:

mkdir pi-playground
cd pi-playground
pi

Envie para ele o seguinte tarefa mínima:

Primeiro, confirme o diretório de trabalho atual e liste os arquivos existentes.
Em seguida, crie um arquivo hello-pi.md com o seguinte conteúdo: a data atual, o diretório de trabalho e os nomes das ferramentas que você pode usar.
Além do arquivo hello-pi.md, não crie, modifique ou delete nenhum outro arquivo.
Após a conclusão, verifique o diretório novamente e me diga quais mudanças reais ocorreram.

Esta tarefa não tem muita tecnologia, mas é ideal para validação. Ele vai encontrar leitura de diretório, escrita de arquivo, cumprimento de restrições e verificação de resultados.

Após confirmar que tudo está normal, podemos então colocar o Pi com mais confiança em um projeto real.

Se o projeto tiver um arquivo .pi/settings.json, recursos .pi ou Skills de nível de projeto, o Pi pode perguntar se você confia no diretório atual.

Confiar no projeto significa que ele pode carregar a configuração do projeto, instalar pacotes faltantes e executar Extensions de projeto.

Lembre-se dos comandos comuns do Pi

• /login: faça login ou altere o provedor de modelo;
• /model: troque o modelo;
• /thinking: ajuste o nível de pensamento;
• /new: crie uma nova sessão;
• /resume: continue uma sessão histórica;
• /tree: abra a árvore de sessões, volte para qualquer nó;
• /compact: compacte manualmente o contexto;
• /reload: recarregue a configuração, Skills, Extensions e temas;
• /hotkeys: veja todas as teclas de atalho;
• /session: veja o arquivo da sessão atual, ID, Token e custos.

Acho que este comando /tree é muito importante.

Se a direção do chat anterior estiver errada, pode ser que apenas abra uma nova sessão. O Pi salva as Sessões com uma estrutura de árvore, você pode voltar a uma mensagem antiga e partir de lá com uma nova ramificação, a ramificação original ainda está no mesmo arquivo JSONL.

Por exemplo, se você pedir ao agente para refatorar código, se ele encontrar que a rota está errada a meio do caminho, volte diretamente para "início da refatoração" e mude o plano, sem precisar alimentar todo o contexto anterior. Especialmente em tarefas longas, esta função é muito útil.

As sessões do Pi são salvas por padrão em:

~/.pi/agent/sessions/

No comando de linha, você também pode continuar a conversa assim:

pi -c
pi -r

A primeira continua a última sessão, e a segunda permite que você escolha uma sessão histórica.

Usando no seu produto próprio

O Pi não pode apenas conversar no terminal.

A forma de uso oficial