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.1 as the published reference. Check gentle-shell --version and the releases: main may 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-shell bin.
• Gentle Shell: launcher and TUI experience of the gentle-pi package.
• Gentle AI: companion software and policy/methodology; gentle-ai commands 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, or pi from 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-ai for 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

1. Authorize: an inspection request remains read-only unless implementation permission is granted.
2. Explore: review code, tests, documentation and conventions before changing.
3. Resolve uncertainty: investigate or ask only about materially open decisions.
4. Classify: small task if it is understood and can be resumed with the prompt + git diff; large if that is not enough.
5. Record large work: create a durable odd/tasks/<nombre>.md artifact and, if Engram is operational, a memory mirror.
6. Implement by tasks: decide the safest path, apply tests according to TDD mode, close units with commits/evidence where appropriate.
7. 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:

1. git status beforehand; create a feature branch.
2. The agent explores and modifies.
3. Unit tests/lint + necessary integration tests.
4. Gentle Changes + native review.
5. Review of git diff without relying solely on the agent's narratives.
6. Commit/PR; CI and human reviewer if required.

11. Key commands

Launcher (external terminal)

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)

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 rpc on 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 main with branch protection and CI on the Git platform.
• Review postinstall scripts/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)

1. End active sessions and leave the repository in a known Git state.
2. Save the configuration of ~/.gentle-shell/, ~/.pi/agent/ only if applicable, ~/.pi/gentle-ai/, and the Engram DB if used.
3. Apply encryption and avoid distributing tokens/model credentials.
4. Keep lockfiles, the Node version, the Pi version, and the gentle-pi version.
5. In projects, keep work via Git, not only via a home backup.

Common issues

16. Practical example: safe workflow in a Python/TypeScript repo

1. Prepare a sample project and install dependencies following its audited scripts.

2. Create a branch:

   git switch -c feat/validacion-sesiones
   

3. Run Gentle Shell:

   gentle-shell
   

4. First request: "Explore how sessions are validated and propose expiration tests without editing."

5. Second request: "Implement only the validated case and run focused tests."

6. Open Alt+G, review changes; also review git diff and external tests.

7. If the work grows, request a recoverable ODD feature with explicit acceptance criteria.

8. If appropriate, allow a subagent for tests/documentation in an independent scope; verify integration.

9. Before committing, check that no secrets or temporary artifacts have been added:

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

10. 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 diff and 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

1. Gentle Shell README
2. Extensive technical reference
3. Workspace documentation
4. Releases/changelog
5. Gentle AI site