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 for macOSgentle-shell-installer-macos.zip
  1. Download the zip

    gentle-shell-installer-macos.zip

  2. Open the zip

    Then open the Gentle Shell Installer folder inside it.

  3. Double-click Install Gentle Shell.command

    A small window opens, then the installer appears in your browser.

  4. 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.

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 →

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.

Keep it up to date
  1. # Update along your channel: latest release or latest main
  2. gentle-shell upgrade
  3. # Switch channel
  4. gentle-shell upgrade --channel main
  5. gentle-shell upgrade --channel release
  6. # Bundled install: back to the previous version
  7. 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.

Remove it
  1. # Show what would be removed
  2. gentle-shell self-uninstall --dry-run
  3. # Remove it after confirming
  4. 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.

Install Gentle Shell

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

FAQ

Quick answers.

Anything else is in the Gentle Shell reference.

Read the documentation →
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.