gentle-shell-uninstall.md

Removing Gentle Shell

gentle-shell self-uninstall removes what Gentle Shell created and then the gentle-pi package. It always prints the full plan first, and nothing is removed until you confirm.

gentle-shell self-uninstall --dry-run          # only print the plan
gentle-shell self-uninstall                    # print the plan, then ask
gentle-shell self-uninstall --yes              # remove without asking; keeps shared configuration
gentle-shell self-uninstall --yes --include-shared

gentle-shell uninstall <source> is a different command: it is Pi's own alias for remove, forwarded to the resolved home, and stays unchanged.

What it removes

In this order:

1. Gentle Shell's own data, each only when it is a real directory or file (never a symbolic link):
   • <config home>/main/: main-channel builds, only when it holds nothing but what the main channel writes (gentle-ai/<commit>/gentle-ai[.exe], packages/gentle-pi-*.tgz, .build, .source); otherwise it is listed as kept.
   • <config home>/channel.json: the recorded update channel.
   • <config home>/dev-binary.json, only when it points at a main-channel build under <config home>/main/gentle-ai. A dev binary you registered yourself is kept.
   • <config home>/tools/go: the Go the installer downloaded for builds, only when every entry is a pinned-Go version folder carrying the installer's .gentle-shell-go marker; otherwise it is listed as kept.
   • The isolated home: GENTLE_SHELL_HOME, or ~/.gentle-shell/agent. It holds the sign-ins, chats and settings of Gentle Shell sessions. A GENTLE_SHELL_HOME directory is removed only when Gentle Shell created it (its .gentle-shell-home marker, or its setup record in ~/.gentle-shell/config.json); otherwise it is listed as kept.
   • ~/.gentle-shell/gentle-ai: the isolated home's own settings (profiles, banner and the other preferences). The gentle-ai folder next to a GENTLE_SHELL_HOME is only listed as kept, since it may not be Gentle Shell's. When GENTLE_PI_CONFIG_HOME names it, the config home rules below apply instead.
   • ~/.gentle-shell/config.json: the launcher settings.
2. Shared Gentle AI configuration, only when you accept it (see below).
3. The gentle-pi package, with the package manager that owns it: pnpm remove -g gentle-pi under PNPM_HOME, otherwise npm uninstall -g gentle-pi.
4. ~/.gentle-shell, only when it is empty.

The config home is GENTLE_PI_CONFIG_HOME, or ~/.pi/gentle-ai: the one Pi with Gentle AI, --link and custom homes use, and where the main channel keeps its builds. The isolated home's own folder is removed with the data above.

Shared configuration

Pi with Gentle AI uses the same files in the config home, so they are kept by default: profiles.json, profiles.export.json, banner.json, builtin-codemode-optout.json, background-subagents.json, double-esc-cancel.json, runtime-guardrails.json and persona.json.

• In a terminal, after you confirm the plan, a separate question asks whether to remove them; the default is No, and so is end of input (Ctrl-D).
• With --yes, they are kept unless you also pass --include-shared.
• --include-shared removes them without the separate question.

Only those exact files are removed; anything else in the config home stays.

What it never touches

• Your Pi home (~/.pi/agent, PI_CODING_AGENT_DIR or GENTLE_SHELL_USER_PI_HOME) and its settings.json.
• Custom homes used with --home <path>, recorded in ~/.gentle-shell/config.json; the plan lists them as not touched.
• Gentle AI's own state in ~/.gentle-ai, and each project's .pi/gentle-ai folder.
• Tools the web installer may have added. The plan lists them with how to remove them yourself: Pi (pnpm remove -g @earendil-works/pi-coding-agent or npm uninstall -g @earendil-works/pi-coding-agent), Engram (installed by Gentle AI's setup), the PATH entry pnpm setup added and, on Windows, %USERPROFILE%\.pnpm.

Refusals and exit codes

It refuses, before removing anything, when one of the places it removes from — the isolated home, the config home or ~/.gentle-shell — checked at its real path (after following symbolic links, including linked parent folders):

• is or contains your home directory;
• is, contains or lies inside your Pi home (~/.pi/agent, PI_CODING_AGENT_DIR or GENTLE_SHELL_USER_PI_HOME) or Gentle AI's state in ~/.gentle-ai. Inside a Gentle Shell session, PI_CODING_AGENT_DIR is the isolated home itself and your Pi home travels in GENTLE_SHELL_USER_PI_HOME: when that variable names an existing directory other than the isolated home, a PI_CODING_AGENT_DIR equal to the isolated home is not treated as your Pi home, so the command also works from inside a session;
• is, contains or lies inside a .pi directory, such as a project's .pi or .pi/gentle-ai (containing means a .pi directly inside it). The default config home, ~/.pi/gentle-ai, is the only .pi location allowed;
• for the isolated home and the config home: is, contains or lies inside the other;
• would remove a path that is, holds or lies inside a custom --home home or another path the plan lists as not touched;
• GENTLE_SHELL_HOME or GENTLE_PI_CONFIG_HOME is not an absolute path;
• neither pnpm nor npm owns the installation (an npm link of a source checkout, for example), or the owning package manager is not on PATH. Remove that installation the way you made it.

Exit code	Meaning
0	Removed, or --dry-run printed the plan.
1	Refused, cancelled, interrupted, or a removal failed. A refusal exits 1 even with --dry-run, since the real run would refuse too.
2	Usage error, including no terminal to confirm in without --yes.

At the questions:

• Ctrl-C at any question stops the whole uninstall: it exits 1 and removes nothing (both questions come before any removal).
• End of input (Ctrl-D, or a closed stdin) answers No: at the first question it cancels (exit 1, nothing removed); at the shared-configuration question it keeps the shared files and the uninstall goes on.

A refused plan lists no Gentle Shell data to remove, so no path ever appears both as removed and as not touched.

When a removal fails, it stops there: the gentle-pi package and everything after it are kept, so gentle-shell self-uninstall is still there to run again. When only the package removal fails, it prints the command to run yourself.

It runs before any Pi runtime check, so it also works when Pi is missing.

Windows

pnpm and npm run the same verified way gentle-shell upgrade runs them: through node.exe and the package manager's own JavaScript entry (or its native .exe), never a .cmd or .bat shim, which cannot run without a shell. A package manager that resolves only to such a shim counts as missing, and the command refuses before removing anything.

Removing the running gentle-pi package with pnpm or npm on Windows has not been verified yet. If the package manager fails, Gentle Shell's data is already gone and the command prints the exact pnpm remove -g gentle-pi or npm uninstall -g gentle-pi to run from a new terminal.