gentle-shell
Gentleman-Programming · Gentleman-Programming/gentle-shell
This coding agent harness for Pi transforms your terminal into an agent workspace, offering orchestration, live feedback, and review guardrails for controlled development with AI.
Gentle Shell is a Pi-native coding-agent harness for controlled development with Organic Driven Development, optional SDD/OpenSpec, subagents, TDD evidence, review guardrails, skills, and memory integrations.
Preview
What you can do with it
- Use an agent to generate code with TDD evidence and ensure it passes review guardrails before committing.
- Orchestrate multiple subagents to work on different parts of a project within a structured development workflow.
- Monitor your AI agent's live changes and runtime status in a dedicated workspace, ensuring controlled and inspectable development.
Safety check
Usable, but read the notes first.
- ●npm package runs a script automatically on install.
package.json
Automated scan of the repo files. Always review code you run.
From the README
gentle-shell™
Your coding agent for controlled development in the workspace you lead.
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.
🎬 See it in action
One prompt, from idea to reviewed commit: memory, workflow, and evidence in a real session.
https://github.com/user-attachments/assets/fa5c0cfe-06e7-4c0d-bd6e-8ac7cb934339
Prefer Spanish subtitles?
https://github.com/user-attachments/assets/6d2bc422-a4dd-4ecf-a04b-fcd3bea7fea9
BUILT FOR PI · Coding-agent workspace · Focused agents · ODD
★ Star gentle-shell on GitHub
Built for Pi. Shaped by Gentle-AI.
Features
gentle-shell — Your coding agent, in the workspace you lead
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.
el Gentleman — Think before you build
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.
Focused agents — Context with a return path
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.
ODD — The everyday workflow
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.
Native review — Review the exact change
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.
Gentle Changes — Every edit, attributed and reviewable
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.
Gentle Agents — Parallel work with a live view
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.
Profiles and model routing — One deliberate decision per knob
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.
🚀 YOLO 🔥 — Session permission, destructive guards intact
🚀 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 prev