<!-- markdownlint-disable-next-line MD041 -->
<a id="top"></a>
<div align="center">
<img width="100%" alt="Gentle-AI neon rose banner: the rose blooms in, the GENTLE-AI wordmark is written on, and the tagline Ecosystem, Framework, Workflows appears" src="docs/assets/brand/gentle-ai-banner.gif" />
<h1>Gentle-AI™</h1>
<p><strong>The deterministic engineering environment for the AI agent you already use.</strong></p>
<p>
<a href="https://github.com/Gentleman-Programming/gentle-ai/releases"><img src="https://img.shields.io/github/v/release/Gentleman-Programming/gentle-ai?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="Release"></a>
<a href="https://github.com/Gentleman-Programming/gentle-ai/stargazers"><img src="https://img.shields.io/github/stars/Gentleman-Programming/gentle-ai?style=for-the-badge&labelColor=1A1218&color=F095C8" alt="Stars"></a>
<img src="https://img.shields.io/badge/agents-18-F095C8?style=for-the-badge&labelColor=1A1218" alt="18 agents">
<img src="https://img.shields.io/badge/macOS%20%C2%B7%20Linux%20%C2%B7%20Windows-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="Platform">
<a href="LICENSE"><img src="https://img.shields.io/badge/MIT-D7A0B8?style=for-the-badge&labelColor=1A1218" alt="License: MIT"></a>
</p>
<p>
<a href="https://gentlemanprogramming.com/"><strong>Website</strong></a> •
<a href="docs/quickstart.md"><strong>Quickstart</strong></a> •
<a href="docs/intended-usage.md"><strong>Docs</strong></a> •
<a href="https://gentle-ai-wiki.gentlemanprogramming.com/"><strong>Wiki</strong></a>
</p>
<br/>
<p>
Your agent writes code, then forgets everything. It has no opinion about your project,
and no way to prove what it did beyond asking you to read every line.
<strong>Gentle-AI gives it memory, a workflow, and evidence.</strong>
</p>
<p>
<h3>See it in action</h3>
<p>
One prompt, from idea to reviewed commit: memory, workflow, and evidence in a real session.
</p>
https://github.com/user-attachments/assets/fa5c0cfe-06e7-4c0d-bd6e-8ac7cb934339
<p>Prefer Spanish subtitles?</p>
https://github.com/user-attachments/assets/6d2bc422-a4dd-4ecf-a04b-fcd3bea7fea9
</p>
<br/>
<!--
HERO SLOT — the only animation on this page. Features is all still: four
diagrams for the concepts, two captures as proof the thing runs. Motion is
spent once, here, right after the pitch lands.
Uncomment when docs/assets/features/hero-pi.gif exists. It is a real-time capture
of the complete Pi startup: banner, extensions, skills and startup output, never
trimmed. A stripped startup does not look like the real thing.
<img width="100%" src="docs/assets/features/hero-pi.gif" alt="Gentle-AI starting up inside Pi" />
<br/>
-->
<sub><strong>If Gentle-AI made your agent worth trusting, a star helps other people find it.</strong></sub>
<!--
sealed_token is a GitHub fine-grained token encrypted against Star History's
public key, so only the encrypted value is published here. It is required
because GitHub restricted the stargazers API to a repository's admins and
collaborators on 2026-06-30; without it the chart renders an error placeholder.
Regenerate it at https://www.star-history.com/?repos=Gentleman-Programming%2Fgentle-ai&type=date&legend=top-left
-->
<a href="https://www.star-history.com/?repos=Gentleman-Programming%2Fgentle-ai&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fgentle-ai&type=date&theme=dark&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fgentle-ai&type=date&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
<img width="620" alt="Star History Chart" src="https://api.star-history.com/chart?repos=Gentleman-Programming%2Fgentle-ai&type=date&legend=top-left&sealed_token=zwrd_DfwYZeJU7nhGYNtREEheKWYEslW_uzrqORlZ36v-JSMepdqGLkKExp1M-xbNq6t-ebVS5iM3WoPDO26tXbSGkjXC2Jo3kHQ3uNzlRkCrWoqRHkPVQXvosKciY109ObiwGV1z8aajyedcloppmekCGrvVKJb6KWxGLXW_mHcRAVIBZUOa4SzW75D" />
</picture>
</a>
<br/>
<sub><strong>WORKS WITH THE AGENT YOU ALREADY HAVE</strong></sub>
<strong><a href="docs/agents.md#pi">Pi</a></strong> ·
<strong><a href="docs/agents.md#opencode">OpenCode</a></strong> ·
<strong><a href="docs/agents.md#claude-code">Claude Code</a></strong> ·
<strong><a href="docs/agents.md#codex">Codex</a></strong> ·
<strong><a href="docs/agents.md#cursor">Cursor</a></strong> ·
<strong><a href="docs/agents.md#vs-code-copilot">VS Code Copilot</a></strong> ·
<strong><a href="docs/agents.md#gemini-cli">Gemini CLI</a></strong> ·
<strong><a href="docs/agents.md#kilo-code">Kilo Code</a></strong><br/>
<strong><a href="docs/agents.md#kimi-code">Kimi Code</a></strong> ·
<strong><a href="docs/agents.md#kiro-ide">Kiro IDE</a></strong> ·
<strong><a href="docs/agents.md#qwen-code">Qwen Code</a></strong> ·
<strong><a href="docs/agents.md#hermes">Hermes</a></strong> ·
<strong><a href="docs/agents.md#antigravity">Antigravity</a></strong> ·
<strong><a href="docs/agents.md#windsurf">Windsurf</a></strong> ·
<strong><a href="docs/agents.md#openclaw">OpenClaw</a></strong> ·
<strong><a href="docs/agents.md#trae">Trae</a></strong> ·
<strong><a href="docs/agents.md#conductor">Conductor</a></strong>
<sub>17 integrations · native configuration · <a href="docs/agents.md">compare capabilities →</a></sub>
</div>
<div align="center"><img src="docs/assets/brand/rose.png" width="28" alt="" /></div>
## Features
---
### Engram™ — Keep your project context
<img width="100%" src="docs/assets/diagrams/engram-memory.svg" alt="Three work sessions separated by a restart and by context compaction. Each break cuts the session layer but stops at the memory layer underneath. The first session saves a decision, the next one asks memory before asking you, and weeks later the same question is answered from memory instead of by re-reading the repository." />
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 →](docs/engram.md)**
---
### ODD — Keep small work small
<img width="100%" src="docs/assets/diagrams/odd-cycle.svg" alt="ODD authorizes and understands a request. Read-only work ends separately; authorized work stays lightweight when small or keeps a recoverable record when substantial, then is implemented, checked, and closed." />
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 →](docs/usage.md#organic-driven-development-odd)**
---
### 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 →](docs/trigger-rules.md)**
---
### 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](https://github.com/Gentleman-Programming/gentle-shell/pull/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](https://github.com/Gentleman-Programming/gentle-shell/pull/1723), [#1794](https://github.com/Gentleman-Programming/gentle-shell/pull/1794), [#1713](https://github.com/Gentleman-Programming/gentle-shell/issues/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 →](docs/usage.md#organic-driven-development-odd)**
---
### RDD — Check finished work at the right depth
<img width="100%" src="docs/assets/diagrams/rdd-review.svg" alt="How RDD checks a finished change. The exact change is frozen to a lineage, revision and target, then a read-only risk assessment picks the depth: passive gets a structural readback with zero reviewer lenses, medium gets one focused lens, high gets the canonical 4R — Risk, Resilience, Readability and Reliability. At most one bounded correction is allowed, and one exact acknowledgement closes the transaction. Delivery stays human-owned." />
Receipt-Driven Development (RDD) is on by default and opt-out: run `gentle-ai review mode disable` to turn it off. Explicit global or clone-local OFF choices remain OFF. Its point is that a review cannot drift: the candidate is frozen before anything reads it, so the evidence belongs to the exact version you are about to rely on — not to whatever the worktree looked like a moment later. The depth comes from that frozen candidate rather than from the model's judgment, and the result is informational. Commit, push and release stay your call.
Review is proportionate: an automatic review is due only for a high-risk candidate, and the agent can name the 4R lenses that fit what it touched — with a reason frozen alongside the authority — instead of paying for all four. Verification by risk tier covers the rest.
https://github.com/user-attachments/assets/9d3b176f-6e59-48f3-aba2-1196f20a4a6f
**[Docs →](docs/review-integration.md)**
---
### Deterministic by design — Know the next valid step
<img width="100%" src="docs/assets/diagrams/deterministic.svg" alt="A different agent, a different model and a brand-new session all converge on the gentle-ai binary. It reads the change state from files on disk and returns the only valid next transition, so no model votes on what comes next. The answer is always one of four public states: Working, Checking, Ready, or Needs your decision." />
A model that guesses the next step guesses differently tomorrow, and differently again for your teammate. That is the gap between a workflow and a suggestion. The **`gentle-ai` binary** owns native RDD review transitions; ODD guidance keeps ordinary work proportional to the request. Review evidence is bound to the candidate rather than a model's recollection.
**[Docs →](docs/trigger-rules.md)**
---
### Gentle Shell — A complete workspace for Pi
<img width="100%" src="docs/assets/features/gentle-shell.png" alt="Gentle Shell development workspace with the todo list and live context and spend information" />
Gentle Shell is a separate Pi integration package. Gentle AI configures supported agents; Gentle Shell owns its own Pi runtime, agents, and interface. Installing or updating this binary does not itself establish Pi behavior parity.
On a clean machine, the [Gentle Shell installers](https://github.com/Gentleman-Programming/gentle-shell#get-started) set up a self-contained, bundled Gentle Shell with its exact Pi, its pinned Gentle AI, and Engram.
**[Docs →](docs/pi.md)**
---
### 17 agents — Keep the agent you already use
<img width="100%" src="docs/assets/features/agents.png" alt="The installer configuring multiple agents" />
Gentle-AI brings its shared workflow to Pi, OpenCode, Claude Code, Codex, and thirteen more agents. Each integration uses that agent's native capabilities, so available features such as delegation and RDD review can differ.
**[Docs →](docs/agents.md)**
---
### Also in the box
| Component | What it does |
| :--- | :--- |
| **Skills library** | Loaded automatically when the task matches |
| **Context7 MCP** | Optional, selectable live framework and library documentation |
| **CodeGraph** | Read-only symbol graph of your codebase |
| **Security deny-list** | Blocks `~/.ssh`, `.env` and credential files |
| **Config backups** | Snapshotted before every single write |
| **Doctor** | `gentle-ai doctor` — read-only health report |
| **Personas** | Optional personas; Gentleman is a caring but rigorous mentor who guides you toward your goal |
| **Themes** | Gentleman and Gentleman-Cute |
| **Model assignment** | Configure supported agent and review-role models where available |
> **Every component, skill and preset: [Full breakdown →](docs/components.md)**
<div align="right"><a href="#top">Back to top</a></div>
<div align="center"><img src="docs/assets/brand/rose.png" width="28" alt="" /></div>
## Get started
```bash
# macOS (Homebrew)
brew install gentleman-programming/tap/gentle-ai
# macOS / Linux (curl)
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash
# Windows (PowerShell) — source install of the latest release, needs Go 1.25.10+
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.1.1
```
When the install directory is not on your `PATH` yet, `install.sh` adds one marked line (`# gentle-ai installer`) to the startup file your shell reads: `~/.zshrc` for zsh, `~/.bashrc` for bash on Linux, for bash on macOS the first existing of `~/.bash_profile`, `~/.bash_login`, or `~/.profile` (else `~/.bash_profile`), a `conf.d` file for fish, and `~/.profile` otherwise. `install.ps1` adds the directory to your user `Path`. Open a new terminal afterwards, or run the command the installer prints under `Current terminal:` to use `gentle-ai` in the current one. If the startup file is a symlink or cannot be edited, nothing is written and the installer prints the line to add yourself.
`go install` never changes your `PATH`. It puts `gentle-ai` in `$(go env GOBIN)` or, when that is unset, in `$(go env GOPATH)/bin` (usually `~/go/bin`), and Go's Linux and macOS setups do not add that directory for you. If `gentle-ai` is not found after `go install`, add it once and open a new terminal (use your `GOBIN` directory instead when it is set, and `~/.zshrc` for zsh):
```bash
echo "export PATH=\"$(go env GOPATH)/bin:\$PATH\"" >> ~/.bashrc
```
To install `main` with the `PATH` set up for you, use `install.sh --channel beta`, which runs `go install` from `main` and then adds its directory as described above:
```bash
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash -s -- --channel beta
```
```bash
gentle-ai # pick your agents, components and persona
gentle-ai doctor # verify — read-only, changes nothing
```
If `doctor` cannot read `state.json`, inspect the reported file and parent directory's access; for permission errors, check permissions and ownership. Keep the existing state file. For invalid JSON, restore a valid backup or repair the content while preserving your installation settings. Then re-run `gentle-ai doctor`; it never changes the file or its permissions.
Then use your agent normally. Your configs are snapshotted before every write, and **Gentle-AI never installs an AI agent for you** — it configures what you already have.
> **Beta channel and per-distro prerequisites: [Quickstart →](docs/quickstart.md) · Signature verification: [Release signing →](docs/release-signing.md#user-verification)**
<div align="right"><a href="#top">Back to top</a></div>
<div align="center"><img src="docs/assets/brand/rose.png" width="28" alt="" /></div>
## Documentation
| Where to go | What you'll find |
| :--- | :--- |
| **[Intended Usage](docs/intended-usage.md)** | The mental model. If you read one page, read this one. |
| **[Quickstart](docs/quickstart.md)** · **[Usage](docs/usage.md)** | Install, prerequisites, every CLI command and flag |
| **[Agents](docs/agents.md)** | Feature matrix and per-agent notes for all 17 |
| **[ODD](docs/usage.md#organic-driven-development-odd)** · **[Routing](docs/trigger-rules.md)** | Everyday direct and delegated work |
| **[Review](docs/review-integration.md)** · **[Architecture](docs/architecture/organic-rdd.md)** | The RDD contract, lifecycle and threat model |
| **[Engram](docs/engram.md)** · **[Components](docs/components.md)** | Memory commands, skills, presets and personas |
| **[Contributing](CONTRIBUTING.md)** · **[Codebase Guide](docs/CODEBASE-GUIDE.md)** | Extend or contribute |
| **[Telemetry](docs/telemetry.md)** | What we count, and how to turn it off |
<div align="right"><a href="#top">Back to top</a></div>
<div align="center"><img src="docs/assets/brand/rose.png" width="28" alt="" /></div>
## Community
Everything labelled [`up-for-grabs`](https://github.com/Gentleman-Programming/gentle-ai/issues?q=is%3Aissue+is%3Aopen+label%3Aup-for-grabs) is scoped, approved and unclaimed — pick one and it's yours.
<div align="center">
<a href="docs/community-roadmap.md"><img src="https://img.shields.io/badge/Community%20Roadmap-F095C8?style=for-the-badge&labelColor=1A1218&logo=readthedocs&logoColor=F095C8" alt="Community Roadmap"></a>
<a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/Contributing%20Guide-F095C8?style=for-the-badge&labelColor=1A1218&logo=git&logoColor=F095C8" alt="Contributing Guide"></a>
<a href="CONTRIBUTORS.md"><img src="https://img.shields.io/badge/Contributors-D7A0B8?style=for-the-badge&labelColor=1A1218&logo=github&logoColor=D7A0B8" alt="Contributors"></a>
<br/><br/>
<a href="CONTRIBUTORS.md">
<img width="100%" src="https://contrib.rocks/image?repo=Gentleman-Programming/gentle-ai&columns=16" alt="Gentle-AI contributors" />
</a>
<p><sub>This project exists because of these people.</sub></p>
</div>
<div align="right"><a href="#top">Back to top</a></div>
<div align="center"><img src="docs/assets/brand/rose.png" width="28" alt="" /></div>
## Built with Gentle-AI
Shipped something with Gentle-AI? Wear the rose. Paste this into your README and the badge links back here:
<div align="center">
<a href="https://github.com/Gentleman-Programming/gentle-ai">
<img width="280" src="docs/assets/brand/built-with-gentle-ai.png" alt="Built with Gentle-AI" />
</a>
</div>
```html
<a href="https://github.com/Gentleman-Programming/gentle-ai">
<img width="220" src="https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/docs/assets/brand/built-with-gentle-ai.png" alt="Built with Gentle-AI" />
</a>
```
Prefer plain Markdown?
```markdown
[](https://github.com/Gentleman-Programming/gentle-ai)
```
Keep the image URL exactly as shown — it is how I find and feature the projects that carry the badge.
<div align="right"><a href="#top">Back to top</a></div>
<div align="center"><img src="docs/assets/brand/rose.png" width="28" alt="" /></div>
## About the author
Built by [Alan Buscaglia](https://github.com/Gentleman-Programming) (Gentleman Programming): 15 years of enterprise architecture, a community of thousands of developers testing these tools daily, and one rule for AI-assisted work — **verifying beats generating**.
Teams adopting AI and finding it isn't working — resistance, everyone prompting their own way, no shared quality bar — can reach out about **[engagements built on these same open-source tools →](docs/consulting.md)**.
<div align="center">
<a href="https://gentlemanprogramming.com/"><img src="https://img.shields.io/badge/Website-F095C8?style=for-the-badge&labelColor=1A1218&logo=googlechrome&logoColor=F095C8" alt="Website"></a>
<a href="https://www.youtube.com/@GentlemanProgramming"><img src="https://img.shields.io/badge/YouTube-F095C8?style=for-the-badge&labelColor=1A1218&logo=youtube&logoColor=F095C8" alt="YouTube"></a>
<a href="https://github.com/Gentleman-Programming"><img src="https://img.shields.io/badge/GitHub-D7A0B8?style=for-the-badge&labelColor=1A1218&logo=github&logoColor=D7A0B8" alt="GitHub"></a>
<a href="mailto:gentleman@ohmybitz.com"><img src="https://img.shields.io/badge/Email-D7A0B8?style=for-the-badge&labelColor=1A1218&logo=maildotru&logoColor=D7A0B8" alt="Email"></a>
</div>
---
<div align="center">
<img src="docs/assets/brand/rose.png" width="56" alt="" />
<br/>
<h3>Gentle-AI is crafted with Gentle-AI</h3>
<br/><br/>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-F095C8?style=for-the-badge&labelColor=1A1218" alt="License: MIT"></a>
</div>
> **Trademark notice:** The Gentle AI™ and Engram™ names and logos are trademarks of Alan Buscaglia. Both marks are used throughout this document; the symbol appears on the first prominent mention of each, and this notice covers the rest. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See [TRADEMARKS.md](TRADEMARKS.md).