![\"gentle-shell](\"docs/assets/brand/gentle-shell-banner.gif\")
\n\nYour coding agent for controlled development in the workspace you lead.
\n\n\n ![\"npm\"](\"https://img.shields.io/npm/v/gentle-pi?style=for-the-badge&labelColor=1A1218&color=F095C8\")
![\"Pi-native](\"https://img.shields.io/badge/Pi-native-F095C8?style=for-the-badge&labelColor=1A1218\"){kind=icon}
![\"MIT](\"https://img.shields.io/npm/l/gentle-pi?style=for-the-badge&labelColor=1A1218&color=F095C8\")
![\"GitHub](\"https://img.shields.io/github/stars/Gentleman-Programming/gentle-shell?style=for-the-badge&labelColor=1A1218&color=F095C8\")
![\"Last](\"https://img.shields.io/github/last-commit/Gentleman-Programming/gentle-shell?style=for-the-badge&labelColor=1A1218&color=D7A0B8\")
\n \n Website\n · \n Quickstart\n · \n Docs\n · \n Wiki\n \n
\n\nYour 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.
\n\nBUILT FOR PI · Coding-agent workspace · Focused agents · ODD
\n\n\n ★ Star gentle-shell on GitHub\n
\n\n\n ![\"\"](\"docs/assets/brand/terminal-divider.svg\")
\n
gentle-shell in action. Screenshot from Gentle-AI.
\n\n**[Docs →](docs/gentle-shell.md)**\n\n---\n\n### el Gentleman — Think before you build\n\n![\"Diagram](\"docs/assets/diagrams/gentleman-workflow.svg\")
\n\nSay 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.\n\n**[Docs →](docs/readme-reference.md#organic-driven-development)**\n\n---\n\n### Focused agents — Context with a return path\n\n![\"Diagram](\"docs/assets/diagrams/agent-orchestration.svg\")
\n\nBring 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.\n\n**[Docs →](docs/readme-reference.md#how-the-harness-decides-what-to-do)**\n\n---\n\n### ODD — The everyday workflow\n\n![\"Organic](\"docs/assets/diagrams/odd-workflow.svg\")
\n\n**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.\n\n**[Docs →](docs/readme-reference.md#organic-driven-development)**\n\n---\n\n### Native review — Review the exact change\n\n![\"Diagram](\"docs/assets/diagrams/native-review.svg\")
\n\nReview 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.\n\n**[Docs →](docs/review-integration.md)**\n\n---\n\n### Gentle Changes — Every edit, attributed and reviewable\n\n![\"Gentle](\"docs/assets/features/changes-view.png\")
\n\nYou 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.\n\n**[Docs →](docs/gentle-shell.md#browse-captured-diffs)**\n\n---\n\n### Gentle Agents — Parallel work with a live view\n\n![\"Gentle](\"docs/assets/features/agents-view.png\")
\n\nDelegating 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.\n\n**[Docs →](docs/gentle-shell.md#gentle-agents)**\n\n---\n\n### Profiles and model routing — One deliberate decision per knob\n\n![\"Profiles](\"docs/assets/features/profiles-routing.png\")
\n\nModel, 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.\n\n**[Docs →](docs/readme-reference.md#agent-model-profiles)**\n\n---\n\n### Command palette — Every command, one keystroke away\n\n![\"Command](\"docs/assets/features/command-palette.png\")
\n\nExtension commands are only useful if you can find them. `alt+k` opens a curated, grouped palette — Configuration, Session, Diagnostics, SDD, and Skills — searchable by label, command name, or description, showing entries only when they are actually registered.\n\n**[Docs →](docs/gentle-shell.md#command-palette)**\n\n---\n\n### Also in the box\n\n| Component | What it does |\n| :--- | :--- |\n| Startup and runtime panel | A configurable gentle-shell entry point and visible runtime state for Pi. |\n| Skills and delivery guidance | Package skills for documentation, issue work, PRs, reviews, and reviewable work units. |\n| Model, effort, persona, and profile controls | Explicit knobs for how Pi routes and presents work. |\n| Safety boundaries | Guards around destructive operations and sensitive-path handling. |\n| Optional companion packages | Extra capabilities you may choose to add; persistent memory is **not** bundled with `gentle-pi`. |\n| Fullscreen workspace layout | Header row plus a scrolling Status → Changes → TODO rail on wide terminals. |\n| Live status bar and prompt petal | One-line gauge, cost, and statuses; the petal shows `working` and `queued`. |\n| Parent ↔ subagent communication | Delegate, steer, reply, and cross-session notification within your local profile. |\n| Native interactive tools | Built-in questions, choices, and review captures — no third-party dependency. |\n| Gentle Todo | A plan card that turns amber when the model lets it go stale. |\n| Subscription usage | Per-window meters and resets for supported provider accounts. |\n| Gentle notices | Gentle AI calls and review reminders as cards in the transcript. |\n\n> **Every component, skill and preset: [Full breakdown →](docs/gentle-shell.md)**\n\n---\n\n### What's new in v3.5\n\nThe [v3.5.1 release](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1) makes Gentle Shell runnable on its own:\n\n- **Standalone launcher:** `npm i -g gentle-pi` installs `gentle-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:\n \n
\n \n
\n \n
\n ![\"GitHub](\"https://img.shields.io/badge/Issues-join%20the%20conversation-F095C8?style=for-the-badge&labelColor=1A1218\"){kind=icon}
![\"Contributors\"](\"https://img.shields.io/badge/Contributors-thank%20you-D7A0B8?style=for-the-badge&labelColor=1A1218\"){kind=icon}
![\"Gentleman](\"https://img.shields.io/badge/Discord-Gentleman%20Programming-F095C8?style=for-the-badge&labelColor=1A1218\"){kind=icon}
\n \n
\n \n
\n ![\"Gentleman](\"https://img.shields.io/badge/Website-Gentleman%20Programming-F095C8?style=for-the-badge&labelColor=1A1218\"){kind=icon}
![\"Gentleman](\"https://img.shields.io/badge/YouTube-Gentleman%20Programming-D7A0B8?style=for-the-badge&labelColor=1A1218\"){kind=icon}
![\"Gentleman](\"https://img.shields.io/badge/GitHub-Gentleman--Programming-F095C8?style=for-the-badge&labelColor=1A1218\"){kind=icon}
\n \n
Built with the workflow it brings to Pi.
\n\n\n ![\"MIT](\"https://img.shields.io/badge/License-MIT-F095C8?style=for-the-badge&labelColor=1A1218\"){kind=icon}
![Gentle-AI](\"https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/docs/assets/features/gentle-shell.png\"){kind=link}