gentle-ai

<!-- 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-16-F095C8?style=for-the-badge&labelColor=1A1218" alt="16 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> &bull; <a href="docs/quickstart.md"><strong>Quickstart</strong></a> &bull; <a href="docs/intended-usage.md"><strong>Docs</strong></a> &bull; <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> <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/> -->

_{<strong>If Gentle-AI made your agent worth trusting, a star helps other people find it.</strong>}

<!-- 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…[redacted]" /> <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…[redacted]" /> <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…[redacted]" /> </picture> </a> <br/>

_{<strong>WORKS WITH THE AGENT YOU ALREADY HAVE</strong>}

<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>

_{16 integrations · native configuration · <a href="docs/agents.md">compare capabilities →</a>}

</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 →

---

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. The agent explores before changing code, checks the results, and keeps progress current so work can resume without rebuilding the plan.

Docs →

---

Strict TDD — Prove behavior when enabled

ODD uses the configured TDD mode and exact test runner. When Strict TDD is enabled, capture a failing behavior test before implementation, make it pass, then refactor while tests stay green. When disabled, run applicable functional checks anyway. The presence of tests alone does not enable Strict TDD.

Docs →

---

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.

Docs →

---

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 →

---

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.

Docs →

---

16 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 twelve more agents. Each integration uses that agent's native capabilities, so available features such as delegation and RDD review can differ.

Docs →

---

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 →

<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

# 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, needs Go 1.25.10+
go install github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai@latest

gentle-ai          # pick your agents, components and persona
gentle-ai doctor   # verify — read-only, changes nothing

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, signature verificati