Install
npm i -g gentle-piPara quién es
Gentle Shell encaja con desarrolladores que ya usan Pi como agente de codificación, quieren desarrollo controlado y esperan que el agente explore antes de tocar el código, pregunte solo en los puntos de decisión reales y mantenga en pasos pequeños el trabajo pequeño y comprendido. El flujo diario tiene un nombre oficial, Organic Driven Development (ODD): el agente explora antes de cambiar nada, solo aclara decisiones reales y mantiene pequeño el trabajo pequeño y comprendido. Una vez instalado, una sesión ordinaria de Pi se convierte en un espacio de trabajo: orquestación de agentes, cambios en vivo y estado de ejecución, monitoreo de uso para cuentas de proveedores compatibles y vistas de diff integradas conviven en una misma interfaz. La documentación oficial también menciona SDD/OpenSpec (opcional), además de subagents, evidencias TDD, review guardrails, skills e integraciones de memory.
Cuándo no encaja o qué requisitos hay: si no usas Pi, la documentación oficial no dice nada sobre ejecutarlo en otros agentes. Hasta que termine la migración oficial, el paquete npm y el repositorio siguen llamándose gentle-pi, de modo que el nombre del producto y el del paquete no coinciden. Qué sistemas operativos necesita y qué versión de Pi exige no se menciona; verifícalo por tu cuenta antes de instalar.
El primer intento en 3 minutos
Empieza aceptando un efecto secundario de la instalación que la documentación oficial dice sin rodeos: gentle-pi reemplaza la extensión codemode integrada de Pi por su propio compact renderer, y a partir de ahí Pi avisa en cada arranque de que la versión integrada no se cargó. Dicho de otro modo, el efecto secundario ocurre en el paso de instalación, no durante la ejecución de alguna tarea; decidir si instalar es decidir si aceptas eso. Quien dependa del comportamiento del codemode integrado debería evaluarlo antes; el resto puede tratar el aviso de arranque como algo esperado.
Solo hay un camino principal recomendado: instala globalmente en la terminal con npm i -g gentle-pi. Tras instalar, arranca gentle-shell: abre Pi y carga el paquete Gentle Shell desde su propio directorio hogar ~/.gentle-shell/agent; si prefieres cargarlo desde un ~/.pi/agent existente, añade --link al arrancar. Es solo el cambio de ubicación de carga que ofrece la documentación oficial, no un segundo método de instalación; ambas ubicaciones están en las instrucciones oficiales, elige una.
Según la descripción oficial hay dos señales de éxito: primero, lo que se abre tras arrancar es una sesión de Pi con el paquete Gentle Shell cargado; segundo, aparece el aviso de arranque de que el codemode integrado no se cargó, que es justo la prueba de que el reemplazo surtió efecto. Ambas cosas se observan en la primera pantalla tras el arranque, sin necesidad de ejecutar antes ninguna tarea que cambie algo. Para la primera tarea elige una pequeña y puramente analítica sobre código: por ejemplo, pide al agente que lea un módulo y explique su estructura y sus relaciones de llamada, sin cambiar nada por ahora. El camino ODD es explorar primero por diseño, así que esta fase no produce cambios; en cuanto a si el agente escribe archivos, ejecuta comandos o accede a la red al ejecutar tareas, la documentación oficial no lo dice, así que no lo trates como hecho confirmado y verifícalo dentro de la sesión antes de dejarlo actuar.
Casos de uso
Caso uno: entender código desconocido. Lanza en la sesión una tarea así: leer primero un módulo dado, explicar sus responsabilidades y dependencias, no modificar archivos. Es el camino diario de ODD: el agente explora primero y pregunta solo por puntos de decisión reales, y las tareas pequeñas se mantienen pequeñas. Si el agente pregunta tras explorar, según la descripción oficial de ODD deberían ser preguntas que afectan de verdad a las decisiones. El resultado esperado es una explicación basada en esa exploración; el formato de respuesta no está definido oficialmente, guíate por lo que la sesión realmente produce.
Caso dos: comprobar mientras cambias. Pide al agente un cambio pequeño mientras revisas cada modificación en la vista de diff integrada; los paneles de cambios en vivo y de estado de ejecución muestran qué está haciendo el agente, y si tu cuenta pertenece a un proveedor compatible, el monitoreo de uso aparece en la misma interfaz. El valor de este caso está en que el proceso de cambio queda visible: las vistas las aporta la documentación oficial, los cambios los genera la tarea, y puedes contrastar ambos lados. Qué se cambia lo acuerdas tú con el agente en la sesión; la documentación oficial cubre solo estas vistas y capacidades de estado y no garantiza la calidad de las reescrituras.
Límites de uso
Efectos secundarios y puntos de confirmación: instalar gentle-pi reemplaza el codemode integrado de Pi (toma el relevo el compact renderer), y el aviso de arranque es un fenómeno esperado, no una avería. Aparte de eso, la documentación oficial no dice nada sobre el alcance de la ejecución de comandos, la lectura y escritura de archivos ni el acceso a la red; si ocurren esas conductas es algo desconocido, no des por hecho que sea de solo lectura. Tampoco explica cómo se escriben a disco los cambios hechos en la sesión ni si se confirma paso a paso; observa el comportamiento real del agente en la sesión antes de decidir si continúas.
Requisitos de entorno: orientado a sesiones de Pi, instalado globalmente vía npm; si funciona en otros agentes y qué lenguajes de código o texto admite, no se menciona. Las limitaciones que la documentación sí declara: el paquete npm y el repositorio siguen llamándose gentle-pi hasta que acabe la migración, de modo que la discrepancia entre nombre de producto y de paquete persiste; --link solo cambia la ubicación desde la que se carga el paquete. Quedan por confirmar cómo configurarlo y desinstalarlo, si el codemode integrado se restaura tras la desinstalación, y cómo se activan SDD/OpenSpec, subagents, evidencias TDD, review guardrails, skills y las integraciones de memory; la documentación los enumera como capacidades, sin pasos.