Your coding agent for controlled development in the workspace you lead.
Website · Quickstart · Docs · Wiki
Your terminal can run an agent. Your workspace should help you lead it.
gentle-shell is your coding agent, bringing your changes, tasks, and engineering workflow together—built for Pi.
One workspace. A coding agent you direct. A workflow you can inspect.
One prompt, from idea to reviewed commit: memory, workflow, and evidence in a real session.
gentle-ai_demo_EN_github.mp4
Prefer Spanish subtitles?
gentle-ai_demo_ES_subtitulado_github.mp4
BUILT FOR PI · Coding-agent workspace · Focused agents · ODD
Built for Pi. Shaped by Gentle-AI.
A bare terminal answers "what is the agent doing?" only with scrollback. gentle-shell turns your Pi session into a workspace: agent orchestration, live changes and runtime status, usage monitoring for supported provider accounts, and built-in diff views — so you lead the work instead of chasing it.
gentle-shell in action. Screenshot from Gentle-AI.
Say what you need once, then keep moving. el Gentleman helps turn intent into clear scope, a sensible next step, and evidence people can review — without making every task feel like a process meeting.
Bring in help without losing the thread. Focused package-owned Pi agents can map a codebase, implement a bounded change, or verify it, while one parent stays accountable for the scope, the decisions, and the final summary.
Organic Driven Development (ODD) is the everyday path: the agent explores before changing anything, clarifies only real decisions, and keeps small understood work small. Substantial, authorized work gets one recoverable feature document — mirrored in memory when available — so progress, evidence, and the next step survive an interruption; checks follow the configured TDD mode.
Review the exact change, not a moving target. Native review keeps one candidate in view, returns risk-scoped evidence, and can surface a bounded correction path. You still decide what happens next in your repository.
You should not have to run git status to find out what your agent did. Gentle Changes captures the successful write and edit tool calls from the current session and its owned subagents — no repository scans, no background polling — and shows them in a two-pane viewer with per-file line counts and an honest diff unavailable when an external edit breaks continuity. Coverage stops at those tools, so shell commands and failed runs leave no row, and a missing entry never proves a clean tree. alt+g opens it; o drops the real file into your editor.
Delegating work should not mean losing it. Every subagent runs as its own process with a live card above the editor — model, tokens, cost, elapsed — and alt+a opens the full view with retained threads, 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.
Model, effort, and who does what should be choices, not accidents. 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.
🚀 Full speed, destructive actions still ask. YOLO removes repeated permission questions for ordinary already-scoped work, which suits long autonomous runs. Destructive operations still require fresh confirmation.
/gentle:yolo enable supplies standing permission for ordinary already-scoped implementation, checks, commits, non-force pushes and PR creation. Default OFF, interactive primary TUI only, bound to the live session and Git clone; /gentle:yolo disable revokes it and /gentle:yolo status checks it. With no argument, /gentle:yolo opens a menu (enable, disable, status) showing the current state; cancelling changes nothing, and without an interactive menu it reports status. Reload and session replacement reset it. Active status plus a separate widget show 🚀 YOLO ON 🔥 — destructive confirmations remain. Explicit restrictions, configured confirmations/blocks, consequential unresolved choices, destination/credential ambiguity and native consent/recovery decisions remain mandatory. Children get no independent delivery grant. This is not a sandbox.
Or open /gentle:customize → Editor and select YOLO: OFF · session only, immediately below Vim. Enter or Space toggles the same live-session permission as /gentle:yolo; browsing and previews never activate it. Unlike Vim, YOLO is not saved in preferences or visual profiles.
Extension commands are only useful if you can find them. alt+k opens a curated, grouped palette — Configuration, Session, Diagnostics, and Skills — searchable by label, command name, or description, showing entries only when they are actually registered.
/gentle:customize opens an interactive panel to set animation quality, startup banner rose, text logo and color, or choose an installed Pi theme. Highlighting a theme previews its source palette without changing the active theme; press Enter or Space to apply it through Pi. If its source is unreadable, the preview is unavailable. Status defaults to a right rail in fullscreen terminals at least 140 columns wide, and to a bottom bar otherwise. Choose right, bottom, or hidden (which removes both the rail and the bottom status bar at every width), move the fullscreen header below the input (below the 140-column breakpoint only one status row paints: a top header replaces the bottom bar, while with the header below the input the bottom bar alone carries the header's context, cost, and usage plus extension statuses), select comfortable/compact/minimal density, and toggle Changes, Agents, TODO, usage/cost, and model details independently. Layout changes and reset take effect immediately; banner changes appear on the next startup. The Editor category offers explicit Vim enable/disable controls for the global prompt preference; highlighting shows the persisted preference and effective prompt state without changing either. Enter or Space saves it and updates the live prompt; unsupported editors keep ordinary editing even when the saved preference is on. Vim is not included in visual profiles or visual reset. The History category turns prompt-history capture on or off; it is off by default, applies to the next prompt without a restart, and never deletes stored history. An explicit GENTLE_PI_HISTORY_CAPTURE value overrides the saved choice, and the panel marks that override (see Prompt history). The panel can reset visual, banner, and animation settings to defaults. Press p for named visual profiles: s saves the current installed theme, banner, animation and layout; select a profile with ↑/↓, then use r to replace, a to apply, or d to delete. z clears only the profile catalog. Confirm destructive/apply actions with y, or cancel with any other key; Esc returns without applying a preview. Applying independent stores is not atomic: partial failures identify what changed.
Open /gentle:customize → Notifications (the card header reads Audio notifications) and configure audio directly in the same two-column card, with no nested menu. Enter toggles the master switch or cycles a type/event through silence/success/error/attention, f assigns a literal absolute local WAV/OGG/FLAC sound (≤2 MiB, ≤10 seconds) to the highlighted Success, Error or Attention type (each type keeps its own sound), and p previews its assigned sound. Advanced folds per-event exceptions; the type choices stay independent. Audio starts off; RPC and children stay silent.
Quick answer (Linux/WSLg): on plain Linux the installed package prefers the native WAV backend and needs no external player — it talks to a local PulseAudio/PipeWire-Pulse Unix socket and requires a running server with a default sink. Inside WSL the Windows system SoundPlayer is preferred instead: the validated WAV snapshot is mapped to a \\wsl.localhost\<distro>\... UNC path, so no Pulse server or RDP audio dependency is required; it does depend on the default /mnt/c automount and the standard C:\Windows root and otherwise falls back to the trusted Linux CLI before any playback. Native Windows WAV uses the same system SoundPlayer through the fixed C:\Windows\...\powershell.exe host. A read-only probe succeeded here, but that is not a claim of physically heard audio. OGG/FLAC keep the legacy CLI backend (paplay/pw-play/aplay) on Linux and WSL; native codecs are a future phase and Windows OGG/FLAC is unsupported. macOS keeps afplay for WAV and FLAC while an own CoreAudio phase is planned. Usage, limits and verification →
| Component | What it does |
|---|---|
| Startup and runtime panel | A configurable gentle-shell entry point and visible runtime state for Pi. |
| Skills and delivery guidance | Package skills for documentation, issue work, PRs, reviews, and reviewable work units. |
| Model, effort, persona, and profile controls | Explicit knobs for how Pi routes and presents work. |
| Safety boundaries | Guards around destructive operations and sensitive-path handling. |
| Optional companion packages | Extra capabilities you may choose to add; persistent memory is not bundled with gentle-pi. |
| Fullscreen workspace layout | Header row plus a scrolling Status → Changes → TODO rail on wide terminals. |
| Live status bar and prompt petal | One-line gauge, cost, and statuses; the petal shows working and queued. |
| Parent ↔ subagent communication | Delegate, steer, reply, and cross-session notification within your local profile. |
| Native interactive tools | Built-in questions, choices, and review captures — no third-party dependency. |
| Gentle Todo | A plan card that turns amber when the model lets it go stale. |
| Subscription usage | Per-window meters and resets for supported provider accounts. |
| Gentle Stats | /gentle:stats shows local usage history: activity heatmap, tokens, cost, streaks, and per-model share. |
| Gentle notices | Gentle AI calls and review reminders as cards in the transcript. |
Cross-orchestrator messages appear as compact 🤖 Sender → 🤖 Recipient cards with single-row headings. Expand a card to inspect available identifiers and reasons. Message queued means queued, not delivered or read; long names are clipped to fit narrow terminals.
Every component, skill and preset: Full breakdown →
The v3.5.1 release makes Gentle Shell runnable on its own:
- Standalone launcher:
npm i -g gentle-piinstallsgentle-shell, which opens Pi with the Gentle Shell package loaded from its own home (~/.gentle-shell/agent) or, with--link, from your existing~/.pi/agent;gentle-shell install npm:<pkg>and the other pi subcommands run against the selected home. A bundled orPATHpi is used, never a modified one. - Link mode take-over: when
~/.pi/agentalready declares gentle-pi as a path package, the launcher takes over extension loading (--no-extensionsplus explicit-efor every other declared package and loose extension) so tools never register twice. - Interactive RPC hosts: with
GENTLE_SHELL_INTERACTIVE_HOST=1and--mode rpc, ask-user tools use pi's RPC dialogs and gentle-agents publishes live subagent activity for the desktop app. See the reference.
Naming transition: The product is called
gentle-shell; the current npm package and repository remaingentle-piuntil migration.
Download the installer for your computer, double-click it, and follow the steps in your browser. It installs everything Gentle Shell needs (Node.js, pnpm, Pi and Gentle Shell), or updates what you already have, and installs nothing until you confirm the plan it shows you. (To show that plan it may first download Node.js and pnpm into a temporary folder, which it removes afterwards.)
| Your computer | Download | Then |
|---|---|---|
| macOS | gentle-shell-installer-macos.zip | Open the zip, then double-click Install Gentle Shell.command inside the Gentle Shell Installer folder. |
| Windows | gentle-shell-installer-windows.zip | Right-click the zip → Extract All. Open the extracted folder, then the Gentle Shell Installer folder inside it, and double-click Install Gentle Shell.cmd. It does not run from inside the zip. |
| Linux | gentle-shell-installer-linux.tar.gz | Extract it, then double-click install-gentle-shell.sh. If your file manager does not run scripts, run sh install-gentle-shell.sh in that folder. |
A small window opens, then the installer appears in your browser. Use the tab it opens, and keep the small window open until the installer says it is done. If a download link does not open, the newest release does not include the installers yet: use Path C meanwhile.
Your computer will warn you the first time. These installers are not signed with an Apple or Microsoft developer certificate yet, so the system cannot verify who made them. That warning is expected; here is how to continue:
- macOS: you see "Install Gentle Shell.command" Not Opened (or cannot be opened because Apple cannot check it). Click Done, open System Settings → Privacy & Security, scroll down to the message about Install Gentle Shell.command, click Open Anyway, and confirm with your password. On older macOS versions you can instead right-click the file, choose Open, then Open again. You only do this once.
- Windows: you see Windows protected your PC: click More info, then Run anyway. If you see Open File – Security Warning instead, click Run.
- Linux: if double-click opens the file in an editor, run
sh install-gentle-shell.shin that folder instead.Only download from this repository's Releases page. To check a download, compare its SHA-256 with gentle-shell-installers-SHA256SUMS.txt.
The installer is a preview: it is tested on Linux and in CI, while clean-machine runs on macOS and Windows are still being verified. How it works and what it changes: installation wizard.
gentle-shell opens Pi with the Gentle Shell package loaded, without installing it into your pi agent or editing its settings.json.
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 --linkgentle-shell alone starts in its own home, ~/.gentle-shell/agent, and sets that home up on first run — no separate step. Gentle Shell keeps its own home with the Gentle AI companion packages and no conflicting plugins; gentle-pi itself always stays this launcher's own copy, never one installed into the home; your pi install is untouched. That home also defaults to the Gentleman-Cute theme unless you set your own. gentle-shell --link reuses ~/.pi/agent as-is, is never auto-provisioned, and never has its theme touched.
# Re-run provisioning by hand, e.g. to see the full install output
gentle-shell setupgentle-shell setup installs the same companion packages gentle-ai provisions into a regular Pi, into this home only, then removes the one package that conflicts with gentle-pi's own ask_user_question tool (gentle-ai #4820). The first gentle-shell launch in a home already runs this automatically; setup is for re-running it by hand. See First run for the opt-out (GENTLE_SHELL_NO_AUTO_SETUP=1) and failure behavior.
# Make --link the default
gentle-shell home linkEvery other argument is forwarded to pi unchanged, for example gentle-shell --mode rpc or gentle-shell -p "...". Full flags, env vars, and modes: launcher reference.
Install the stable release into an existing pi agent, restart Pi, then synchronize the installed assets.
# Published stable release: v3.5.1
pi install npm:gentle-pi@3.5.1
# Restart Pi, then run:
gentle-ai sync
# Start Pi in your project
piSee the v3.5.1 release notes for version-specific changes.
Builtin codemode warning. gentle-pi replaces Pi's builtin codemode with its compact renderer, so Pi warns at startup that the builtin was not loaded. In your own Pi home (pi with this package, or gentle-shell --link), gentle-pi asks once in the interactive TUI whether to add "-builtin:codemode" to extensions in the agent settings.json (usually ~/.pi/agent/settings.json); it writes only if you accept, and the warning disappears from the next launch. A declined prompt is not repeated. To silence it by hand, add the entry yourself, for example "extensions": ["-builtin:codemode"]. Isolated gentle-shell homes already carry it.
The same installer as the download above, started from a clone instead of a download:
git clone https://github.com/Gentleman-Programming/gentle-shell.git
cd gentle-shell
# macOS and Linux
sh scripts/bootstrap.sh
# Windows (cmd)
scripts\bootstrap.cmdIt installs what is missing (Node.js, pnpm, Pi, Gentle Shell) and updates an existing Gentle Shell; nothing changes until you confirm. The bootstrap gets Node.js and pnpm into a temporary folder if they are missing, then opens the wizard in your browser at a private 127.0.0.1 address. Use the tab it opens: the link works once and expires after 2 minutes. On the review screen, choose what to install:
- Latest release (recommended): the published Gentle Shell with its pinned Gentle AI binary.
- Latest main: development builds of Gentle Shell and Gentle AI from the latest commit of
main, built on your computer. Needs Go.
An existing Pi is reused, never reinstalled or downgraded. An existing Gentle Shell is updated with the package manager that installed it (pnpm or npm); one it cannot attribute, such as an npm link of a source checkout, is left untouched and explained. No checkout dependencies are needed (pnpm install is not required). This is a preview: it is tested on Linux and in CI, while clean-machine runs on macOS and Windows are still being verified. Details: installation wizard.
# Update along your channel: the latest release, or the latest main
gentle-shell upgrade
# Switch channel
gentle-shell upgrade --channel main
gentle-shell upgrade --channel releasegentle-shell upgrade uses the package manager that owns your installation. On the main channel it rebuilds Gentle AI and Gentle Shell from the latest main commits (only what changed) and needs Go and pnpm; switching back to release restores the pinned Gentle AI binary. gentle-shell update is a different command: it is Pi's own package update. More: upgrade reference.
Use /gentle:jobs to inspect this session's background commands and monitors. Running jobs appear first; each group is ordered newest first. Arrow keys select a job, Tab opens details on narrow terminals, s stops a running job, and q closes the modal.
The Status panel has a Jobs section with each running job's description. When the panel is hidden or unavailable in the compact/mobile layout, the top or bottom bar shows only the running count (⧗ 1 job). The count and descriptions disappear when no jobs remain active; /gentle:jobs retains completed jobs for inspection.
The first-party nan provider is included; no third-party provider package is required. Set NAN_API_KEY before starting Pi, or use native /login → NaN (also /login nan), then use /model to select a model. Both login routes await explicit API-key input; blank or whitespace-only entries fail without saving a credential, and surrounding whitespace is trimmed. Cancellation leaves the stored key unchanged. Stored keys take precedence over NAN_API_KEY. Pi streams chat completions through its OpenAI-compatible provider. Model discovery intersects NaN's authenticated /v1/models response with a maintained subset of known chat IDs from the official model documentation; unknown and non-chat IDs are omitted. A successful response with no known chat IDs stays empty. Documented context, reasoning, and text/image capabilities are preserved with conservative numeric bounds for abbreviated limits; audio input is not advertised by Pi. The provider configures maxTokens caps rather than claiming undocumented model maxima: 32,768 for GLM 5.3, GLM 5.3 Flash, and MiMo; 16,384 for DeepSeek V4 Flash; 65,536 for Gemma 4 and Qwen 3.6; and 131,000 for Qwen 3.8 Flash (NaN documents 131K). Reasoning shares the output budget. Before a successful refresh, all seven documented chat models are available as the offline fallback in /gentle:models: glm5.3, deepseek-v4-flash, glm5.3-flash, qwen3.8-flash, mimo-v2.6-flash, gemma4, and qwen3.6. This fallback declares documented support, not proof of access for your key. Once refreshed, the successful live key-scoped list remains authoritative (including an empty list), even offline or after a failed refresh. Changing credentials resets the catalog to the full documented fallback until discovery succeeds for the new key. NaN MCP search and media bridges are not included.
Thinking levels follow NaN's reasoning contract:
| Models | Pi thinking levels |
|---|---|
| GLM 5.3 / GLM 5.3 Flash | low, medium, high, and max are fully controllable. No off; Pi's minimal and xhigh clamp to low and max. |
| Qwen 3.6 / Gemma 4 | off sends none and minimal also skips reasoning; low, medium, high, and max set reasoning budgets. Pi's xhigh clamps to max. |
| DeepSeek V4 Flash / Qwen 3.8 Flash / MiMo | The same off (none), minimal, low, medium, high, and max levels are accepted, but NaN manages their reasoning depth, so no value changes it. Pi's xhigh clamps to max. The header reports effort: auto for these three and a one-time notice says the level does not change the depth. |
/gentle:status
/gentle:doctor
STATUS diagnostics are opt-in:
/gentle:status-timing enablearms timing for the next separately authorized STATUS-bearing tool call;showconsults the memory-only summary anddisableclears it. It never invokes or retries STATUS. See the diagnostic boundaries.
RDD is opt-in: enable native receipt-driven development only through an explicit
/gentle:review-mode enabledecision. The.git/gentle-ai/candidate-viewsparent must sit on a filesystem that honors private POSIX modes (or equivalent Windows ACLs); WSL DrvFS mounts without metadata can reject START before lineage creation.
Fullscreen installation note: a recognized global installation persists Pi’s
"tuiMode": "fullscreen"setting. Project-local and other install paths do not receive that change.
Interactive RPC hosts: the desktop app sets
GENTLE_SHELL_INTERACTIVE_HOST=1automatically, without touching your Pi config — see the installation reference.
For prerequisites, source-checkout instructions, full install behavior, and release policy, use the installation reference. For everyday work, describe the outcome and follow ODD.
Start with the product-facing destination, then move into the operational reference only when you need the details.
| Destination | Purpose |
|---|---|
| gentle-shell reference | Workspace layout, changes, usage, agents, and todo interactions. |
| ODD workflow · Technical reference | Everyday work and recovery, installation, configuration, commands, and contributor detail. |
| Review integration | The provider/consumer boundary for native review. |
| Native authority architecture | Ownership boundaries and review architecture. |
| Telemetry | Approved fields and source limitations. |
| Delegated verification | Practical verification guidance. |
| Skill style guide | The package skill contract. |
| Installation wizard (preview) | How the browser installer checks your computer, what it installs on the release and main channels, its security model, and what is still being verified. |
This project is built in public. Bring a real workflow, a sharp question, a bug report, or a small improvement that makes the next person’s work clearer.
- Open an issue with the context needed to reproduce or understand the idea.
- See the people shaping the project in the contributors graph.
- Follow Gentleman Programming for the wider ecosystem.
gentle-shell is built by Alan Buscaglia, the maker behind Gentleman Programming. It grew from a practical belief: capable agents are more useful when the human’s intent, review load, and delivery judgment stay visible all the way through the work.
Startup intro collaboration: thanks to @aporcelli and pi-gentle-startup, which inspired the clean-screen startup animation, compact runtime panel, and pink visual treatment.
Built with the workflow it brings to Pi.
Trademark notice: The gentle-shell™ and gentle-pi™ names and associated logos are trademarks of Alan Buscaglia. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See TRADEMARKS.md.