https://github.com/user-attachments/assets/fa5c0cfe-06e7-4c0d-bd6e-8ac7cb934339
https://github.com/user-attachments/assets/6d2bc422-a4dd-4ecf-a04b-fcd3bea7fea9
If Gentle-AI made your agent worth trusting, a star helps other people find it.
WORKS WITH THE AGENT YOU ALREADY HAVE
Pi ·
OpenCode ·
Claude Code ·
Codex ·
Cursor ·
VS Code Copilot ·
Gemini CLI ·
Kilo Code
Kimi Code ·
Kiro IDE ·
Qwen Code ·
Hermes ·
Antigravity ·
Windsurf ·
OpenClaw ·
Trae ·
Conductor
17 integrations · native configuration · compare capabilities →
Support the project
Sponsorship never buys rankings, default selections or endorsements; see TRADEMARKS.md.
Features
Engram™ — Keep your project context
The cost of a fresh session is not the tokens — it is you, re-explaining the same decisions every morning. Engram removes that: your agent writes down what it learns as it goes and reaches for it before it reaches for you, so context accumulates instead of resetting.
Docs →
ODD — Keep small work small
Small changes should not need a planning pipeline, and larger work should not lose its context between sessions. Organic Driven Development (ODD) keeps understood changes lightweight and gives substantial, authorized work one recoverable feature document. Questions, reviews and proposals stay read-only until you ask for a change. The agent explores before changing code, checks the results, and keeps progress current so work can resume without rebuilding the plan.
Tasks are sized by understanding, risk, and resumability, never by file count. A small task — understood, with contained risk, and resumable from the diff alone — runs inline: no subagents, no task document. Work becomes large only when it can't be resumed from the diff — several sessions, external waits, or requirements too long to survive compaction — never because of its size. The feature document of a large task holds your spec verbatim, and every handoff points at it instead of paraphrasing it.
https://github.com/user-attachments/assets/857a2195-34b8-4720-87af-f71bca3dec92
Docs →
Delegate for a reason — Not for size
A subagent costs a fresh session, uncached reads, and a handoff. So the orchestrator delegates only when it can name the reason:
| Reason | When it applies |
|---|
| Exploration | Understanding needs more than one inline batch (about 3 calls and 10k tokens) or more than about five sequential lookups; one read-only explorer returns a short map with path:line evidence |
| Parallel writers | Two or more independent units of behavior (code, tests, and docs together) with disjoint edit surfaces, each needing several minutes of work: several files or roughly 100+ changed lines, because a subagent spends one to two minutes reading before it writes. A delivery that depends on another is not independent |
| Context backstop | A long session hands its next bounded unit to a fresh worker |
| Independent verifier | A change that names a high-risk item (data, security, shared contracts, concurrency, delivery, or no test that would catch a regression); never a native risk tier alone, an unclear or failed assessment, or the model that wrote the change |
A trigger holds only when its condition truly holds; none holds by default, and when in doubt the parent works inline. Without a reason the parent writes inline, following its feature document. File count, task size, or a model price ratio never decide the route on their own.
https://github.com/user-attachments/assets/ccd96c9e-e0fd-4504-ad94-0302398f13a9
Docs →
Measured — What proportional routing changed
The routing rules above came from benchmarks, not intuition. These are Gentle Shell runs on 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 |
| Bug rooted in shared logic | 479 s · $0.361 | 276 s · $0.207 — one explorer |
| Data migration (high risk) | 559 s · $0.403 · needed a feedback round | 539 s · $0.555 · accepted on the first round — one independent verifier |
| 73-line spec, 26 hidden checks | Paraphrased handoffs: 13 failing, still 23/26 after two feedback rounds | Spec passed by reference (gentle-shell#1718) |
Against the same model in Codex CLI, with blind review of every solution, Gentle Shell was accepted on the first round in every cell and ranked higher on the medium (3 of 3 runs) and large tasks; it was close on the small one. The large task still took about three times longer (17.5–17.9 min vs 6.1 min) — that gap is open work. Sources: gentle-shell#1723, #1794, #1713.
Test-first by default — Prove each requested rule
ODD applies test-first development by default when a relevant runnable test and a clear expected outcome exist: capture a failing behavior test before implementation, make it pass, then refactor while tests stay green. Each requested rule gets one RED test, each touched existing command or option gets one test proving its previous behavior still holds, and nothing else is padded in. Without a meaningful runnable test, the agent explains the exception and runs applicable functional checks anyway.
Docs →
This is the beginning of the README. Read the rest at the original. Read the full README ↗
