Gentleman-Programming/gentle-shell

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.
🎬 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
Watch Prefer Spanish subtitles? — the same demo with Spanish captions
https://github.com/user-attachments/assets/6d2bc422-a4dd-4ecf-a04b-fcd3bea7fea9
BUILT FOR PI  ·  Shaped by Gentle-AI  ·  Coding-agent workspace  ·  Focused agents  ·  ODD
✨ What's new in v4.1
The v4.1.0 release makes Gentle Shell installable on a clean machine and pins Gentle AI v4.1.1:
- **Clean-machine installers:** a browser wizard and double-click installers for macOS, Windows, and Linux install what is missing, update what you have, and ask once before changing anything. See Get started.
- **Bundled Gentle Shell:** a new installation keeps its exact Pi, pinned Gentle AI, Engram, and state in one prefix; existing global installs can migrate, the launcher offers updates, and gentle-shell self-uninstall removes it.
- **Background jobs and monitors:** bash_background wakes the agent once when a command exits, and monitor turns each output line of a long-running command into an event. Inspect them with /gentle:jobs (Background jobs).
- **Contextual Auto permissions:** Auto decides with the conversation's context and image input, retries provider failures, and can be the saved default (Permission modes).
- **Cross-session coordination:** sessions publish a recognizable subject, task aliases, repository scope, and a bounded work classification that other sessions can list, search, and consult with explicit cost permission.
- **Session-bound profiles:** the active profile binds to the parent session, and orchestrator and reviewer routing apply per session.
- **Delegate for a reason and review by risk:** see Focused agents, ODD, and Native review.
🧠 How it works
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.
**Docs →**
---
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; behavior changes are test-first by default when a runnable test applies.
Tasks are sized by understanding, risk, and resumability: work you could finish from the request and git diff alone runs inline, with no subagents and no task document. The feature document quotes your spec verbatim, and every handoff points at it instead of paraphrasing it, so exact strings, error messages, and examples reach the workers intact.
**Docs →**
---
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.
The parent delegates for a reason, not for size. Understanding that outgrows one inline batch (about 3 calls and 10k tokens) gets one read-only explorer; two or more independent units of behavior, each big enough to outweigh a subagent's start-up and with disjoint edit surfaces, get parallel writers; a change that touches a named high-risk item gets an independent verifier, whatever model wrote it; a long session hands its next unit to a fresh worker. Without a named reason the parent works inline — file count and task size never decide the route.
**Docs →**
---
Measured — What proportional routing changed
The routing rules came from benchmarks. These runs use a local benchmark with hidden acceptance suites; each cell is a single run (n=1), and cost is API-equivalent.
| Scenario | Before | After |
| :--- | :--- | :--- |
| 3-line bug in one function | 335 s · 56 turns · $0.339 | **77 s · 10 turns · $0.105** — inline, no subagents |