Gentle Shell · built for Pi
Your coding agent, in the workspace you lead.
Gentle Shell turns a Pi session into a terminal workspace: parallel coding agents, live tasks, Git diffs and permission controls in one interface. Powered by Gentle AI and Organic Driven Development (ODD).
Comfortable with npm? npm i -g gentle-pi then gentle-shell
- v4.1.0
- latest release
- MIT
- open source
- 3
- installers: macOS, Windows, Linux
- Pi 1.2.0+
- required
Naming: the product is Gentle Shell; the npm package and repository stay gentle-pi until the migration.
Choose an install path
How do you want to install?
Already installed with npm before v4.1.0? Use the download installer; it detects your installation and shows the update plan.
Download and double-click
Installs Node.js, pnpm, Pi and Gentle Shell, or updates what you already have. It installs nothing until you confirm the plan it shows you.
- Download the zip
gentle-shell-installer-macos.zip
- Open the zip
Then open the Gentle Shell Installer folder inside it.
- Double-click Install Gentle Shell.command
A small window opens, then the installer appears in your browser.
- Confirm the plan in the browser
Use the tab it opens, and keep the small window open until the installer says it is done.
Your computer will warn you the first time.The installers are not signed with an Apple or Microsoft developer certificate yet, so the system cannot verify who made them. You see “Install Gentle Shell.command” Not Opened. Click Done, open System Settings → Privacy & Security, find the message about the installer, click Open Anyway and confirm with your password. You only do this once.
- Download the zip
gentle-shell-installer-windows.zip
- Right-click the zip → Extract All
It does not run from inside the zip.
- Open the extracted Gentle Shell Installer folder
Double-click Install Gentle Shell.cmd.
- Confirm the plan in the browser
Use the tab it opens, and keep the small window open until the installer says it is done.
Your computer will warn you the first time.The installers are not signed with an Apple or Microsoft developer certificate yet, so the system cannot verify who made them. You see Windows protected your PC: click More info, then Run anyway. If you see Open File – Security Warning instead, click Run.
- Download the archive
gentle-shell-installer-linux.tar.gz
- Extract it
Then open the extracted folder.
- Double-click install-gentle-shell.sh
If your file manager does not run scripts, run
sh install-gentle-shell.shin that folder. - Confirm the plan in the browser
Use the tab it opens, and keep the small window open until the installer says it is done.
Your computer will warn you the first time.The installers are not signed with an Apple or Microsoft developer certificate yet, so the system cannot verify who made them. If double-click opens the file in an editor, run sh install-gentle-shell.sh in that folder instead.
Where it goes
A new installation keeps its own Node.js, npm, pnpm and Pi in ~/.gentle-shell. Your own tools are not used or changed.
Check the download
Only download from the repository's Releases page, and compare the SHA-256 with gentle-shell-installers-SHA256SUMS.txt.
The installer is a preview: tested on Linux and in CI, while clean-machine runs on macOS and Windows are still being verified. How the installation wizard works →
Standalone gentle-shell
Opens Pi with the Gentle Shell package loaded, without installing it into your pi agent or editing its settings.json. Requires Pi 1.2.0 or newer.
npm i -g gentle-pi- # Own home, never touches your pi install
gentle-shell- # Reuse your pi sign-ins, models and chats instead
gentle-shell --link
Its own home
gentle-shell starts in ~/.gentle-shell/agent and sets it up on first run, with the Gentle AI companion packages and the Gentleman-Cute theme.
Or share with pi
--link reuses ~/.pi/agent as it is. home import-pi copies your sign-ins instead, and never overwrites a file.
- # Make --link the default
gentle-shell home link- # Or copy your pi sign-ins into the separate home
gentle-shell home import-pi --dry-rungentle-shell home import-pi
Every other argument goes to pi unchanged, for example gentle-shell --mode rpc.
Inside an existing pi
Install the stable release into your pi agent, restart Pi, then synchronize the installed assets.
- # Published stable release: v4.1.0
pi install npm:gentle-pi@4.1.0- # Restart Pi, then run:
gentle-ai sync- # Start Pi in your project
pi
Seeing a builtin codemode warning?Gentle Shell replaces Pi's builtin codemode with its compact renderer. It asks once whether to add "-builtin:codemode" to your agent settings and writes only if you accept.
Browser installer from a checkout
The same installer as the download, started from a clone. It opens the wizard at a private 127.0.0.1 address; the link works once and expires after 2 minutes.
git clone https://github.com/Gentleman-Programming/gentle-shell.gitcd gentle-shell- # macOS and Linux
sh scripts/bootstrap.sh- # Windows (cmd)
scripts\bootstrap.cmd
- Latest release (recommended): the published Gentle Shell with its pinned Gentle AI binary.
- Latest main: development builds from the latest commit of
main, built on your computer with Go.
After installing
Check it and keep it current.
Inside a session, /gentle:status and /gentle:doctor check your setup.
Update
gentle-shell upgrade uses the package manager that owns your installation.
- # Update along your channel: latest release or latest main
gentle-shell upgrade- # Switch channel
gentle-shell upgrade --channel maingentle-shell upgrade --channel release- # Bundled install: back to the previous version
gentle-shell upgrade --rollback
Before v4.1.0 the launcher has no upgrade. Download the latest installer instead; it detects your installation and shows the update plan.
Remove
Removes Gentle Shell's own data, its isolated home and the gentle-pi package. It never touches your Pi home.
- # Show what would be removed
gentle-shell self-uninstall --dry-run- # Remove it after confirming
gentle-shell self-uninstall
See the workspace before you install it.
Gentle Shell turns a Pi session into a workspace for AI-assisted development. Pick a feature below to see it on screen.
Gentle Changes: what your session left uncommitted
The current Git state of the session's repository and of every worktree its subagents used: working tree against HEAD, untracked files included, one group per root.
Commit and a file disappears; remove a worktree and its group goes with it. Nothing runs at startup.
- alt+gopen the two-pane viewer
- Fhide the file list, read the diff full width
- oopen the real file in your editor
- j / kmove between files
Gentle Agents: parallel work with a live view
Every subagent runs as its own process with a live card: model, tokens, cost and elapsed time. The full view keeps each thread, with stop controls and history restored on resume.
A child can ask you a question as an ordinary dialog, and background results come back as cards that start a new turn. Nothing polls.
- alt+aopen the full agents view
- ffollow the selected thread
- sstop an active task you own
- aswitch scope to all open sessions
Profiles and model routing: one deliberate decision per knob
Named profiles route the orchestrator atomically and independently from packaged and review roles.
A repository can pin its profile so its subagents stop following the globally active one, and the panel always shows the routing the runtime actually uses.
- /gentle:profilesopen the profiles panel
- headershows model · effort · profile live
Gentle Commands: every command, one keystroke away
A curated, grouped menu, not a raw list of every extension command. Entries appear only when they are actually registered.
Search by label, command name or description; Enter runs the entry exactly as if you had typed it.
- alt+kopen Gentle Commands (
/gentle:commands) - ctrl+j / ctrl+kmove
- enterrun the highlighted entry
- escclose
Customization: look, layout, editor and permissions in one panel
Eleven categories: Animations, Banner, Themes, Editor, History, Notifications, Layout, Cards, Sections, Profiles and Reset. Click one in the mock to see its options.
Pick animation quality, the startup rose, logo and color, a Pi theme with a live preview, where the status and header live and how dense the shell is, the card style and content, and which sections show. The Editor category holds Vim, the session-only YOLO switch and the session and default permission modes; History turns prompt-history capture on or off, Notifications sets opt-in audio per event, and Profiles saves named visual profiles.
- /gentle:customizeopen the panel
- ← / → or tabswitch between categories and options
- ↑ / ↓move
- enterapply the highlighted choice
- pnamed visual profiles (in Notifications: test the sound)
- escclose
Background jobs: waiting costs neither a loop nor a subagent
bash_background runs a command in the background and wakes the agent once when it exits, with the exit code and the last output lines. monitor turns each output line of a long-running command into an event.
/gentle:jobs lists this session's jobs with their command, status, output file and live tail.
- /gentle:jobsopen the jobs overlay
- ↑ / ↓select a job
- sstop the selected running job
- qclose
Permission modes: Normal, Auto, YOLO or Super YOLO
- Normal
- The default. Every permission question is asked, as Pi asks it today.
- Auto beta
- A separate reviewer, using the current session model, checks each eligible action (file, shell, custom and MCP tools) against what you asked before it runs. A decision that is unavailable or stale does not run the action. It adds inference cost and latency.
- YOLO
- Standing permission for ordinary, already-authorized work: implementation, checks, commits, non-force pushes and pull requests run without asking. Destructive operations still ask for a fresh confirmation.
- Super YOLO
- No permission prompts at all, data-loss confirmations and configured guardrails included. Secrets stay blocked (
.env,.ssh, keychains, key files,secrets/, cloud credentials), catastrophic commands stay blocked (rm -rf /,git reset --hard, forced clean, force push), and questions and consent are never answered for you.
In every mode your explicit restrictions and consent decisions still apply, subagents never inherit an elevated mode, and none of them is a sandbox.
- /gentle:mode <mode>normal, auto, yolo or super-yolo for this session
- /gentle:mode default <mode>the mode new sessions start in
- /gentle:mode statuscurrent mode and saved default
- /gentle:yoloquick toggle: enable, disable, status
- /gentle:customizeEditor → Session or Default permissions
Gentle AI, Gentle Shell, gentle-pi: what is the difference?
- Gentle AI
- Configures the coding agents you already use (Claude Code, OpenCode, Cursor, Codex, Pi and more) with memory, the ODD workflow, skills and review guardrails. It never installs an agent for you.
- Gentle Shell
- A complete workspace built on Pi, with its own Pi runtime, agents and interface: Gentle Changes, Gentle Agents, Gentle Commands and the permission modes. Its installer bundles its exact Pi, a pinned Gentle AI and Engram.
- gentle-pi
- Not a third product: it is Gentle Shell's npm package and repository name until the migration.
In short: Gentle AI improves the agent you already have; Gentle Shell is the full workspace on Pi, with Gentle AI inside.
Is Gentle Shell a theme for Pi?
No. It is a coding-agent workspace built for Pi: the shell bar, workspace changes, provider usage and native agent orchestration views inside a Pi session.
Will it change my existing pi setup?
Not with the standalone launcher: gentle-shell runs in its own home, ~/.gentle-shell/agent. Use gentle-shell --link only if you want it to reuse your pi sign-ins, models and chats.
What do I need first?
Nothing for the download installer: it installs Node.js, pnpm and Pi when they are missing. For the npm paths you need Pi 1.2.0 or newer and Node 22.19.0 or newer.
Does it include persistent memory?
The gentle-pi package does not bundle it. Memory comes from the optional gentle-engram companion; a bundled install from the installer keeps Engram in its own folder.
Which models can I use?
The models your Pi setup offers, picked with /model. The first-party NaN provider is included, and the usage panel shows subscription windows for Codex, Claude and NaN.
How do I remove it?
gentle-shell self-uninstall removes Gentle Shell's own data, its isolated home and the gentle-pi package. It never touches your Pi home.
Lead the work instead of chasing it.
Free and open source under the MIT license.