README 未给出安装命令，需查阅 docs/quickstart.md；需先有已安装的受支持代理（如 Claude Code、Cursor、Codex 等）
gentle-ai
Gentleman-ProgrammingMIT活跃维护给 Claude Code、Cursor、Codex 等编码代理统一配置持久记忆、技能库、MCP 服务器和人格设定，避免被单一代理锁定。
Gentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.
v4.4.0发布于 2026-11-07 17:38 UTC8,724star +150 / 7 天889fork同步于 2026-11-10 17:31 UTC
给现有 AI 编码代理加记忆、工作流和证据的确定性工程环境
给 Claude Code、Cursor、Codex 等编码代理统一配置持久记忆、技能库、MCP 服务器和人格设定，避免被单一代理锁定。
核心能力
- 用 Engram 持久记忆跨会话保存项目决策
- 用 ODD 按理解度与风险决定任务轻重
- 按明确理由决定是否派子代理而非按规模
- 默认测试先行，每条需求先写失败测试
- RDD 按风险分级对完成改动做只读审查
容易踩的坑
内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README
- v4.4.0v4.4.0 — Antigravity 1.4 Parity, Faster Gentle Shell Launches and Safer Windows Restores最新正式版2026-11-07 · 2026-11-07 17:38 UTC
Gentle AI v4.4.0 is a minor release over v4.3.1. Restores and rollbacks now work when Windows redirects
%APPDATA%outside the profile, and a workspace uninstall snapshot can be restored on its own. JSON and JSONC configs that start with a UTF-8 BOM keep the user's keys instead of being merged into an empty object. The Windows Full Suite is green again and now runs on every pull request. Antigravity (agy 1.4) reaches parity with native Judgment Day agents, per-role model tiers and guidance that fits agy's 24 KB rule budget. Gentle Shell provisions Stable from a reviewed gentle-pi supplier list, launches in a fraction of the time, and publishesgson Windows. Codex honorsCODEX_HOMEend to end. The provider contract stays byte-frozen at1.4.0.Provenance
- Previous stable:
v4.3.1→2dba7784114fff57864519c4c0d067e952a8c98b - Release target:
v4.4.0→55240afb100ad6d2ef5fbe16f7be33a7693f77ad - Release workflow: run 42396346091
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.4.0
What's new
Antigravity 1.4 parity
Antigravity now receives the Judgment Day native agents (
jd-judge-a,jd-judge-b,jd-fix-agent) that Claude Code, Cursor and Kiro already had. Their model tier (inherit,flash_lite,flash,pro) can be picked per role in the installer and changed later from Configure Models. Gentle AI guidance is rendered as owned agy rule files that each stay under agy's 24 KB limit, and legacy Gentle AI sections inGEMINI.mdare migrated into them.Included work: #5931, #5938, #5939, #5940, #5941, #5942 (issue #5930).
Gentle Shell Stable follows a reviewed gentle-pi supplier list
Gentle Shell now ships a reviewed list of gentle-pi releases, each pinned by its npm tarball SRI and installer hash, and reads it live with a fail-safe fallback. Stable installs provision the newest reviewed release, the Windows provisioner reads the same list, installs without a list authenticate supplier files at launch, and the Stable update check detects an outdated gentle-pi by its installed version and targets the newest listed release. gentle-pi 4.5.1 is the first reviewed entry.
Included work: #5849, #5852, #5853, #5863, #5871, #5873, #5876 (issue #5845) by @decode2.
Faster Gentle Shell launches
Standalone
gentle-shell/gslaunches spent 13 to 19 seconds re-verifying unchanged bytes on every start. Pinned binaries, the retained Main source and the installed graph are now checked against ctime-bound stamp caches and receipts that a prior full audit produced, so every check stays as strict while unchanged bytes are no longer re-read. Main launches drop to about 3.3 seconds and Stable launches from 2.81 to 0.33 seconds; a timing probe on the Windows runtime lane measured the Windows launch boundary at about 52 ms warm.Included work: #5920 (issue #5917), #5960, [#5922](https://github.com/Gentleman-Programming/gentle
- Previous stable:
- v4.3.1v4.3.1 — Gentle Shell Installs and Updates from the TUI on Every Platform2026-10-27 · 2026-10-27 18:35 UTC
查看更新说明
Gentle AI v4.3.1 is a minor release over v4.2.0. It supersedes the
v4.3.0tag, whose release run stopped in preflight on an untidygo.modbefore publishing anything;v4.3.0has no release or assets. Gentle Shell now installs, manages and updates from the TUI on Linux, macOS and Windows: Linux stable delivery lands with its own installer experience, macOS gains TUI installs with CodeGraph and Main preview, and every platform updates only the components that changed while keeping operator state. It also adds the GitHub Copilot CLI agent adapter, advances the reviewed boundary on acknowledgement, and fixes a Windows upgrade regression that would have hidden existing Gentle Shell installations. The provider contract stays byte-frozen at1.4.0.Provenance
- Previous stable:
v4.2.0→4acaf4241beae1e0c977c92dfe406a270f8d40de - Release target:
v4.3.1→2dba7784114fff57864519c4c0d067e952a8c98b - Release workflow: run 40559437366
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.4.0
What's new
Gentle Shell on Linux
Linux stable delivery begins with an opt-in installer UI. The TUI hands the embedded installation off after restoring the terminal, binds preference profiles to a physical confirmation, stages private canonical preferences before bootstrap, and composes verified private installation and MCP stages. Root installs require an explicit opt-in with a typed risk warning, and the private kernel check names its refusal causes.
Included work: #5558, #5559, #5562, #5563, #5564, #5567, #5570, #5574, #5582, #5585, #5596, #5644, #5730 (issue #5727), #5716 (issue #5713).
Gentle Shell launchers and PATH
Installs publish the
gsandgentle-shelllaunchers, report occupied names instead of overwriting them, and show the publication result and a PATH hint on completion.~/.local/binis put on PATH after the launcher is published, andinstall.shandinstall.ps1put the gentle-ai install directory on PATH.Included work: #5742, #5743 (issue #5740), #5760 (issue #5758), #5759.
Gentle Shell from the TUI on macOS
The TUI installs Gentle Shell on macOS and applies canonical preferences, installs CodeGraph on macOS arm64, and installs and switches to the Main preview SDK. The existing-Pi target sets Pi's own
fd/rgaside and restores the agent exactly on uninstall.Included work: #5748, #5752, #5754, #5756.
Scoped updates that keep operator state
Installations record c
- Previous stable:
- v4.2.0v4.2.0 — Gentle Shell's Routing Ships in the Provider Contract2026-10-15 · 2026-10-15 16:59 UTC
查看更新说明
Gentle AI v4.2.0 is a minor release. It publishes Gentle Shell's ODD routing block from gentle-ai, so Pi's workflow wording now has a single source, and it ships the orchestrator routing changes measured on the Gentle Shell bench: conditional delegation triggers, a named-risk independent verifier, commits per reviewable slice, and small tasks kept inline. It also fixes three review-mode defects on Windows and long local paths. The provider contract moves from
1.3.0to1.4.0to add theroutingbundle entry.Provenance
- Previous stable:
v4.1.1→898d3976e8049a7238eaa7de60bff325c30d2b3d - Release target:
v4.2.0→4acaf4241beae1e0c977c92dfe406a270f8d40de - Release workflow: run 38771798911
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.4.0
What's new
Gentle Shell's routing block ships in the provider contract bundle
RenderRouting(pi)now emits Gentle Shell's own ODD step lines (steps 1-7, phase reporting, and resume) verbatim, and the review provider-contract bundle publishes that block asrouting/pi.mdunder a new manifest fieldrouting, introduced in contract1.4.0with the same rule asorchestration. Every other agent's rendered routing is byte-identical to v4.1.1, pinned by per-runtime sha256 goldens. Gentle Shell can vendor the block under its existing SHA lock instead of hand-copying it; gentle-ai still writes nothing into Pi's prompt files.Included work: #5537, #5539 (issue #5536).
Commit per reviewable slice, small tasks stay inline
ODD routing now commits work units in reviewable slices of about 400 authored changed lines on the feature branch and keeps small tasks inline, without feature documents or delegated writers, unless the user asks for them.
Included work: #5530 (issue #5529).
Breaking changes
No breaking changes are declared for v4.2.0. The module path stays at
/v4and no review CLI flag changed. The provider contract moves from1.3.0to1.4.0additively: manifests from1.2.0and1.3.0withoutroutingstill validate, while the1.4.0verifier accepts only archives whose bundle README matches this release (the same rule applied whenorchestrationwas added). Installed agent guidance and orchestrator instructions changed, so rungentle-ai sync.Upgrade now
brew upgrade gentle-ai gentle-ai syncWindows and other source installs:
go install github.com/gentleman-programming/gentle-ai/v4/cmd/[email protected] gentle-ai syncRun
gentle-ai syncafter upgrading so managed agent, reviewer, and runtime assets match the installed binary, including the rewritten ODD routing and delegation triggers.What was fixed
Delegation triggers fire only on their named conditions
Delegation triggers were read as always-on, so orchestrators delegated and verified small, low-risk work. The triggers are now conditional, the independent verifier runs only for a named high-risk item, and the differential check preserves existing behavior through a PRESERVE pointer.
Included work: #5522 (issue #5521).
Transport refusals name the user-owned exit
Review transport refusal messages did not say how the user could leave the refused state. They now name the user-owned exit, and Codex's dormant transport is declared honestly.
Included work: #5523 (issue #2573).
Tool artifacts and test scratch stay out of delivered diffs
CodeGraph and test scratch files could enter delivered diffs. CodeGraph keeps its index excluded locally and guidance keeps test scratch outside the wor
- Previous stable:
- v4.1.1v4.1.1 — Consistent Module Checksum for the v4.1 Line2026-10-12 · 2026-10-12 12:19 UTC
查看更新说明
Gentle AI v4.1.1 is a hotfix release with the same code as v4.1.0. The first
v4.1.0tag failed its release preflight before anything was published and was then cut again on the fixed commit. The Go module proxy and checksum database had already recorded the firstv4.1.0commit, so ago installthat downloadsv4.1.0straight from GitHub (for example withGOPROXY=direct) fails checksum verification. v4.1.1 publishes the released commit under a version that every download path resolves to the same bytes. The provider contract stays at1.3.0.Provenance
- Previous stable:
v4.1.0→898d3976e8049a7238eaa7de60bff325c30d2b3d - Release target:
v4.1.1→898d3976e8049a7238eaa7de60bff325c30d2b3d - Release workflow: run 38246837247
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.3.0
What's new
No new features are declared for v4.1.1. See the v4.1.0 notes for what the v4.1 line brings.
Breaking changes
No breaking changes are declared for v4.1.1. The module path stays at
/v4, the provider contract stays at1.3.0, and no review CLI flag changed. The breaking changes declared for v4.1.0 still apply to anyone upgrading from v4.0.x.Upgrade now
brew upgrade gentle-ai gentle-ai syncWindows and other source installs:
go install github.com/gentleman-programming/gentle-ai/v4/cmd/[email protected] gentle-ai syncRun
gentle-ai syncafter upgrading so managed agent, reviewer, and runtime assets match the installed binary. Source installs should use@v4.1.1rather than@v4.1.0.What was fixed
One checksum for the v4.1 release
The first
v4.1.0tag pointed atcbdbe97d1, whosego.modwas not tidy, so the release preflight stopped before publication. After the fix, the tag was deleted and cut again at898d3976e. In the meantimeproxy.golang.organdsum.golang.orghad recordedv4.1.0ascbdbe97d1, and those records are permanent. Installs through the default Go proxy still work, because they receive the recorded source, which differs only by one// indirectmarker ingo.mod. Installs that download from GitHub directly fail withchecksum mismatch. v4.1.1 tags the released commit under a new version, so the proxy, the checksum database, GitHub, and the signed archives all agree.Included work: #5474 (issue #5473).
Numbers
0 non-merge commits, 0 merged pull requests, and 0 unique GitHub PR authors since v4.1.0. v4.1.1 re-tags the v4.1.0 release commit.
Install
brew install Gentleman-Programming/tap/gentle-aior
go install github.com/gentleman-programming/gentle-ai/v4/cmd/[email protected]Windows remains supported through the Go installation path, which needs Go 1.25.10 or newer. Official Windows binary archives and Scoop publication remain unavailable; Windows upgrades fail closed to Go-based guidance rather than downloading unsigned binaries. The
scripts/install.shandscripts/install.ps1installers resolve the latest release tag and derive the/v4module path from it.Signed platform archives below:
linux_amd64,linux_arm64,darwin_amd64,darwin_arm64, withchecksums.txtand its minisign signature.Full changelog: https://github.com/Gentleman-Programming/gentle-ai/compare/v4.1.0...v4.1.1
- Previous stable:
- v4.1.0v4.1.0 — Proportionate Native Review and a Clean SDD Exit2026-10-12 · 2026-10-12 11:17 UTC
查看更新说明
Use v4.1.1 for source installs. It is the same code with one consistent Go module checksum;
go install [email protected]fails checksum verification when it downloads from GitHub directly.Gentle AI v4.1.0 is a minor release. Native review becomes proportionate: automatic review starts only for high-risk changes, the agent can choose which review lenses to run for what it touched, and an acknowledged passive delta is no longer offered again. The SDD retirement now also cleans up installed systems: Gentle-owned SDD agents, skills, commands, hooks, and profiles are removed on sync and install. OpenCode settings, plugins, launchers, and permissions are hardened, the Windows Full Suite is green again, and Gentle Shell installer candidates ship for Linux, Windows 11 x64, and macOS. The provider contract moves from
1.2.0to1.3.0, an additive minor bump for agent lens selection.Provenance
- Previous stable:
v4.0.0→ff77164d4 - Release target:
v4.1.0→898d3976e8049a7238eaa7de60bff325c30d2b3d - Release workflow: run 38240234416
- Verification: preflight, release, and verify jobs all succeeded.
- Provider contract:
1.3.0(was1.2.0)
What's new
Proportionate, intent-aware native review
Native review now scales with what changed.
review assessreportsreview_due: trueonly forhighrisk. Amediumcandidate reportsreview_due: falsewithunder_budget, whatever itschanged_lines, because size is a reviewer prompt budget, not risk. Review findings are graded with consistent severity and judged against the change's intent. START and the STATUS preflight accept--lenses <r,...> --lenses-reason <text>, so the agent can name the 4R lenses that fit what it touched instead of taking the tier default. Ahighcandidate may run fewer than four lenses. The selection and its reason are frozen with the authority, recovery successors inherit them, and a resumed START on an active lineage keeps the frozen selection. Callers detect support through the newstart_lens_selectioncapability. After a base-diff candidate is acknowledged, review detects the passive delta that follows and stops offering review for it, without hiding a review that is still live.Included work: #5345 (issue #5344), #5348 (issue #5347), #5351 (issue #5350), #5322 (issue #4739).
ODD orchestration delegates for a reason
The orchestrator delegates when it has a named reason, not because a task is large. Work is delegated when understanding exceeds the inline evidence budget, when two or more independent writers have separate edit surfaces, or when a high-risk change needs an independent verifier. File count and task size alone never decide the route. Test discipline and the verify handoff now reach every runtime, and OpenCode verification uses probes derived from the spec and tests each requirement.
Included work: #5250 (issue #5249).
Gentle Shell installer candidates
gentle-ai shell installgains a TUI and an inspect-then-confirm command line for installing Gentle Shell. It supports a Separate mode on Linux amd64 (with a Shared mode for an existing owned Pi prefix) and on Windows 11 x64, and a user installer on macOS. These are candidates, not release-qualified paths. The Linux guide is marked "source candidate only, not a release guide", and the Windows guide states that real installation and terminal restoration remain unverified. The parent TUI now consumes a selection-only shell API.Included work: [#5242](https://github.com/
- Previous stable:
用户点评
登录用户的真实使用记录，可按版本和硬件筛选共 0 条
还没有人点评。第一个说出真实体验的人最有价值。
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 →
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.
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
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
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.
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
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.
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.
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.
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 →
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]
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):
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:
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash -s -- --channel beta
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
| Where to go | What you'll find |
|---|---|
| Intended Usage | The mental model. If you read one page, read this one. |
| Quickstart · Usage | Install, prerequisites, every CLI command and flag |
| Agents | Feature matrix and per-agent notes for all 17 |
| ODD · Routing | Everyday direct and delegated work |
| Review · Architecture | The RDD contract, lifecycle and threat model |
| Engram · Components | Memory commands, skills, presets and personas |
| Contributing · Codebase Guide | Extend or contribute |
| Telemetry | What we count, and how to turn it off |
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:
<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?
[](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.