Install
npm i -g gentle-piWho it's for
Gentle Shell suits developers who already use Pi as their coding agent, want controlled development, and expect the agent to explore before touching any code, to ask questions only at genuine decision points, and to keep small, well-understood work moving in small steps. The official name for this everyday workflow is Organic Driven Development (ODD): the agent explores before changing anything, clarifies only real decisions, and keeps small, understood work small. Once installed, an ordinary Pi session becomes a workspace: agent orchestration, live changes and runtime status, usage monitoring for supported provider accounts, and built-in diff views all live in one interface. The official README also names optional SDD/OpenSpec, along with subagents, TDD evidence, review guardrails, skills, and memory integrations.
Where it fits poorly, or what to settle first: if you don't use Pi, the official documentation says nothing about running it inside other agents. Until the official migration finishes, both the npm package and the repository keep the name gentle-pi, so the product name and the package name currently differ. Which operating systems it needs and which Pi version it requires go unmentioned; confirm both yourself before installing.
Your first attempt in 3 minutes
Start by accepting one installation-time side effect that the official documentation states openly: gentle-pi replaces Pi's builtin codemode extension with its own compact renderer, and from then on Pi warns at every startup that the builtin was not loaded. In other words, the side effect happens at the installation step, not during some later task; deciding whether to install is deciding whether to accept it. If you depend on the builtin codemode's behavior, evaluate that first; everyone else can treat the startup warning as an expected sight.
Only one main path is recommended: install globally in a terminal with npm i -g gentle-pi. After installing, start gentle-shell: it opens Pi with the Gentle Shell package loaded from its own home directory ~/.gentle-shell/agent; if you would rather load it from an existing ~/.pi/agent, pass --link at startup. This is only the official switch between load locations, not a second installation method — both locations appear in the official instructions, so pick one.
The official description gives two success signals: first, what opens after startup is a Pi session with the Gentle Shell package loaded; second, the startup warning that the builtin codemode was not loaded appears — which is precisely proof that the replacement took effect. Both are visible on the first screen after launch, and no task that changes anything needs to run first. For the first task, pick a small, purely analytical one about code — for example, have the agent read a module and explain its structure and call relationships, without changing anything yet. The ODD path is explore-first by design, so this stage produces no changes; whether the agent writes files, runs commands, or reaches the network when executing tasks is not stated in the official documentation, so treat it as unconfirmed and verify inside the session before letting it act.
Use cases
Case one: understanding unfamiliar code. Launch a task like this in the session: read a given module first, explain its responsibilities and dependencies, and don't modify files. This walks the ODD everyday path — the agent explores first and asks only about real decision points, keeping small tasks small. If the agent asks questions after exploring, then by the official description of ODD they should be questions that genuinely affect decisions. The expected outcome is an explanation grounded in that exploration; the reply format is not defined officially, so go by what the session actually outputs.
Case two: checking while changing. Have the agent make a small change while you inspect each change in the built-in diff view; the live changes and runtime status panels show what the agent is doing, and if your account belongs to a supported provider, usage monitoring appears in the same interface. The value here is that the change process stays visible: the views are provided officially, the changes come from the task, and the two can be compared side by side. What gets changed is agreed between you and the agent in the session; the official documentation covers only these views and status capabilities and does not vouch for rewrite quality.
Boundaries of use
Side effects and confirmation points: installing gentle-pi replaces Pi's builtin codemode (the compact renderer takes over), and the startup warning is expected behavior, not a fault. Beyond that, the official documentation says nothing about its command-execution, file read/write, or network-access scope — whether those behaviors occur is unknown, so do not assume it is read-only. The documentation also omits how changes made during a session are written to disk and whether each step is confirmed; observe the agent's actual behavior in the session before deciding to continue.
Runtime prerequisites: it targets Pi sessions and installs globally through npm; whether it runs inside other agents, and which code or text languages it supports, go unmentioned. The limits stated officially: the npm package and repository remain gentle-pi until migration completes, so the mismatch between product name and package name persists until then; --link only switches where the package loads from. Still-unconfirmed key information includes how to configure and uninstall it, whether the builtin codemode is restored after uninstalling, and how SDD/OpenSpec, subagents, TDD evidence, review guardrails, skills, and the memory integrations are each enabled — the official documentation names them as capabilities but gives no steps.