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.
BUILT FOR PI · Coding-agent workspace · Focused agents · Optional SDD
Built for Pi. Shaped by Gentle-AI.
A complete workspace for the agent you direct. gentle-shell is your coding agent, built for Pi, with native workspace features for agent orchestration, usage monitoring for supported provider accounts, and built-in diff views—all in one integrated layout.
See active tasks, session changes, and runtime status without leaving the work you are leading.
gentle-shell in action. Screenshot from Gentle-AI.
→ Read the gentle-shell reference
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.
→ See persona modes and routing
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.
When a change needs a plan people can follow, choose SDD/OpenSpec and keep the proposal, specification, design, tasks, and verification record together. If Strict TDD is active and the project provides the test capability, apply work records RED → GREEN → TRIANGULATE → REFACTOR evidence as it happens.
→ Explore the SDD/OpenSpec flow
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.
→ Read the review integration boundary
The v2.6.0 release brings a more persistent, inspectable Pi workspace:
- Shell: registered worktrees survive reloads;
/gentle:changesgroups dirty roots with diffs, status, and line counts; fullscreen navigation, responsive sidebars, and cached frames stay live without unnecessary redraws. - Agents and profiles: the Agents view shows orchestrator/session hierarchy, retained completion, abort, and lost-exit history, parent-child handoff, and model, effort, and usage observability. Named
/gentle:profilesatomically route the orchestrator independently from packaged and review roles. - Control and recovery: native SDD requires parent-confirmed preflight; native review supports intended-untracked selection, consent, and provider continuations. Subsystems install with explicit recovery guidance when npm lifecycle scripts were skipped; Pi Git installs are recognized globally; custom ask responses are opt-in. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.
| Capability | What it brings to the workspace |
|---|---|
| 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. |
Optional companions, when they fit your setup
| Package | Optional role |
|---|---|
pi-intercom |
Cross-session communication where your Pi setup supports it. |
gentle-engram |
Persistent memory, separately installed and configured. |
pi-web-access |
Web access when a task needs it and your policy allows it. |
pi-lens |
Additional inspection surfaces. |
@juicesharp/rpiv-ask-user-question |
Interactive choice support. |
These are companions, not hidden prerequisites or a claim that every Pi installation has every capability.
Install the stable release, restart Pi, then synchronize the installed assets.
Naming transition: The product is called
gentle-shell; the current npm package and repository remaingentle-piuntil migration.
# Published stable release: v2.6.0
pi install npm:gentle-pi@2.6.0
# Restart Pi, then run:
gentle-ai sync
# Start Pi in your project
piSee the v2.6.0 release notes for version-specific changes.
/gentle:status
/gentle:doctor
RDD is opt-in: enable native receipt-driven development only through an explicit
/gentle:review-mode enabledecision.
Fullscreen installation note: a recognized global installation persists Pi’s
"tuiMode": "fullscreen"setting. Project-local and other install paths do not receive that change.
For prerequisites, source-checkout instructions, full install behavior, and release policy, use the installation reference. For substantial work, choose SDD/OpenSpec explicitly and review the phase artifacts before implementation.
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. |
| README technical reference | Preserved installation, release policy, configuration, SDD/OpenSpec, commands, skills, 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. |
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.