gentleman-programming/gentle-ai

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

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.

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 →

---

RDD — Check finished work at the right depth

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 →

---

Deterministic by design — Know the next valid step

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

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 set up a self-contained, bundled Gentle Shell with its exact Pi, its pinned Gentle AI, and Engram.

Docs →

---

17 agents — Keep the agent you already use

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 →

---

Also in the box

Every component, skill and preset: Full breakdown →

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 of the latest release, needs Go 1.25.10+
go install github.com/gentleman-programming/gentle-ai/v4/cmd/[email protected]

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 → · Signature verification: Release signing →

Documentation

Community

Everything labelled up-for-grabs is scoped, approved and unclaimed — pick one and it’s yours.

Built with Gentle-AI

Shipped something with Gentle-AI? Wear the rose. Paste this into your README and the badge links back here:

Prefer plain Markdown?

[![Built with Gentle-AI](https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/docs/assets/brand/built-with-gentle-ai.png)](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.

About the author

Built by Alan Buscaglia (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 →.

---

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.