← Volver a agentes
v0.1.0latest0 weekly · 1 total downloads

Gentle Shell

Entorno de programación basado en Pi con Organic Driven Development, subagentes, revisión de cambios y guardas. Guía de instalación, perfiles y trabajo en repositorios.

Enlaces relacionados

Acerca del agente

Gentle Shell — instalación y trabajo con agentes

Revisado: 10/10/2026
Repositorio: https://github.com/Gentleman-Programming/gentle-shell
Referencia técnica: https://github.com/Gentleman-Programming/gentle-shell/blob/main/docs/readme-reference.md
Lanzador: gentle-shell; paquete npm: gentle-pi.

Compatibilidad: documentación revisada el 10/10/2026, con gentle-pi v3.5.1 como referencia publicada. Comprueba gentle-shell --version y las releases: main puede incluir funciones posteriores.

1. Funciones

Gentle Shell es un harness de programación para Pi. Organiza exploración, implementación, delegación a subagentes y revisión de cambios en un repositorio. Su metodología Organic Driven Development (ODD) mantiene el alcance y la continuidad de tareas largas mediante artefactos de trabajo y evidencias.

Qué aporta sobre Pi

  • Lanzador standalone que abre Pi con paquetes/skills/tema y home separado.
  • Interfaz TUI/fullscreen de estado: modelo, uso, costes disponibles, cambios, TODO y agentes.
  • ODD: explorar antes de cambiar, no sobrerregular tareas pequeñas, un documento persistente para tareas grandes.
  • Subagentes especializados: explorar, implementar, comprobar, revisar, con resultado que vuelve al padre.
  • Gentle Changes: diffs y rastreo de escrituras atribuidas a esta sesión y sus subagentes.
  • Herramientas nativas de revisión, decisiones y preguntas.
  • Perfiles por modelo/esfuerzo/rol, y pin por repositorio.
  • Guardas de operaciones destructivas; modo YOLO de sesión con límites.
  • Skills y paquetes complementarios: gentle-engram, MCP, acceso web, etc.

2. Ecosistema y nomenclatura

               usuario en terminal
                      |
                  gentle-shell
                      |
       lanza Pi + paquete gentle-pi
                      |
     ODD / prompts / skills / revisiones
            |                  |
       padre/orquestador    subagentes
            |                  |
       checkout Git / cambios / tests
                      |
       opcional: Engram / MCP / web
  • Pi: el agente/CLI de programación sobre el que corre.
  • gentle-pi: paquete npm con extensiones, skills, prompts, themes, configuraciones y bin gentle-shell.
  • Gentle Shell: lanzador y experiencia TUI del paquete gentle-pi.
  • Gentle AI: software compañero y política/metodología; existen comandos gentle-ai, y el paquete puede provisionar activos a través de su binario fijado.
  • Gentle Dot: aplicación de escritorio independiente.
  • Gentle Engram: integración complementaria de memoria persistente.

3. Requisitos

Confirmados en documentación

  • Runtime Node.js y npm para npm i -g gentle-pi.
  • Un Pi disponible por alguno de los mecanismos del launcher: ejecutable especificado con GENTLE_SHELL_PI, Pi opcional incluido adyacente, o pi del PATH.
  • El launcher requiere Pi >= 0.99.1, según la referencia técnica revisada.
  • Un proveedor de LLM/modelo aceptado por Pi y autenticación correctamente configurada.
  • Git y un repositorio real para aprovechar ODD, diffs, ramas y review.
  • Terminal capaz de ejecutar aplicaciones TUI; para panel lateral fullscreen es más cómodo uno ancho.

El instalador gráfico puede gestionar Node, pnpm y Pi. Para la ruta npm, utiliza una versión de Node LTS compatible con los requisitos del paquete instalado.

Recursos y coste

Dimensiona CPU y RAM según el proyecto y las herramientas ejecutadas. El consumo del proveedor depende de modelos, turnos y subagentes simultáneos; limita concurrencia y presupuesto por tarea.

4. Instalación recomendada: standalone aislado

Ruta documentada como principal:

npm i -g gentle-pi
# Verifica qué se instaló
gentle-shell --version
# Comienza en su propio home
gentle-shell

Dónde guarda su estado

  • Home standalone por defecto: ~/.gentle-shell/agent.
  • Configuración de preferencia de home: ~/.gentle-shell/config.json.
  • Home de Pi habitual: ~/.pi/agent.
  • Configuración interna de Gentle AI: normalmente ~/.pi/gentle-ai para parte de perfiles/opciones globales; la ruta efectiva puede variar con variables/config.
  • El launcher puede crear en su primer arranque configuración visual y ejecutar autoprovisionado de complementos de Gentle AI en su propio home aislado.

Importante: “home aislado” significa directorio de configuración distinto, no contenedor Docker ni aislamiento del sistema operativo. El proceso Pi puede seguir leyendo/escribiendo archivos a los que tenga permiso Unix.

Primera ejecución

En el standalone actual, la primera ejecución configura el home aislado y puede realizar setup automáticamente. Para repetir aprovisionamiento y ver su salida:

gentle-shell setup

Para inspeccionar la versión y home:

gentle-shell --version
gentle-shell home

No necesitas llamar a gentle-shell install npm:gentle-pi en el home aislado: el launcher ya inyecta su propia copia de ese paquete. Instalar otra copia a mano puede originar conflictos de herramientas o drift de versión.

Inicio en un proyecto

cd /ruta/a/tu-repositorio
git status --short
gentle-shell

Comienza por una tarea read-only, por ejemplo: «Explora la arquitectura, señala riesgos y prepara un plan; no modifiques archivos». Después prueba un cambio pequeño con test y revisión.

5. Ruta alternativa: reutilizar un Pi ya configurado

# Si ya tienes ~/.pi/agent con login, modelos y chats:
gentle-shell --link

Este flag usa el home del Pi existente y reutiliza sesiones/credenciales/modelos. No se recomienda como primera prueba si tienes un Pi muy personalizado: comienza aislado para evitar colisiones de plugins.

Para hacer del modo link el comportamiento habitual:

gentle-shell home link
gentle-shell home

Para volver al modo aislado:

gentle-shell home isolated
gentle-shell home

Para un home arbitrario:

gentle-shell --home /ruta/a/otro/agent
gentle-shell home /ruta/a/otro/agent

La primera forma selecciona el home de esa invocación; la segunda persiste elección para próximas. Los flags --link, --isolated y --home son mutuamente excluyentes.

6. Instalar dentro de un Pi existente (sin launcher standalone)

La ruta B del README:

# Requiere que el comando 'pi' funcione antes:
pi install npm:[email protected]
# Reinicia Pi y ejecuta la sincronización indicada:
gentle-ai sync
# Abre Pi en el repositorio:
pi

El comando/versionado [email protected] es el ejemplo de stable documentado en la fecha de esta guía; consulta la release oficial antes de fijarlo para tu entorno. La ruta B modifica el home de Pi existente, a diferencia de la ruta standalone aislada. Registra o haz backup de ~/.pi/agent/settings.json y assets antes.

No mezcles ruta A y B indiscriminadamente. El launcher tiene lógica para evitar cargar dos extensiones con los mismos tools en algunos modos, pero sigue siendo más simple elegir una estrategia de instalación por home.

7. Alternativa gráfica/instalador de releases

El README también documenta descargas de instaladores para macOS, Windows y Linux. Son descargables desde las releases oficiales; comprueba checksums SHA-256 cuando existan. El instalador gráfico web/browser es descrito como preview y las ejecuciones limpias macOS/Windows aún estaban bajo comprobación en los textos revisados.

Si te interesa la opción desde código fuente:

git clone https://github.com/Gentleman-Programming/gentle-shell.git
cd gentle-shell
sh scripts/bootstrap.sh  # macOS/Linux; verificar script antes de ejecutar

El instalador puede descargar Node/pnpm temporalmente, y solicita confirmación del plan antes de instalar. No lo ejecutes con privilegios elevados sin motivo. En Windows sigue los .cmd oficiales y las rutas publicadas; no traslades literalmente el script Linux.

8. Organic Driven Development (ODD), paso a paso

ODD ajusta el esfuerzo y la trazabilidad al riesgo y a la continuidad de la tarea.

Ciclo documentado

  1. Autorizar: una petición de inspección se mantiene read-only salvo permiso de implementación.
  2. Explorar: revisar código, tests, documentación y convenciones antes de cambiar.
  3. Resolver incertidumbre: investigar o preguntar solo sobre decisiones materialmente abiertas.
  4. Clasificar: tarea pequeña si se entiende y puede reanudarse con el prompt + git diff; grande si eso no basta.
  5. Registrar trabajo grande: crear artefacto durable odd/tasks/<nombre>.md y, si Engram está operativo, espejo de memoria.
  6. Implementar por tareas: decidir el camino más seguro, aplicar tests según modo TDD, cerrar unidades con commits/evidencias cuando corresponda.
  7. Cerrar: resumen de resultado comprobado, tests pasados/fallidos, riesgos y próximos pasos.

La referencia indica que un umbral alrededor de 400 líneas de cambio es solo orientativo, no una prohibición ni un método para dividir artificialmente trabajo.

Ejemplo de trabajo acotado

Inspecciona la validación de sesiones y sus tests. Implementa el caso de expiración, ejecuta las pruebas relevantes y presenta el diff. Mantén fuera del alcance los contratos y servicios no afectados.

Para trabajos que abarcan varios servicios, utiliza un artefacto ODD con tareas y criterios de aceptación. Las operaciones sobre ramas protegidas, datos o producción siguen sujetas a los controles del repositorio.

9. Subagentes y orquestación

Gentle Shell incorpora agentes focalizados para explorar, implementar y comprobar; un padre/orquestador mantiene responsabilidad sobre alcance, decisiones y resumen. En la TUI se visualiza actividad, modelo, tokens, coste cuando esté disponible, historial e interrupciones.

  • Para qué delegar: tareas independientes, análisis paralelo o aislamiento de contexto.
  • Cuándo no: para cambiar tres líneas sencillas, donde la coordinación cuesta más que la ejecución.
  • Prevención de conflictos: define archivos/objetivos por worker, evita que dos escritores cambien la misma API sin coordinación, usa branches/worktrees cuando convenga.
  • Verificación: el padre integra resultados y ejecuta tests; no asumas que “worker finished” implica que todas sus modificaciones quedaron aprobadas.
  • Coste: cada subagente gasta sus propias llamadas; controla modelos y esfuerzo por rol.

Interfaz y atajos documentados

  • Alt+A: visor de agentes en vivo.
  • Alt+G: visor de Gentle Changes.
  • Alt+K: paleta de comandos.
  • /gentle:customize: personalización de layout y paneles.
  • /gentle:stats: estadísticas locales de uso, modelos y costes registrados.

Los atajos pueden depender del emulador de terminal y de cómo capture Alt/Option. Prueba en un terminal conocido antes de asumir que falló el plugin.

10. Gentle Changes y revisión nativa

Gentle Changes

Recoge escrituras/ediciones exitosas realizadas por las herramientas del agente y sus subagentes asociados a la sesión. Muestra archivos, líneas modificadas y diffs, con posibilidad de abrir archivos en editor.

Advertencia específica de la documentación: no registra necesariamente todos los cambios hechos por shell, procesos externos o ejecuciones fallidas. Por tanto ausencia de entrada en Changes ≠ repositorio limpio.

Antes de hacer commit verifica también:

git status --short
git diff --stat
git diff --check
git diff

Revisión nativa

Gentle Shell ofrece revisión del candidato acotado (work unit / PR slice) y reportes de riesgos con evidencia. La revisión no sustituye los tests, reglas de protección de rama ni aprobación de otra persona para cambios de alto impacto.

Recomendación de pipeline humano:

  1. git status antes; crea rama de feature.
  2. El agente explora y modifica.
  3. Tests unitarios/lint + tests de integración necesarios.
  4. Gentle Changes + revisión nativa.
  5. Revisión de git diff sin confiar solo en narrativas del agente.
  6. Commit/PR; CI y revisor humano si se requiere.

11. Comandos clave

Lanzador (terminal externo)

ComandoQué hace
gentle-shellAbre con home seleccionado, aislado por defecto
gentle-shell --versionMuestra versión Gentle Shell, Pi y home
gentle-shell --linkReutiliza home de Pi existente
gentle-shell --isolatedFuerza home standalone
gentle-shell --home /rutaHome personalizado para esa ejecución
gentle-shell homeMuestra modo y ruta efectivos
gentle-shell home linkGuarda link como elección por defecto
gentle-shell setupProvisiona complementos del home seleccionado
gentle-shell setup --dry-runSimula provisionado del home seleccionado
gentle-shell listLista paquetes Pi del home efectivo
gentle-shell install npm:paqueteInstala paquete Pi en ese home
gentle-shell updateActualiza paquetes de Pi en ese home, no necesariamente launcher
gentle-shell upgradeActualiza Gentle Shell según canal release/main
gentle-shell --mode rpcPasa a Pi el modo RPC cuando el runtime lo soporte

La ubicación del flag importa: gentle-shell --link install npm:pi-web-access opera sobre Pi enlazado. No instales complementos en el home equivocado por confundir --link.

Comandos dentro de la sesión (TUI)

ComandoUso
/gentle:customizeEstilo, panel, UI y opciones sesión
/gentle:modelsAsignación de modelos/roles según integración
/gentle:profilesPerfiles de routing por agente
/gentle:statsHistorial local de uso/coste
/gentle:statusInformación de estado/diagnóstico
/gentle:doctorDiagnóstico de configuración/runtime
/gentle:yoloMenú de permisos rápidos de la sesión
/gentle:yolo statusConsulta si YOLO está habilitado
/gentle:yolo enableAutoriza acciones ordinarias acotadas, no destructivas
/gentle:yolo disableRevoca permisos de YOLO

Si algún comando no aparece en tu build, verifica con la paleta Alt+K, release y documentación. No se deben presuponer todos los subcomandos de main en releases antiguas.

12. Perfiles de modelos por rol

Puedes combinar modelos económicos para exploración y modelos más fuertes para decisiones complejas. Gentle Shell admite perfiles nombrados y asignación independiente por rol, con posible pin por repositorio.

Ideas de perfiles (ejemplo conceptual, no configuración oficial lista para pegar):

  • fast: orquestador modelo ágil, investigador económico, checks focalizados.
  • deep-work: orquestador y revisor de mayor capacidad; subagentes limitados a lo justificable.
  • offline: cuando el proveedor/modelo y herramientas sean realmente compatibles con ejecución local.

La referencia documenta perfiles en ~/.pi/gentle-ai/profiles.json y dos tipos de pin:

  • Local del clone Git: <git-common-dir>/gentle-ai/profile-pin.json, sin versionar.
  • Declaración de repo: <worktree-root>/.pi/gentle-ai/profile.json, normal y versionable.

El panel /gentle:profiles es preferible a editar a mano el JSON. Anclar un perfil impide que un cambio global de modelos altere inadvertidamente el siguiente subagente en un repositorio dado.

Autentica el proveedor en Pi y selecciona modelos disponibles para tu cuenta.

13. Memoria y complementos recomendados

¿Hay memoria por defecto?

ODD conserva artefactos en el repositorio. Engram añade memoria persistente como integración complementaria; setup puede provisionarla según la versión de gentle-ai fijada. Comprueba los paquetes instalados antes de depender de esa memoria.

Para inspeccionar paquetes existentes:

gentle-shell list

Compañeros citados por documentación técnica (la lista exacta puede variar por release):

# Ejemplos; instala solo si NO están ya provisionados:
gentle-shell install npm:gentle-engram
gentle-shell install npm:pi-web-access
gentle-shell install npm:pi-intercom
gentle-shell install npm:pi-lens

El setup moderno puede instalar otros módulos como pi-mcp-adapter o pi-btw, y eliminar automáticamente alguno incompatible con su tool nativo. Por ello, antes de tocar nada ejecuta gentle-shell list y evita reinstalar paquetes conflictivos que el propio setup retira.

Qué guardar

  • Configuración/homes si quieres continuidad entre equipos.
  • Artefactos ODD versionados en proyecto, especialmente odd/tasks/*.md.
  • Memoria/DB de Engram si estás usando ese companion; sigue su backup oficial.
  • Historial de chats si lo necesitas, conforme a tus políticas de privacidad.
  • Secrets y tokens por separado con gestor de credenciales.

No subas ~/.pi/agent, ~/.gentle-shell/agent o bases de memoria enteras a un repo público.

14. Seguridad: qué protecciones existen y cuáles no

Guardas y confirmaciones

La herramienta documenta guardas de operaciones destructivas (por ejemplo, reescrituras peligrosas, cambios fuera de scope), revisión y decisiones de usuario. Puede cambiar según versión/configuración. No debes confiar exclusivamente en el texto de la política del agente para proteger archivos críticos.

El modo YOLO

/gentle:yolo enable permite evitar preguntas repetidas para trabajo ordinario ya acotado en la sesión interactiva. Según README, quedan controles destructivos, confirmaciones obligatorias, decisiones de credenciales/destino, límites de sesión y límites a subagentes. Por defecto está OFF; se resetea con reload/sustitución de sesión.

Revisa el alcance y prepara rama y backup antes de habilitarlo. YOLO conserva los permisos del usuario del sistema; no proporciona aislamiento del proceso.

Endurecimiento sugerido

  • Usa un usuario Linux/macOS sin privilegios para trabajos no confiables.
  • Para repos externos sospechosos, ejecuta Pi/Gentle Shell en un devcontainer/VM con permisos limitados; esto es propuesta adicional, no característica inherente de Gentle Shell.
  • Mantén secrets de producción fuera del clone y fuera de los permisos del runner.
  • No abras --mode rpc en TCP público; verifica autenticación/transportes del host que lo exponga.
  • Delega solo a subagentes con scope explícito; no actives push/despliegue automáticos.
  • Protege main con branch protection y CI en plataforma Git.
  • Revisa scripts postinstall/paquetes npm antes de actualizar.
  • No confíes ciegamente en documentación externa, issues o README que el modelo lea: son fuentes de prompt injection.

Telemetría

La referencia técnica contempla un comando interno /gentle:telemetry disable y variables como DO_NOT_TRACK=1 o GENTLE_AI_TELEMETRY=0 para deshabilitar telemetría asociada en determinados componentes. Si necesitas política sin telemetría, comprueba estado y exclusiones de la versión real que despliegues; no presupongas que esas variables controlan otros paquetes de terceros o llamadas a modelos.

15. Operación, actualización y recuperación

Inspección básica

node --version
npm --version
gentle-shell --version
gentle-shell home
gentle-shell list
# Verifica repo activo:
git status --short

Dentro de la TUI ejecuta /gentle:doctor y /gentle:status cuando estén disponibles en tu versión.

Diferencia fundamental: update vs upgrade

# Actualiza los paquetes Pi instalados en el home seleccionado:
gentle-shell update

# Actualiza el launcher Gentle Shell en su canal actual:
gentle-shell upgrade

# Cambia/selecciona release si fue configurado canal de desarrollo:
gentle-shell upgrade --channel release

La referencia contempla canal release y canal main. El segundo puede compilar componentes de desarrollo y requerir Go/pnpm; para entorno estable y reproducible, empieza por release y fija versión/commit a nivel de instalación cuando sea posible.

Backup (propuesta operativa)

  1. Termina sesiones activas y deja el repositorio en estado Git conocido.
  2. Guarda configuración de ~/.gentle-shell/, ~/.pi/agent/ solo si corresponde, ~/.pi/gentle-ai/ y DB de Engram si se usa.
  3. Aplica cifrado y evita difundir tokens/model credentials.
  4. Conserva lockfiles, versión de Node, versión de Pi y de gentle-pi.
  5. En proyectos, conserva el trabajo por Git, no solo mediante backup del home.

Problemas frecuentes

SíntomaSolución de investigación
gentle-shell: command not foundnpm global bin PATH, versión de Node/npm, instalación global efectiva
No encuentra PiGENTLE_SHELL_PI, paquete Pi adjunto o pi en PATH; versión >=0.99.1
Credenciales no aparecen¿home isolated o link? autentica en el home correcto
Duplicated tool ask_user_questiondos extensiones instaladas; evita duplicar gentle-pi o paquete de pregunta retirado
setup fallarevisa dependencia/binario local Gentle AI, versión y mensajes de error; usa setup --dry-run
No hay memoria entre sesionescomprobar gentle-engram, inicialización, archivo ODD y home
No aparecen Changescambios realizados externamente/shell; usar git diff para verdad del repositorio
Los subagentes gastan demasiadoreducir fan-out, ajustar perfiles y roles, acotar scope
Panel se ve raro en terminalanchura TUI, terminal compatible, /gentle:customize
YOLO sigue pidiendo confirmaciónacciones destructivas/ambiguas mantienen consentimiento, esto es esperado

16. Ejemplo práctico: flujo seguro en repo Python/TypeScript

  1. Prepara un proyecto de ejemplo e instala dependencias siguiendo sus scripts auditados.

  2. Crea una rama:

    git switch -c feat/validacion-sesiones
    
  3. Ejecuta Gentle Shell:

    gentle-shell
    
  4. Primera petición: «Explora cómo se validan las sesiones y propón pruebas de expiración sin editar».

  5. Segunda petición: «Implementa solo el caso validado y ejecuta tests focalizados».

  6. Abre Alt+G, revisa cambios; revisa también git diff y tests externos.

  7. Si el trabajo crece, pide una feature ODD recuperable con criterios de aceptación explícitos.

  8. Si conviene, permite un subagente para tests/documentación en scope independiente; verifica integración.

  9. Antes del commit, comprueba que no se han añadido secretos ni artefactos temporales:

    git status --short
    git diff --check
    git diff --stat
    git diff
    
  10. Revisión humana y, si corresponde, CI antes de merge.

17. Uso remoto

Puede ejecutarse por SSH en una máquina de desarrollo con Node, Pi, Git y autenticación del proveedor. Utiliza un usuario con acceso limitado al repositorio. Para integrar tareas con otros servicios, emplea tickets o PRs y permisos acotados.

18. Validación de la instalación

  • Comprueba versión, home efectivo, proveedor y paquetes instalados.
  • Ejecuta una inspección y un cambio pequeño; contrasta Gentle Changes con git diff y tests.
  • Verifica continuidad ODD, memoria y permisos según las funciones que utilices.
  • Ensaya actualización y recuperación con configuración respaldada y credenciales protegidas.

19. Referencias oficiales

  1. README Gentle Shell
  2. Referencia técnica extensa
  3. Documentación del workspace
  4. Releases/changelog
  5. Sitio Gentle AI
Ficheros y descargas

Gentle Shell — instalación y trabajo con agentes

Revisado: 10/10/2026
Repositorio: https://github.com/Gentleman-Programming/gentle-shell
Referencia técnica: https://github.com/Gentleman-Programming/gentle-shell/blob/main/docs/readme-reference.md
Lanzador: gentle-shell; paquete npm: gentle-pi.

Compatibilidad: documentación revisada el 10/10/2026, con gentle-pi v3.5.1 como referencia publicada. Comprueba gentle-shell --version y las releases: main puede incluir funciones posteriores.

1. Funciones

Gentle Shell es un harness de programación para Pi. Organiza exploración, implementación, delegación a subagentes y revisión de cambios en un repositorio. Su metodología Organic Driven Development (ODD) mantiene el alcance y la continuidad de tareas largas mediante artefactos de trabajo y evidencias.

Qué aporta sobre Pi

  • Lanzador standalone que abre Pi con paquetes/skills/tema y home separado.
  • Interfaz TUI/fullscreen de estado: modelo, uso, costes disponibles, cambios, TODO y agentes.
  • ODD: explorar antes de cambiar, no sobrerregular tareas pequeñas, un documento persistente para tareas grandes.
  • Subagentes especializados: explorar, implementar, comprobar, revisar, con resultado que vuelve al padre.
  • Gentle Changes: diffs y rastreo de escrituras atribuidas a esta sesión y sus subagentes.
  • Herramientas nativas de revisión, decisiones y preguntas.
  • Perfiles por modelo/esfuerzo/rol, y pin por repositorio.
  • Guardas de operaciones destructivas; modo YOLO de sesión con límites.
  • Skills y paquetes complementarios: gentle-engram, MCP, acceso web, etc.

2. Ecosistema y nomenclatura

               usuario en terminal
                      |
                  gentle-shell
                      |
       lanza Pi + paquete gentle-pi
                      |
     ODD / prompts / skills / revisiones
            |                  |
       padre/orquestador    subagentes
            |                  |
       checkout Git / cambios / tests
                      |
       opcional: Engram / MCP / web
  • Pi: el agente/CLI de programación sobre el que corre.
  • gentle-pi: paquete npm con extensiones, skills, prompts, themes, configuraciones y bin gentle-shell.
  • Gentle Shell: lanzador y experiencia TUI del paquete gentle-pi.
  • Gentle AI: software compañero y política/metodología; existen comandos gentle-ai, y el paquete puede provisionar activos a través de su binario fijado.
  • Gentle Dot: aplicación de escritorio independiente.
  • Gentle Engram: integración complementaria de memoria persistente.

3. Requisitos

Confirmados en documentación

  • Runtime Node.js y npm para npm i -g gentle-pi.
  • Un Pi disponible por alguno de los mecanismos del launcher: ejecutable especificado con GENTLE_SHELL_PI, Pi opcional incluido adyacente, o pi del PATH.
  • El launcher requiere Pi >= 0.99.1, según la referencia técnica revisada.
  • Un proveedor de LLM/modelo aceptado por Pi y autenticación correctamente configurada.
  • Git y un repositorio real para aprovechar ODD, diffs, ramas y review.
  • Terminal capaz de ejecutar aplicaciones TUI; para panel lateral fullscreen es más cómodo uno ancho.

El instalador gráfico puede gestionar Node, pnpm y Pi. Para la ruta npm, utiliza una versión de Node LTS compatible con los requisitos del paquete instalado.

Recursos y coste

Dimensiona CPU y RAM según el proyecto y las herramientas ejecutadas. El consumo del proveedor depende de modelos, turnos y subagentes simultáneos; limita concurrencia y presupuesto por tarea.

4. Instalación recomendada: standalone aislado

Ruta documentada como principal:

npm i -g gentle-pi
# Verifica qué se instaló
gentle-shell --version
# Comienza en su propio home
gentle-shell

Dónde guarda su estado

  • Home standalone por defecto: ~/.gentle-shell/agent.
  • Configuración de preferencia de home: ~/.gentle-shell/config.json.
  • Home de Pi habitual: ~/.pi/agent.
  • Configuración interna de Gentle AI: normalmente ~/.pi/gentle-ai para parte de perfiles/opciones globales; la ruta efectiva puede variar con variables/config.
  • El launcher puede crear en su primer arranque configuración visual y ejecutar autoprovisionado de complementos de Gentle AI en su propio home aislado.

Importante: “home aislado” significa directorio de configuración distinto, no contenedor Docker ni aislamiento del sistema operativo. El proceso Pi puede seguir leyendo/escribiendo archivos a los que tenga permiso Unix.

Primera ejecución

En el standalone actual, la primera ejecución configura el home aislado y puede realizar setup automáticamente. Para repetir aprovisionamiento y ver su salida:

gentle-shell setup

Para inspeccionar la versión y home:

gentle-shell --version
gentle-shell home

No necesitas llamar a gentle-shell install npm:gentle-pi en el home aislado: el launcher ya inyecta su propia copia de ese paquete. Instalar otra copia a mano puede originar conflictos de herramientas o drift de versión.

Inicio en un proyecto

cd /ruta/a/tu-repositorio
git status --short
gentle-shell

Comienza por una tarea read-only, por ejemplo: «Explora la arquitectura, señala riesgos y prepara un plan; no modifiques archivos». Después prueba un cambio pequeño con test y revisión.

5. Ruta alternativa: reutilizar un Pi ya configurado

# Si ya tienes ~/.pi/agent con login, modelos y chats:
gentle-shell --link

Este flag usa el home del Pi existente y reutiliza sesiones/credenciales/modelos. No se recomienda como primera prueba si tienes un Pi muy personalizado: comienza aislado para evitar colisiones de plugins.

Para hacer del modo link el comportamiento habitual:

gentle-shell home link
gentle-shell home

Para volver al modo aislado:

gentle-shell home isolated
gentle-shell home

Para un home arbitrario:

gentle-shell --home /ruta/a/otro/agent
gentle-shell home /ruta/a/otro/agent

La primera forma selecciona el home de esa invocación; la segunda persiste elección para próximas. Los flags --link, --isolated y --home son mutuamente excluyentes.

6. Instalar dentro de un Pi existente (sin launcher standalone)

La ruta B del README:

# Requiere que el comando 'pi' funcione antes:
pi install npm:[email protected]
# Reinicia Pi y ejecuta la sincronización indicada:
gentle-ai sync
# Abre Pi en el repositorio:
pi

El comando/versionado [email protected] es el ejemplo de stable documentado en la fecha de esta guía; consulta la release oficial antes de fijarlo para tu entorno. La ruta B modifica el home de Pi existente, a diferencia de la ruta standalone aislada. Registra o haz backup de ~/.pi/agent/settings.json y assets antes.

No mezcles ruta A y B indiscriminadamente. El launcher tiene lógica para evitar cargar dos extensiones con los mismos tools en algunos modos, pero sigue siendo más simple elegir una estrategia de instalación por home.

7. Alternativa gráfica/instalador de releases

El README también documenta descargas de instaladores para macOS, Windows y Linux. Son descargables desde las releases oficiales; comprueba checksums SHA-256 cuando existan. El instalador gráfico web/browser es descrito como preview y las ejecuciones limpias macOS/Windows aún estaban bajo comprobación en los textos revisados.

Si te interesa la opción desde código fuente:

git clone https://github.com/Gentleman-Programming/gentle-shell.git
cd gentle-shell
sh scripts/bootstrap.sh  # macOS/Linux; verificar script antes de ejecutar

El instalador puede descargar Node/pnpm temporalmente, y solicita confirmación del plan antes de instalar. No lo ejecutes con privilegios elevados sin motivo. En Windows sigue los .cmd oficiales y las rutas publicadas; no traslades literalmente el script Linux.

8. Organic Driven Development (ODD), paso a paso

ODD ajusta el esfuerzo y la trazabilidad al riesgo y a la continuidad de la tarea.

Ciclo documentado

  1. Autorizar: una petición de inspección se mantiene read-only salvo permiso de implementación.
  2. Explorar: revisar código, tests, documentación y convenciones antes de cambiar.
  3. Resolver incertidumbre: investigar o preguntar solo sobre decisiones materialmente abiertas.
  4. Clasificar: tarea pequeña si se entiende y puede reanudarse con el prompt + git diff; grande si eso no basta.
  5. Registrar trabajo grande: crear artefacto durable odd/tasks/<nombre>.md y, si Engram está operativo, espejo de memoria.
  6. Implementar por tareas: decidir el camino más seguro, aplicar tests según modo TDD, cerrar unidades con commits/evidencias cuando corresponda.
  7. Cerrar: resumen de resultado comprobado, tests pasados/fallidos, riesgos y próximos pasos.

La referencia indica que un umbral alrededor de 400 líneas de cambio es solo orientativo, no una prohibición ni un método para dividir artificialmente trabajo.

Ejemplo de trabajo acotado

Inspecciona la validación de sesiones y sus tests. Implementa el caso de expiración, ejecuta las pruebas relevantes y presenta el diff. Mantén fuera del alcance los contratos y servicios no afectados.

Para trabajos que abarcan varios servicios, utiliza un artefacto ODD con tareas y criterios de aceptación. Las operaciones sobre ramas protegidas, datos o producción siguen sujetas a los controles del repositorio.

9. Subagentes y orquestación

Gentle Shell incorpora agentes focalizados para explorar, implementar y comprobar; un padre/orquestador mantiene responsabilidad sobre alcance, decisiones y resumen. En la TUI se visualiza actividad, modelo, tokens, coste cuando esté disponible, historial e interrupciones.

  • Para qué delegar: tareas independientes, análisis paralelo o aislamiento de contexto.
  • Cuándo no: para cambiar tres líneas sencillas, donde la coordinación cuesta más que la ejecución.
  • Prevención de conflictos: define archivos/objetivos por worker, evita que dos escritores cambien la misma API sin coordinación, usa branches/worktrees cuando convenga.
  • Verificación: el padre integra resultados y ejecuta tests; no asumas que “worker finished” implica que todas sus modificaciones quedaron aprobadas.
  • Coste: cada subagente gasta sus propias llamadas; controla modelos y esfuerzo por rol.

Interfaz y atajos documentados

  • Alt+A: visor de agentes en vivo.
  • Alt+G: visor de Gentle Changes.
  • Alt+K: paleta de comandos.
  • /gentle:customize: personalización de layout y paneles.
  • /gentle:stats: estadísticas locales de uso, modelos y costes registrados.

Los atajos pueden depender del emulador de terminal y de cómo capture Alt/Option. Prueba en un terminal conocido antes de asumir que falló el plugin.

10. Gentle Changes y revisión nativa

Gentle Changes

Recoge escrituras/ediciones exitosas realizadas por las herramientas del agente y sus subagentes asociados a la sesión. Muestra archivos, líneas modificadas y diffs, con posibilidad de abrir archivos en editor.

Advertencia específica de la documentación: no registra necesariamente todos los cambios hechos por shell, procesos externos o ejecuciones fallidas. Por tanto ausencia de entrada en Changes ≠ repositorio limpio.

Antes de hacer commit verifica también:

git status --short
git diff --stat
git diff --check
git diff

Revisión nativa

Gentle Shell ofrece revisión del candidato acotado (work unit / PR slice) y reportes de riesgos con evidencia. La revisión no sustituye los tests, reglas de protección de rama ni aprobación de otra persona para cambios de alto impacto.

Recomendación de pipeline humano:

  1. git status antes; crea rama de feature.
  2. El agente explora y modifica.
  3. Tests unitarios/lint + tests de integración necesarios.
  4. Gentle Changes + revisión nativa.
  5. Revisión de git diff sin confiar solo en narrativas del agente.
  6. Commit/PR; CI y revisor humano si se requiere.

11. Comandos clave

Lanzador (terminal externo)

ComandoQué hace
gentle-shellAbre con home seleccionado, aislado por defecto
gentle-shell --versionMuestra versión Gentle Shell, Pi y home
gentle-shell --linkReutiliza home de Pi existente
gentle-shell --isolatedFuerza home standalone
gentle-shell --home /rutaHome personalizado para esa ejecución
gentle-shell homeMuestra modo y ruta efectivos
gentle-shell home linkGuarda link como elección por defecto
gentle-shell setupProvisiona complementos del home seleccionado
gentle-shell setup --dry-runSimula provisionado del home seleccionado
gentle-shell listLista paquetes Pi del home efectivo
gentle-shell install npm:paqueteInstala paquete Pi en ese home
gentle-shell updateActualiza paquetes de Pi en ese home, no necesariamente launcher
gentle-shell upgradeActualiza Gentle Shell según canal release/main
gentle-shell --mode rpcPasa a Pi el modo RPC cuando el runtime lo soporte

La ubicación del flag importa: gentle-shell --link install npm:pi-web-access opera sobre Pi enlazado. No instales complementos en el home equivocado por confundir --link.

Comandos dentro de la sesión (TUI)

ComandoUso
/gentle:customizeEstilo, panel, UI y opciones sesión
/gentle:modelsAsignación de modelos/roles según integración
/gentle:profilesPerfiles de routing por agente
/gentle:statsHistorial local de uso/coste
/gentle:statusInformación de estado/diagnóstico
/gentle:doctorDiagnóstico de configuración/runtime
/gentle:yoloMenú de permisos rápidos de la sesión
/gentle:yolo statusConsulta si YOLO está habilitado
/gentle:yolo enableAutoriza acciones ordinarias acotadas, no destructivas
/gentle:yolo disableRevoca permisos de YOLO

Si algún comando no aparece en tu build, verifica con la paleta Alt+K, release y documentación. No se deben presuponer todos los subcomandos de main en releases antiguas.

12. Perfiles de modelos por rol

Puedes combinar modelos económicos para exploración y modelos más fuertes para decisiones complejas. Gentle Shell admite perfiles nombrados y asignación independiente por rol, con posible pin por repositorio.

Ideas de perfiles (ejemplo conceptual, no configuración oficial lista para pegar):

  • fast: orquestador modelo ágil, investigador económico, checks focalizados.
  • deep-work: orquestador y revisor de mayor capacidad; subagentes limitados a lo justificable.
  • offline: cuando el proveedor/modelo y herramientas sean realmente compatibles con ejecución local.

La referencia documenta perfiles en ~/.pi/gentle-ai/profiles.json y dos tipos de pin:

  • Local del clone Git: <git-common-dir>/gentle-ai/profile-pin.json, sin versionar.
  • Declaración de repo: <worktree-root>/.pi/gentle-ai/profile.json, normal y versionable.

El panel /gentle:profiles es preferible a editar a mano el JSON. Anclar un perfil impide que un cambio global de modelos altere inadvertidamente el siguiente subagente en un repositorio dado.

Autentica el proveedor en Pi y selecciona modelos disponibles para tu cuenta.

13. Memoria y complementos recomendados

¿Hay memoria por defecto?

ODD conserva artefactos en el repositorio. Engram añade memoria persistente como integración complementaria; setup puede provisionarla según la versión de gentle-ai fijada. Comprueba los paquetes instalados antes de depender de esa memoria.

Para inspeccionar paquetes existentes:

gentle-shell list

Compañeros citados por documentación técnica (la lista exacta puede variar por release):

# Ejemplos; instala solo si NO están ya provisionados:
gentle-shell install npm:gentle-engram
gentle-shell install npm:pi-web-access
gentle-shell install npm:pi-intercom
gentle-shell install npm:pi-lens

El setup moderno puede instalar otros módulos como pi-mcp-adapter o pi-btw, y eliminar automáticamente alguno incompatible con su tool nativo. Por ello, antes de tocar nada ejecuta gentle-shell list y evita reinstalar paquetes conflictivos que el propio setup retira.

Qué guardar

  • Configuración/homes si quieres continuidad entre equipos.
  • Artefactos ODD versionados en proyecto, especialmente odd/tasks/*.md.
  • Memoria/DB de Engram si estás usando ese companion; sigue su backup oficial.
  • Historial de chats si lo necesitas, conforme a tus políticas de privacidad.
  • Secrets y tokens por separado con gestor de credenciales.

No subas ~/.pi/agent, ~/.gentle-shell/agent o bases de memoria enteras a un repo público.

14. Seguridad: qué protecciones existen y cuáles no

Guardas y confirmaciones

La herramienta documenta guardas de operaciones destructivas (por ejemplo, reescrituras peligrosas, cambios fuera de scope), revisión y decisiones de usuario. Puede cambiar según versión/configuración. No debes confiar exclusivamente en el texto de la política del agente para proteger archivos críticos.

El modo YOLO

/gentle:yolo enable permite evitar preguntas repetidas para trabajo ordinario ya acotado en la sesión interactiva. Según README, quedan controles destructivos, confirmaciones obligatorias, decisiones de credenciales/destino, límites de sesión y límites a subagentes. Por defecto está OFF; se resetea con reload/sustitución de sesión.

Revisa el alcance y prepara rama y backup antes de habilitarlo. YOLO conserva los permisos del usuario del sistema; no proporciona aislamiento del proceso.

Endurecimiento sugerido

  • Usa un usuario Linux/macOS sin privilegios para trabajos no confiables.
  • Para repos externos sospechosos, ejecuta Pi/Gentle Shell en un devcontainer/VM con permisos limitados; esto es propuesta adicional, no característica inherente de Gentle Shell.
  • Mantén secrets de producción fuera del clone y fuera de los permisos del runner.
  • No abras --mode rpc en TCP público; verifica autenticación/transportes del host que lo exponga.
  • Delega solo a subagentes con scope explícito; no actives push/despliegue automáticos.
  • Protege main con branch protection y CI en plataforma Git.
  • Revisa scripts postinstall/paquetes npm antes de actualizar.
  • No confíes ciegamente en documentación externa, issues o README que el modelo lea: son fuentes de prompt injection.

Telemetría

La referencia técnica contempla un comando interno /gentle:telemetry disable y variables como DO_NOT_TRACK=1 o GENTLE_AI_TELEMETRY=0 para deshabilitar telemetría asociada en determinados componentes. Si necesitas política sin telemetría, comprueba estado y exclusiones de la versión real que despliegues; no presupongas que esas variables controlan otros paquetes de terceros o llamadas a modelos.

15. Operación, actualización y recuperación

Inspección básica

node --version
npm --version
gentle-shell --version
gentle-shell home
gentle-shell list
# Verifica repo activo:
git status --short

Dentro de la TUI ejecuta /gentle:doctor y /gentle:status cuando estén disponibles en tu versión.

Diferencia fundamental: update vs upgrade

# Actualiza los paquetes Pi instalados en el home seleccionado:
gentle-shell update

# Actualiza el launcher Gentle Shell en su canal actual:
gentle-shell upgrade

# Cambia/selecciona release si fue configurado canal de desarrollo:
gentle-shell upgrade --channel release

La referencia contempla canal release y canal main. El segundo puede compilar componentes de desarrollo y requerir Go/pnpm; para entorno estable y reproducible, empieza por release y fija versión/commit a nivel de instalación cuando sea posible.

Backup (propuesta operativa)

  1. Termina sesiones activas y deja el repositorio en estado Git conocido.
  2. Guarda configuración de ~/.gentle-shell/, ~/.pi/agent/ solo si corresponde, ~/.pi/gentle-ai/ y DB de Engram si se usa.
  3. Aplica cifrado y evita difundir tokens/model credentials.
  4. Conserva lockfiles, versión de Node, versión de Pi y de gentle-pi.
  5. En proyectos, conserva el trabajo por Git, no solo mediante backup del home.

Problemas frecuentes

SíntomaSolución de investigación
gentle-shell: command not foundnpm global bin PATH, versión de Node/npm, instalación global efectiva
No encuentra PiGENTLE_SHELL_PI, paquete Pi adjunto o pi en PATH; versión >=0.99.1
Credenciales no aparecen¿home isolated o link? autentica en el home correcto
Duplicated tool ask_user_questiondos extensiones instaladas; evita duplicar gentle-pi o paquete de pregunta retirado
setup fallarevisa dependencia/binario local Gentle AI, versión y mensajes de error; usa setup --dry-run
No hay memoria entre sesionescomprobar gentle-engram, inicialización, archivo ODD y home
No aparecen Changescambios realizados externamente/shell; usar git diff para verdad del repositorio
Los subagentes gastan demasiadoreducir fan-out, ajustar perfiles y roles, acotar scope
Panel se ve raro en terminalanchura TUI, terminal compatible, /gentle:customize
YOLO sigue pidiendo confirmaciónacciones destructivas/ambiguas mantienen consentimiento, esto es esperado

16. Ejemplo práctico: flujo seguro en repo Python/TypeScript

  1. Prepara un proyecto de ejemplo e instala dependencias siguiendo sus scripts auditados.

  2. Crea una rama:

    git switch -c feat/validacion-sesiones
    
  3. Ejecuta Gentle Shell:

    gentle-shell
    
  4. Primera petición: «Explora cómo se validan las sesiones y propón pruebas de expiración sin editar».

  5. Segunda petición: «Implementa solo el caso validado y ejecuta tests focalizados».

  6. Abre Alt+G, revisa cambios; revisa también git diff y tests externos.

  7. Si el trabajo crece, pide una feature ODD recuperable con criterios de aceptación explícitos.

  8. Si conviene, permite un subagente para tests/documentación en scope independiente; verifica integración.

  9. Antes del commit, comprueba que no se han añadido secretos ni artefactos temporales:

    git status --short
    git diff --check
    git diff --stat
    git diff
    
  10. Revisión humana y, si corresponde, CI antes de merge.

17. Uso remoto

Puede ejecutarse por SSH en una máquina de desarrollo con Node, Pi, Git y autenticación del proveedor. Utiliza un usuario con acceso limitado al repositorio. Para integrar tareas con otros servicios, emplea tickets o PRs y permisos acotados.

18. Validación de la instalación

  • Comprueba versión, home efectivo, proveedor y paquetes instalados.
  • Ejecuta una inspección y un cambio pequeño; contrasta Gentle Changes con git diff y tests.
  • Verifica continuidad ODD, memoria y permisos según las funciones que utilices.
  • Ensaya actualización y recuperación con configuración respaldada y credenciales protegidas.

19. Referencias oficiales

  1. README Gentle Shell
  2. Referencia técnica extensa
  3. Documentación del workspace
  4. Releases/changelog
  5. Sitio Gentle AI

Versiones (1)

VersiónDescargas (semana)Descargas (total)Publicación
0.1.0latest

Primera versión publicada.

0114 de octubre de 2026