Gentle Shell
Pi-based programming environment with Organic Driven Development, subagents, change review and guards. Installation guide, profiles and working in repositories.
Related links
About
Gentle Shell — installation and working with agents
Reviewed: 10/10/2026
Repository: https://github.com/Gentleman-Programming/gentle-shell
Technical reference: https://github.com/Gentleman-Programming/gentle-shell/blob/main/docs/readme-reference.md
Launcher: gentle-shell; npm package: gentle-pi.
Compatibility: documentation reviewed on 10/10/2026, with
gentle-pi v3.5.1as the published reference. Checkgentle-shell --versionand the releases:mainmay include later features.
1. Features
Gentle Shell is a programming harness for Pi. It organizes exploration, implementation, delegation to subagents and review of changes in a repository. Its Organic Driven Development (ODD) methodology maintains scope and continuity of long tasks through work artifacts and evidence.
What it adds over Pi
- Standalone launcher that opens Pi with packages/skills/theme and a separate home.
- TUI/fullscreen status interface: model, usage, available costs, changes, TODO and agents.
- ODD: explore before changing, do not over-regulate small tasks, one persistent document for large tasks.
- Specialized subagents: explore, implement, check, review, with results returning to the parent.
- Gentle Changes: diffs and write tracking attributed to this session and its subagents.
- Native tools for review, decisions and questions.
- Profiles by model/effort/role, and per-repository pinning.
- Guards for destructive operations; session YOLO mode with limits.
- Complementary skills and packages:
gentle-engram, MCP, web access, etc.
2. Ecosystem and nomenclature
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: the programming agent/CLI it runs on.
- gentle-pi: npm package with extensions, skills, prompts, themes, configurations and the
gentle-shellbin. - Gentle Shell: launcher and TUI experience of the
gentle-pipackage. - Gentle AI: companion software and policy/methodology;
gentle-aicommands exist, and the package can provision assets through its pinned binary. - Gentle Dot: independent desktop application.
- Gentle Engram: complementary persistent memory integration.
3. Requirements
Confirmed in documentation
- Node.js and npm runtime for
npm i -g gentle-pi. - A Pi available through one of the launcher mechanisms: executable specified with
GENTLE_SHELL_PI, optional included Pi adjacent, orpifrom PATH. - The launcher requires Pi >= 0.99.1, according to the reviewed technical reference.
- An LLM/model provider accepted by Pi and authentication correctly configured.
- Git and a real repository to take advantage of ODD, diffs, branches and review.
- A terminal capable of running TUI applications; for the fullscreen side panel a wide one is more comfortable.
The graphical installer can manage Node, pnpm and Pi. For the npm route, use an LTS Node version compatible with the requirements of the installed package.
Resources and cost
Size CPU and RAM according to the project and the tools executed. Provider consumption depends on models, turns and simultaneous subagents; limit concurrency and budget per task.
4. Recommended installation: isolated standalone
Documented as the main route:
npm i -g gentle-pi
# Verifica qué se instaló
gentle-shell --version
# Comienza en su propio home
gentle-shell
Where it stores its state
- Default standalone home:
~/.gentle-shell/agent. - Home preference configuration:
~/.gentle-shell/config.json. - Usual Pi home:
~/.pi/agent. - Gentle AI internal configuration: normally
~/.pi/gentle-aifor part of global profiles/options; the effective path may vary with variables/config. - The launcher can create visual configuration on its first start and run self-provisioning of Gentle AI add-ons in its own isolated home.
Important: "isolated home" means a different configuration directory, not a Docker container or operating system isolation. The Pi process may still read/write files it has Unix permission for.### First run
In the current standalone, the first run configures the isolated home and can perform setup automatically. To repeat provisioning and see its output:
gentle-shell setup
To inspect the version and home:
gentle-shell --version
gentle-shell home
You do not need to call gentle-shell install npm:gentle-pi in the isolated home: the launcher already injects its own copy of that package. Installing another copy by hand can cause tool conflicts or version drift.
Starting in a project
cd /ruta/a/tu-repositorio
git status --short
gentle-shell
Start with a read-only task, for example: "Explore the architecture, point out risks and prepare a plan; do not modify files." Then try a small change with tests and review.
5. Alternative path: reuse an already configured Pi
# Si ya tienes ~/.pi/agent con login, modelos y chats:
gentle-shell --link
This flag uses the existing Pi home and reuses sessions/credentials/models. It is not recommended as a first test if you have a highly customized Pi: start isolated to avoid plugin collisions.
To make link mode the usual behavior:
gentle-shell home link
gentle-shell home
To return to isolated mode:
gentle-shell home isolated
gentle-shell home
For an arbitrary home:
gentle-shell --home /ruta/a/otro/agent
gentle-shell home /ruta/a/otro/agent
The first form selects the home for that invocation; the second persists the choice for future ones. The --link, --isolated and --home flags are mutually exclusive.
6. Install inside an existing Pi (without the standalone launcher)
Path B of the 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
The [email protected] command/versioning is the documented stable example as of the date of this guide; check the official release before pinning it for your environment. Path B modifies the existing Pi home, unlike the isolated standalone path. Record or back up ~/.pi/agent/settings.json and assets beforehand.
Do not mix paths A and B indiscriminately. The launcher has logic to avoid loading two extensions with the same tools in some modes, but it is still simpler to choose one installation strategy per home.
7. Graphical alternative/release installer
The README also documents installer downloads for macOS, Windows and Linux. They are downloadable from the official releases; check SHA-256 checksums where they exist. The web/browser graphical installer is described as preview and clean macOS/Windows runs were still under verification in the reviewed texts.
If you are interested in the option from source code:
git clone https://github.com/Gentleman-Programming/gentle-shell.git
cd gentle-shell
sh scripts/bootstrap.sh # macOS/Linux; verificar script antes de ejecutar
The installer may download Node/pnpm temporarily, and it requests confirmation of the plan before installing. Do not run it with elevated privileges without reason. On Windows, follow the official .cmd and the published paths; do not literally transplant the Linux script.
8. Organic Driven Development (ODD), step by step
ODD adjusts effort and traceability to the risk and continuity of the task.
Documented cycle
- Authorize: an inspection request remains read-only unless implementation permission is granted.
- Explore: review code, tests, documentation and conventions before changing.
- Resolve uncertainty: investigate or ask only about materially open decisions.
- Classify: small task if it is understood and can be resumed with the prompt +
git diff; large if that is not enough. - Record large work: create a durable
odd/tasks/<nombre>.mdartifact and, if Engram is operational, a memory mirror. - Implement by tasks: decide the safest path, apply tests according to TDD mode, close units with commits/evidence where appropriate.
- Close: summary of verified result, tests passed/failed, risks and next steps.
The reference indicates that a threshold of around 400 lines of change is only guidance, not a prohibition nor a method for artificially splitting work.
Example of scoped work> Inspect session validation and its tests. Implement the expiration case, run the relevant tests, and present the diff. Keep unaffected contracts and services out of scope.
For work spanning multiple services, use an ODD artifact with tasks and acceptance criteria. Operations on protected branches, data, or production remain subject to the repository's controls.
9. Subagents and orchestration
Gentle Shell incorporates focused agents to explore, implement, and verify; a parent/orchestrator maintains responsibility for scope, decisions, and summary. The TUI displays activity, model, tokens, cost when available, history, and interruptions.
- When to delegate: independent tasks, parallel analysis, or context isolation.
- When not to: to change three simple lines, where coordination costs more than execution.
- Conflict prevention: define files/targets per worker, prevent two writers from changing the same API without coordination, use branches/worktrees when appropriate.
- Verification: the parent integrates results and runs tests; do not assume that "worker finished" implies that all its modifications were approved.
- Cost: each subagent spends its own calls; control models and effort per role.
Interface and documented shortcuts
Alt+A: live agent viewer.Alt+G: Gentle Changes viewer.Alt+K: command palette./gentle:customize: layout and panel customization./gentle:stats: local usage, model, and recorded cost statistics.
Shortcuts may depend on the terminal emulator and how it captures Alt/Option. Test in a known terminal before assuming the plugin failed.
10. Gentle Changes and native review
Gentle Changes
Collects successful writes/edits made by the agent's tools and its subagents associated with the session. Shows files, modified lines, and diffs, with the option to open files in an editor.
Documentation-specific warning: it does not necessarily record all changes made by shell, external processes, or failed executions. Therefore absence of an entry in Changes ≠ clean repository.
Before committing, also verify:
git status --short
git diff --stat
git diff --check
git diff
Native review
Gentle Shell offers review of the scoped candidate (work unit / PR slice) and risk reports with evidence. The review does not replace tests, branch protection rules, or approval by another person for high-impact changes.
Recommended human pipeline:
git statusbeforehand; create a feature branch.- The agent explores and modifies.
- Unit tests/lint + necessary integration tests.
- Gentle Changes + native review.
- Review of
git diffwithout relying solely on the agent's narratives. - Commit/PR; CI and human reviewer if required.
11. Key commands
Launcher (external terminal)
| Command | What it does |
|---|---|
gentle-shell | Opens with the selected home, isolated by default |
gentle-shell --version | Shows Gentle Shell, Pi, and home version |
gentle-shell --link | Reuses an existing Pi home |
gentle-shell --isolated | Forces standalone home |
gentle-shell --home /ruta | Custom home for that run |
gentle-shell home | Shows effective mode and path |
gentle-shell home link | Saves link as the default choice |
gentle-shell setup | Provisions add-ons for the selected home |
gentle-shell setup --dry-run | Simulates provisioning of the selected home |
gentle-shell list | Lists Pi packages of the effective home |
gentle-shell install npm:paquete | Installs a Pi package in that home |
gentle-shell update | Updates packages of Pi in that home, not necessarily the launcher |
gentle-shell upgrade | Updates Gentle Shell according to the release/main channel |
gentle-shell --mode rpc | Passes RPC mode to Pi when the runtime supports it |
The flag's location matters: gentle-shell --link install npm:pi-web-access operates on the linked Pi. Do not install add-ons in the wrong home by confusing --link.
Commands within the session (TUI)
| Command | Use |
|---|---|
/gentle:customize | Style, panel, UI, and session options |
/gentle:models | Model/role assignment according to integration |
/gentle:profiles | Routing profiles per agent |
/gentle:stats | Local usage/cost history |
/gentle:status | Status/diagnostic information |
/gentle:doctor | Configuration/runtime diagnostics |
/gentle:yolo | Session quick permissions menu |
/gentle:yolo status | Checks whether YOLO is enabled |
/gentle:yolo enable | Authorizes scoped, non-destructive ordinary actions |
/gentle:yolo disable | Revokes YOLO permissions |
12. Model profiles by role
You can combine economical models for exploration and stronger models for complex decisions. Gentle Shell supports named profiles and independent assignment by role, with possible pinning per repository.
Profile ideas (conceptual example, not official configuration ready to paste):
fast: agile model orchestrator, economical researcher, focused checks.deep-work: higher-capacity orchestrator and reviewer; subagents limited to what is justifiable.offline: when the provider/model and tools are truly compatible with local execution.
The reference documents profiles in ~/.pi/gentle-ai/profiles.json and two types of pin:
- Local to the Git clone:
<git-common-dir>/gentle-ai/profile-pin.json, unversioned. - Repo declaration:
<worktree-root>/.pi/gentle-ai/profile.json, normal and versionable.
The /gentle:profiles panel is preferable to editing the JSON by hand. Pinning a profile prevents a global model change from inadvertently altering the next subagent in a given repository.
Authenticate the provider in Pi and select models available for your account.
13. Memory and recommended add-ons
Is there memory by default?
ODD keeps artifacts in the repository. Engram adds persistent memory as a complementary integration; setup can provision it depending on the pinned gentle-ai version. Check the installed packages before relying on that memory.
To inspect existing packages:
gentle-shell list
Companions cited by technical documentation (the exact list may vary by 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
The modern setup can install other modules such as pi-mcp-adapter or pi-btw, and automatically remove any that are incompatible with its native tool. Therefore, before touching anything run gentle-shell list and avoid reinstalling conflicting packages that the setup itself removes.
What to save
- Configuration/homes if you want continuity between machines.
- ODD artifacts versioned in the project, especially
odd/tasks/*.md. - Engram memory/DB if you are using that companion; follow its official backup.
- Chat history if you need it, in accordance with your privacy policies.
- Secrets and tokens separately with a credentials manager.
Do not upload ~/.pi/agent, ~/.gentle-shell/agent, or entire memory databases to a public repo.
14. Security: what protections exist and what do not
Guards and confirmations
The tool documents guards for destructive operations (for example, dangerous rewrites, changes outside scope), review, and user decisions. It may change depending on version/configuration. You should not rely exclusively on the agent policy text to protect critical files.
YOLO mode
/gentle:yolo enable allows avoiding repeated questions for ordinary work already scoped in the interactive session. According to the README, destructive controls, mandatory confirmations, credential/destination decisions, session limits, and limits on subagents remain. It is OFF by default; it resets with reload/session replacement.
Review the scope and prepare a branch and backup before enabling it. YOLO preserves the system user's permissions; it does not provide process isolation.
Suggested hardening
- Use an unprivileged Linux/macOS user for untrusted work.
- For suspicious external repos, run Pi/Gentle Shell in a devcontainer/VM with limited permissions; this is an additional proposal, not an inherent feature of Gentle Shell.
- Keep production secrets outside the clone and outside the runner's permissions.
- Do not open
--mode rpcon public TCP; verify the authentication/transports of the host exposing it. - Delegate only to subagents with explicit scope; do not enable automatic push/deployment.
- Protect
mainwith branch protection and CI on the Git platform. - Review
postinstallscripts/npm packages before updating. - Do not blindly trust external documentation, issues, or READMEs that the model reads: they are sources of prompt injection.### Telemetry
The technical reference covers an internal command /gentle:telemetry disable and variables such as DO_NOT_TRACK=1 or GENTLE_AI_TELEMETRY=0 to disable associated telemetry in certain components. If you need a policy without telemetry, check the status and exclusions of the actual version you deploy; do not assume that these variables control other third-party packages or model calls.
15. Operation, upgrade, and recovery
Basic inspection
node --version
npm --version
gentle-shell --version
gentle-shell home
gentle-shell list
# Verifica repo activo:
git status --short
Inside the TUI, run /gentle:doctor and /gentle:status when they are available in your version.
Key difference: 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
The reference covers the release channel and the main channel. The latter may compile development components and require Go/pnpm; for a stable and reproducible environment, start with release and pin the version/commit at the installation level when possible.
Backup (operational proposal)
- End active sessions and leave the repository in a known Git state.
- Save the configuration of
~/.gentle-shell/,~/.pi/agent/only if applicable,~/.pi/gentle-ai/, and the Engram DB if used. - Apply encryption and avoid distributing tokens/model credentials.
- Keep lockfiles, the Node version, the Pi version, and the
gentle-piversion. - In projects, keep work via Git, not only via a home backup.
Common issues
| Symptom | Investigation solution |
|---|---|
gentle-shell: command not found | npm global bin PATH, Node/npm version, effective global installation |
| Cannot find Pi | GENTLE_SHELL_PI, bundled Pi package, or pi in PATH; version >=0.99.1 |
| Credentials do not appear | isolated home or link? authenticate in the correct home |
Duplicated tool ask_user_question | two extensions installed; avoid duplicating gentle-pi or the retired question package |
setup fails | check the local Gentle AI dependency/binary, version, and error messages; use setup --dry-run |
| No memory between sessions | check gentle-engram, initialization, ODD file, and home |
| Changes do not appear | changes made externally/shell; use git diff for repository truth |
| Subagents use too much | reduce fan-out, adjust profiles and roles, narrow scope |
| Panel looks odd in the terminal | TUI width, compatible terminal, /gentle:customize |
| YOLO still asks for confirmation | destructive/ambiguous actions retain consent, this is expected |
16. Practical example: safe workflow in a Python/TypeScript repo
-
Prepare a sample project and install dependencies following its audited scripts.
-
Create a branch:
git switch -c feat/validacion-sesiones -
Run Gentle Shell:
gentle-shell -
First request: "Explore how sessions are validated and propose expiration tests without editing."
-
Second request: "Implement only the validated case and run focused tests."
-
Open
Alt+G, review changes; also reviewgit diffand external tests. -
If the work grows, request a recoverable ODD feature with explicit acceptance criteria.
-
If appropriate, allow a subagent for tests/documentation in an independent scope; verify integration.
-
Before committing, check that no secrets or temporary artifacts have been added:
git status --short git diff --check git diff --stat git diff -
Human review and, if applicable, CI before merge.
17. Remote use
It can be run over SSH on a development machine with Node, Pi, Git, and provider authentication. Use a user with limited access to the repository. To integrate tasks with other services, use tickets or PRs and scoped permissions.
18. Installation validation
- Check the version, effective home, provider, and installed packages.
- Run an inspection and a small change; compare Gentle Changes with
git diffand tests. - Verify ODD continuity, memory, and permissions according to the features you use.
- Rehearse upgrade and recovery with backed-up configuration and protected credentials.## 19. Official references
Files & downloads
Gentle Shell — installation and working with agents
Reviewed: 10/10/2026
Repository: https://github.com/Gentleman-Programming/gentle-shell
Technical reference: https://github.com/Gentleman-Programming/gentle-shell/blob/main/docs/readme-reference.md
Launcher: gentle-shell; npm package: gentle-pi.
Compatibility: documentation reviewed on 10/10/2026, with
gentle-pi v3.5.1as the published reference. Checkgentle-shell --versionand the releases:mainmay include later features.
1. Features
Gentle Shell is a programming harness for Pi. It organizes exploration, implementation, delegation to subagents and review of changes in a repository. Its Organic Driven Development (ODD) methodology maintains scope and continuity of long tasks through work artifacts and evidence.
What it adds over Pi
- Standalone launcher that opens Pi with packages/skills/theme and a separate home.
- TUI/fullscreen status interface: model, usage, available costs, changes, TODO and agents.
- ODD: explore before changing, do not over-regulate small tasks, one persistent document for large tasks.
- Specialized subagents: explore, implement, check, review, with results returning to the parent.
- Gentle Changes: diffs and write tracking attributed to this session and its subagents.
- Native tools for review, decisions and questions.
- Profiles by model/effort/role, and per-repository pinning.
- Guards for destructive operations; session YOLO mode with limits.
- Complementary skills and packages:
gentle-engram, MCP, web access, etc.
2. Ecosystem and nomenclature
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: the programming agent/CLI it runs on.
- gentle-pi: npm package with extensions, skills, prompts, themes, configurations and the
gentle-shellbin. - Gentle Shell: launcher and TUI experience of the
gentle-pipackage. - Gentle AI: companion software and policy/methodology;
gentle-aicommands exist, and the package can provision assets through its pinned binary. - Gentle Dot: independent desktop application.
- Gentle Engram: complementary persistent memory integration.
3. Requirements
Confirmed in documentation
- Node.js and npm runtime for
npm i -g gentle-pi. - A Pi available through one of the launcher mechanisms: executable specified with
GENTLE_SHELL_PI, optional included Pi adjacent, orpifrom PATH. - The launcher requires Pi >= 0.99.1, according to the reviewed technical reference.
- An LLM/model provider accepted by Pi and authentication correctly configured.
- Git and a real repository to take advantage of ODD, diffs, branches and review.
- A terminal capable of running TUI applications; for the fullscreen side panel a wide one is more comfortable.
The graphical installer can manage Node, pnpm and Pi. For the npm route, use an LTS Node version compatible with the requirements of the installed package.
Resources and cost
Size CPU and RAM according to the project and the tools executed. Provider consumption depends on models, turns and simultaneous subagents; limit concurrency and budget per task.
4. Recommended installation: isolated standalone
Documented as the main route:
npm i -g gentle-pi
# Verifica qué se instaló
gentle-shell --version
# Comienza en su propio home
gentle-shell
Where it stores its state
- Default standalone home:
~/.gentle-shell/agent. - Home preference configuration:
~/.gentle-shell/config.json. - Usual Pi home:
~/.pi/agent. - Gentle AI internal configuration: normally
~/.pi/gentle-aifor part of global profiles/options; the effective path may vary with variables/config. - The launcher can create visual configuration on its first start and run self-provisioning of Gentle AI add-ons in its own isolated home.
Important: "isolated home" means a different configuration directory, not a Docker container or operating system isolation. The Pi process may still read/write files it has Unix permission for.### First run
In the current standalone, the first run configures the isolated home and can perform setup automatically. To repeat provisioning and see its output:
gentle-shell setup
To inspect the version and home:
gentle-shell --version
gentle-shell home
You do not need to call gentle-shell install npm:gentle-pi in the isolated home: the launcher already injects its own copy of that package. Installing another copy by hand can cause tool conflicts or version drift.
Starting in a project
cd /ruta/a/tu-repositorio
git status --short
gentle-shell
Start with a read-only task, for example: "Explore the architecture, point out risks and prepare a plan; do not modify files." Then try a small change with tests and review.
5. Alternative path: reuse an already configured Pi
# Si ya tienes ~/.pi/agent con login, modelos y chats:
gentle-shell --link
This flag uses the existing Pi home and reuses sessions/credentials/models. It is not recommended as a first test if you have a highly customized Pi: start isolated to avoid plugin collisions.
To make link mode the usual behavior:
gentle-shell home link
gentle-shell home
To return to isolated mode:
gentle-shell home isolated
gentle-shell home
For an arbitrary home:
gentle-shell --home /ruta/a/otro/agent
gentle-shell home /ruta/a/otro/agent
The first form selects the home for that invocation; the second persists the choice for future ones. The --link, --isolated and --home flags are mutually exclusive.
6. Install inside an existing Pi (without the standalone launcher)
Path B of the 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
The [email protected] command/versioning is the documented stable example as of the date of this guide; check the official release before pinning it for your environment. Path B modifies the existing Pi home, unlike the isolated standalone path. Record or back up ~/.pi/agent/settings.json and assets beforehand.
Do not mix paths A and B indiscriminately. The launcher has logic to avoid loading two extensions with the same tools in some modes, but it is still simpler to choose one installation strategy per home.
7. Graphical alternative/release installer
The README also documents installer downloads for macOS, Windows and Linux. They are downloadable from the official releases; check SHA-256 checksums where they exist. The web/browser graphical installer is described as preview and clean macOS/Windows runs were still under verification in the reviewed texts.
If you are interested in the option from source code:
git clone https://github.com/Gentleman-Programming/gentle-shell.git
cd gentle-shell
sh scripts/bootstrap.sh # macOS/Linux; verificar script antes de ejecutar
The installer may download Node/pnpm temporarily, and it requests confirmation of the plan before installing. Do not run it with elevated privileges without reason. On Windows, follow the official .cmd and the published paths; do not literally transplant the Linux script.
8. Organic Driven Development (ODD), step by step
ODD adjusts effort and traceability to the risk and continuity of the task.
Documented cycle
- Authorize: an inspection request remains read-only unless implementation permission is granted.
- Explore: review code, tests, documentation and conventions before changing.
- Resolve uncertainty: investigate or ask only about materially open decisions.
- Classify: small task if it is understood and can be resumed with the prompt +
git diff; large if that is not enough. - Record large work: create a durable
odd/tasks/<nombre>.mdartifact and, if Engram is operational, a memory mirror. - Implement by tasks: decide the safest path, apply tests according to TDD mode, close units with commits/evidence where appropriate.
- Close: summary of verified result, tests passed/failed, risks and next steps.
The reference indicates that a threshold of around 400 lines of change is only guidance, not a prohibition nor a method for artificially splitting work.
Example of scoped work> Inspect session validation and its tests. Implement the expiration case, run the relevant tests, and present the diff. Keep unaffected contracts and services out of scope.
For work spanning multiple services, use an ODD artifact with tasks and acceptance criteria. Operations on protected branches, data, or production remain subject to the repository's controls.
9. Subagents and orchestration
Gentle Shell incorporates focused agents to explore, implement, and verify; a parent/orchestrator maintains responsibility for scope, decisions, and summary. The TUI displays activity, model, tokens, cost when available, history, and interruptions.
- When to delegate: independent tasks, parallel analysis, or context isolation.
- When not to: to change three simple lines, where coordination costs more than execution.
- Conflict prevention: define files/targets per worker, prevent two writers from changing the same API without coordination, use branches/worktrees when appropriate.
- Verification: the parent integrates results and runs tests; do not assume that "worker finished" implies that all its modifications were approved.
- Cost: each subagent spends its own calls; control models and effort per role.
Interface and documented shortcuts
Alt+A: live agent viewer.Alt+G: Gentle Changes viewer.Alt+K: command palette./gentle:customize: layout and panel customization./gentle:stats: local usage, model, and recorded cost statistics.
Shortcuts may depend on the terminal emulator and how it captures Alt/Option. Test in a known terminal before assuming the plugin failed.
10. Gentle Changes and native review
Gentle Changes
Collects successful writes/edits made by the agent's tools and its subagents associated with the session. Shows files, modified lines, and diffs, with the option to open files in an editor.
Documentation-specific warning: it does not necessarily record all changes made by shell, external processes, or failed executions. Therefore absence of an entry in Changes ≠ clean repository.
Before committing, also verify:
git status --short
git diff --stat
git diff --check
git diff
Native review
Gentle Shell offers review of the scoped candidate (work unit / PR slice) and risk reports with evidence. The review does not replace tests, branch protection rules, or approval by another person for high-impact changes.
Recommended human pipeline:
git statusbeforehand; create a feature branch.- The agent explores and modifies.
- Unit tests/lint + necessary integration tests.
- Gentle Changes + native review.
- Review of
git diffwithout relying solely on the agent's narratives. - Commit/PR; CI and human reviewer if required.
11. Key commands
Launcher (external terminal)
| Command | What it does |
|---|---|
gentle-shell | Opens with the selected home, isolated by default |
gentle-shell --version | Shows Gentle Shell, Pi, and home version |
gentle-shell --link | Reuses an existing Pi home |
gentle-shell --isolated | Forces standalone home |
gentle-shell --home /ruta | Custom home for that run |
gentle-shell home | Shows effective mode and path |
gentle-shell home link | Saves link as the default choice |
gentle-shell setup | Provisions add-ons for the selected home |
gentle-shell setup --dry-run | Simulates provisioning of the selected home |
gentle-shell list | Lists Pi packages of the effective home |
gentle-shell install npm:paquete | Installs a Pi package in that home |
gentle-shell update | Updates packages of Pi in that home, not necessarily the launcher |
gentle-shell upgrade | Updates Gentle Shell according to the release/main channel |
gentle-shell --mode rpc | Passes RPC mode to Pi when the runtime supports it |
The flag's location matters: gentle-shell --link install npm:pi-web-access operates on the linked Pi. Do not install add-ons in the wrong home by confusing --link.
Commands within the session (TUI)
| Command | Use |
|---|---|
/gentle:customize | Style, panel, UI, and session options |
/gentle:models | Model/role assignment according to integration |
/gentle:profiles | Routing profiles per agent |
/gentle:stats | Local usage/cost history |
/gentle:status | Status/diagnostic information |
/gentle:doctor | Configuration/runtime diagnostics |
/gentle:yolo | Session quick permissions menu |
/gentle:yolo status | Checks whether YOLO is enabled |
/gentle:yolo enable | Authorizes scoped, non-destructive ordinary actions |
/gentle:yolo disable | Revokes YOLO permissions |
12. Model profiles by role
You can combine economical models for exploration and stronger models for complex decisions. Gentle Shell supports named profiles and independent assignment by role, with possible pinning per repository.
Profile ideas (conceptual example, not official configuration ready to paste):
fast: agile model orchestrator, economical researcher, focused checks.deep-work: higher-capacity orchestrator and reviewer; subagents limited to what is justifiable.offline: when the provider/model and tools are truly compatible with local execution.
The reference documents profiles in ~/.pi/gentle-ai/profiles.json and two types of pin:
- Local to the Git clone:
<git-common-dir>/gentle-ai/profile-pin.json, unversioned. - Repo declaration:
<worktree-root>/.pi/gentle-ai/profile.json, normal and versionable.
The /gentle:profiles panel is preferable to editing the JSON by hand. Pinning a profile prevents a global model change from inadvertently altering the next subagent in a given repository.
Authenticate the provider in Pi and select models available for your account.
13. Memory and recommended add-ons
Is there memory by default?
ODD keeps artifacts in the repository. Engram adds persistent memory as a complementary integration; setup can provision it depending on the pinned gentle-ai version. Check the installed packages before relying on that memory.
To inspect existing packages:
gentle-shell list
Companions cited by technical documentation (the exact list may vary by 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
The modern setup can install other modules such as pi-mcp-adapter or pi-btw, and automatically remove any that are incompatible with its native tool. Therefore, before touching anything run gentle-shell list and avoid reinstalling conflicting packages that the setup itself removes.
What to save
- Configuration/homes if you want continuity between machines.
- ODD artifacts versioned in the project, especially
odd/tasks/*.md. - Engram memory/DB if you are using that companion; follow its official backup.
- Chat history if you need it, in accordance with your privacy policies.
- Secrets and tokens separately with a credentials manager.
Do not upload ~/.pi/agent, ~/.gentle-shell/agent, or entire memory databases to a public repo.
14. Security: what protections exist and what do not
Guards and confirmations
The tool documents guards for destructive operations (for example, dangerous rewrites, changes outside scope), review, and user decisions. It may change depending on version/configuration. You should not rely exclusively on the agent policy text to protect critical files.
YOLO mode
/gentle:yolo enable allows avoiding repeated questions for ordinary work already scoped in the interactive session. According to the README, destructive controls, mandatory confirmations, credential/destination decisions, session limits, and limits on subagents remain. It is OFF by default; it resets with reload/session replacement.
Review the scope and prepare a branch and backup before enabling it. YOLO preserves the system user's permissions; it does not provide process isolation.
Suggested hardening
- Use an unprivileged Linux/macOS user for untrusted work.
- For suspicious external repos, run Pi/Gentle Shell in a devcontainer/VM with limited permissions; this is an additional proposal, not an inherent feature of Gentle Shell.
- Keep production secrets outside the clone and outside the runner's permissions.
- Do not open
--mode rpcon public TCP; verify the authentication/transports of the host exposing it. - Delegate only to subagents with explicit scope; do not enable automatic push/deployment.
- Protect
mainwith branch protection and CI on the Git platform. - Review
postinstallscripts/npm packages before updating. - Do not blindly trust external documentation, issues, or READMEs that the model reads: they are sources of prompt injection.### Telemetry
The technical reference covers an internal command /gentle:telemetry disable and variables such as DO_NOT_TRACK=1 or GENTLE_AI_TELEMETRY=0 to disable associated telemetry in certain components. If you need a policy without telemetry, check the status and exclusions of the actual version you deploy; do not assume that these variables control other third-party packages or model calls.
15. Operation, upgrade, and recovery
Basic inspection
node --version
npm --version
gentle-shell --version
gentle-shell home
gentle-shell list
# Verifica repo activo:
git status --short
Inside the TUI, run /gentle:doctor and /gentle:status when they are available in your version.
Key difference: 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
The reference covers the release channel and the main channel. The latter may compile development components and require Go/pnpm; for a stable and reproducible environment, start with release and pin the version/commit at the installation level when possible.
Backup (operational proposal)
- End active sessions and leave the repository in a known Git state.
- Save the configuration of
~/.gentle-shell/,~/.pi/agent/only if applicable,~/.pi/gentle-ai/, and the Engram DB if used. - Apply encryption and avoid distributing tokens/model credentials.
- Keep lockfiles, the Node version, the Pi version, and the
gentle-piversion. - In projects, keep work via Git, not only via a home backup.
Common issues
| Symptom | Investigation solution |
|---|---|
gentle-shell: command not found | npm global bin PATH, Node/npm version, effective global installation |
| Cannot find Pi | GENTLE_SHELL_PI, bundled Pi package, or pi in PATH; version >=0.99.1 |
| Credentials do not appear | isolated home or link? authenticate in the correct home |
Duplicated tool ask_user_question | two extensions installed; avoid duplicating gentle-pi or the retired question package |
setup fails | check the local Gentle AI dependency/binary, version, and error messages; use setup --dry-run |
| No memory between sessions | check gentle-engram, initialization, ODD file, and home |
| Changes do not appear | changes made externally/shell; use git diff for repository truth |
| Subagents use too much | reduce fan-out, adjust profiles and roles, narrow scope |
| Panel looks odd in the terminal | TUI width, compatible terminal, /gentle:customize |
| YOLO still asks for confirmation | destructive/ambiguous actions retain consent, this is expected |
16. Practical example: safe workflow in a Python/TypeScript repo
-
Prepare a sample project and install dependencies following its audited scripts.
-
Create a branch:
git switch -c feat/validacion-sesiones -
Run Gentle Shell:
gentle-shell -
First request: "Explore how sessions are validated and propose expiration tests without editing."
-
Second request: "Implement only the validated case and run focused tests."
-
Open
Alt+G, review changes; also reviewgit diffand external tests. -
If the work grows, request a recoverable ODD feature with explicit acceptance criteria.
-
If appropriate, allow a subagent for tests/documentation in an independent scope; verify integration.
-
Before committing, check that no secrets or temporary artifacts have been added:
git status --short git diff --check git diff --stat git diff -
Human review and, if applicable, CI before merge.
17. Remote use
It can be run over SSH on a development machine with Node, Pi, Git, and provider authentication. Use a user with limited access to the repository. To integrate tasks with other services, use tickets or PRs and scoped permissions.
18. Installation validation
- Check the version, effective home, provider, and installed packages.
- Run an inspection and a small change; compare Gentle Changes with
git diffand tests. - Verify ODD continuity, memory, and permissions according to the features you use.
- Rehearse upgrade and recovery with backed-up configuration and protected credentials.## 19. Official references
Versions (1)
| Version | Downloads (weekly) | Downloads (total) | Published |
|---|---|---|---|
0.1.0latest First published version. | 0 | 1 | October 14, 2026 |