Install
npm i -g gentle-piPara quem é
Gentle Shell é para desenvolvedores que já usam Pi como agente de codificação, querem desenvolvimento controlado e esperam que o agente explore antes de mexer no código, pergunte apenas nos pontos de decisão reais e mantenha em passos pequenos o trabalho pequeno e bem compreendido. O fluxo de trabalho cotidiano tem nome oficial: Organic Driven Development (ODD) — o agente explora antes de mudar qualquer coisa, esclarece apenas decisões reais e mantém pequeno o trabalho pequeno e compreendido. Depois de instalado, uma sessão comum de Pi vira um espaço de trabalho: orquestração de agentes, mudanças ao vivo e status de execução, monitoramento de uso para contas de provedores compatíveis e visões de diff integradas ficam na mesma interface. A documentação oficial também cita SDD/OpenSpec (opcional), além de subagents, evidências TDD, review guardrails, skills e integrações de memory.
Quando não serve ou quais pré-requisitos existem: se você não usa Pi, a documentação oficial não diz nada sobre executá-lo em outros agentes. Até a migração oficial terminar, o pacote npm e o repositório continuam se chamando gentle-pi, de modo que o nome do produto e o do pacote não coincidem. Quais sistemas operacionais são necessários e qual versão de Pi é exigida não são mencionados; confirme por conta própria antes de instalar.
A primeira tentativa em 3 minutos
Comece aceitando um efeito colateral da instalação que a documentação oficial declara abertamente: gentle-pi substitui a extensão codemode integrada do Pi pelo próprio compact renderer, e daí em diante o Pi avisa a cada inicialização que a versão integrada não foi carregada. Em outras palavras, o efeito colateral acontece na etapa de instalação, não durante a execução de alguma tarefa; decidir instalar ou não é decidir aceitar isso ou não. Quem depende do comportamento do codemode integrado deve avaliar antes; os demais podem tratar o aviso de inicialização como algo esperado.
Há um só caminho principal recomendado: instale globalmente no terminal com npm i -g gentle-pi. Depois de instalar, inicie o gentle-shell: ele abre o Pi e carrega o pacote Gentle Shell do seu próprio diretório home ~/.gentle-shell/agent; para carregar de um ~/.pi/agent existente, acrescente --link na inicialização. Isso é apenas a troca de local de carregamento prevista oficialmente, não um segundo método de instalação; os dois locais estão nas instruções oficiais, escolha um.
Segundo a descrição oficial, há dois sinais de sucesso: primeiro, o que se abre após a inicialização é uma sessão de Pi com o pacote Gentle Shell carregado; segundo, aparece o aviso de inicialização de que o codemode integrado não foi carregado — justamente a prova de que a substituição surtiu efeito. Os dois se observam na primeira tela após a inicialização, sem precisar executar antes nenhuma tarefa que mude algo. Para a primeira tarefa, escolha uma pequena e puramente analítica sobre código: por exemplo, peça ao agente para ler um módulo e explicar a estrutura dele e as relações de chamada, sem mudar nada por enquanto. O caminho ODD já é, por natureza, explorar primeiro, então esta fase não produz mudanças; quanto a saber se o agente escreve arquivos, executa comandos ou acessa a rede ao executar tarefas, a documentação oficial não diz — não trate isso como fato confirmado e verifique dentro da sessão antes de deixá-lo agir.
Casos de uso
Caso um: entender código desconhecido. Inicie na sessão uma tarefa assim: ler primeiro um módulo, explicar suas responsabilidades e dependências, não modificar arquivos. É o caminho cotidiano do ODD — o agente explora primeiro e pergunta apenas sobre pontos de decisão reais, e as tarefas pequenas permanecem pequenas. Se o agente perguntar depois de explorar, pela descrição oficial do ODD devem ser perguntas que realmente afetam decisões. O resultado esperado é uma explicação baseada nessa exploração; o formato da resposta não é definido oficialmente, guie-se pelo que a sessão realmente produz.
Caso dois: conferir enquanto muda. Peça ao agente uma pequena alteração enquanto confere cada mudança na visão de diff integrada; os painéis de mudanças ao vivo e de status de execução mostram o que o agente está fazendo, e se a sua conta pertence a um provedor compatível, o monitoramento de uso aparece na mesma interface. O valor deste caso está em o processo de mudança ficar visível: as visões vêm da documentação oficial, as mudanças vêm da tarefa, e dá para confrontar os dois lados. O que mudar é decidido entre você e o agente na sessão; a documentação oficial cobre apenas essas visões e capacidades de status e não garante a qualidade das reescritas.
Limites de uso
Efeitos colaterais e pontos de confirmação: instalar o gentle-pi substitui o codemode integrado do Pi (o compact renderer assume), e o aviso de inicialização é um fenômeno esperado, não uma falha. Fora isso, a documentação oficial não diz nada sobre a abrangência da execução de comandos, da leitura e escrita de arquivos nem do acesso à rede; se esses comportamentos ocorrem é algo desconhecido, não presuma que é somente leitura. Também não explica como as mudanças feitas na sessão são gravadas em disco nem se há confirmação passo a passo; observe o comportamento real do agente na sessão antes de decidir continuar.
Pré-requisitos de ambiente: voltado a sessões de Pi, instalado globalmente via npm; se funciona em outros agentes e quais linguagens de código ou texto suporta, não é mencionado. As limitações declaradas oficialmente: o pacote npm e o repositório continuam se chamando gentle-pi até a migração terminar, de modo que a divergência entre nome de produto e nome de pacote persiste; --link apenas muda o local de onde o pacote é carregado. Ficam por confirmar como configurar e desinstalar, se o codemode integrado é restaurado após a desinstalação e como ativar SDD/OpenSpec, subagents, evidências TDD, review guardrails, skills e as integrações de memory; a documentação os lista como capacidades, sem dar passos.