Quick start
First time here? Follow Install for prerequisites and the platform-specific binary command, then:
# Pick your agents, components and persona
gentle-ai
# Verify the installation
gentle-ai doctor
Table of contents
What is Gentle-AI?
You installed Claude Code, OpenCode, Cursor or Codex. It writes code — but it forgets everything between sessions, has no opinion about how your project works, and gives you no way to check its work beyond reading every line yourself.
Gentle-AI is an ecosystem configurator. It takes the agent runtime already on your machine and equips it with persistent memory, a planning workflow, a curated skill library, MCP tool servers, model routing, a teaching-oriented persona, and an optional evidence-based review step.
|
Before
"I installed an AI agent, but it's just a chatbot that writes code."
|
After
The agent remembers your decisions, follows your project's conventions, picks a working style that matches the size of the task, and can produce reviewable evidence for what it changed.
|
Who it's for
- Developers who already use an AI coding agent daily and want it to stop starting from zero.
- Teams that want consistent agent behavior across different agent runtimes and machines.
- Anyone who wants to verify what an agent did instead of trusting its summary.
What it is not
[!IMPORTANT]
Gentle-AI never installs an AI agent for you. It configures runtimes that are already present. If you select an agent it cannot detect, it refuses and prints the exact command you'd run yourself — it will not silently install software on your machine.
What you get
Gentle-AI installs a set of components. You pick them individually, or take a preset.
|
Engram™ · Recommended
Persistent memory across sessions — decisions, bug fixes, and context survive restarts.
|
Skills · Recommended
A curated library of coding skills the agent loads when the task matches.
|
|
Persona · Optional
A teaching-oriented voice (Gentleman or neutral), or your own custom persona.
|
SDD · Optional
Spec-Driven Development — a planning workflow for substantial features.
|
|
Context7 · Optional
An MCP server that fetches live framework and library documentation.
|
Permissions · Optional
Security-first guardrails, including a deny list for ~/.ssh, .env, and credential files.
|
|
GGA · Optional
Gentleman Guardian Angel — an AI provider switcher.
|
Theme · Optional
Selectable Gentleman and Gentleman-Cute themes for Claude Code and OpenCode.
|
Presets bundle these for you
| Preset |
Includes |
Dev Stack + Polish full-gentleman |
Every component and every skill |
Dev Stack ecosystem-only |
Engram, SDD, Skills, Context7, GGA + all skills |
Memory Only minimal |
Engram and SDD skills |
| Custom |
You choose; existing persona and settings stay untouched |
Full breakdown: Components, Skills & Presets.
Which agents it works with
Gentle-AI configures each agent using that agent's own native features, so capabilities differ. Delegation model tells you whether the agent can hand work to focused sub-agents or runs everything in one conversation.
Full delegation can hand work to focused sub-agents
| Agent |
Mechanism |
Key feature |
| Claude Code |
Task tool |
Sub-agents, output styles |
| OpenCode |
Multi-mode overlay |
Per-phase model routing |
| Kilo Code |
Multi-mode overlay |
OpenCode-compatible config in ~/.config/kilo |
| Gemini CLI |
Experimental |
Custom agents in ~/.gemini/agents/ |
| Cursor |
Native subagents |
10 SDD agents in ~/.cursor/agents/ |
| VS Code Copilot |
runSubagent |
Parallel execution |
| Codex |
Native multi-agent |
CLI-native TOML config; enabled by default with solo-agent fallback |
| Antigravity |
Dynamic subagents |
Mission Control uses define_subagent + invoke_subagent for SDD phases |
| Kimi Code |
Native custom agents |
Modular prompt templates in ~/.kimi |
| Kiro IDE |
Native subagents |
Native ~/.kiro/agents/ + steering orchestration |
| Qwen Code |
Native sub-agents |
Slash commands, ~/.qwen/commands/, auto_edit mode |
| Pi |
Package-managed subagents |
First-class gentle-pi harness with Pi-native persona/models, SDD, and Engram memory |
| Hermes |
delegate_task |
Ephemeral fresh-context workers; YAML MCP config and SOUL.md persona |
Solo-agent runs everything in one conversation
| Agent |
Key feature |
| Windsurf |
Plan Mode, Code Mode, native workflows |
| OpenClaw |
Workspace-first AGENTS.md / SOUL.md with global MCP config |
| Trae |
Desktop app by ByteDance; ~/.trae/skills/ + OS-specific rules |
Hermes must be installed manually first. Gentle-AI detects and configures the existing runtime; it does not install Hermes.
[!NOTE]
Pi is package-managed, not just configured. Selecting Pi installs the first-class gentle-pi harness, which owns Pi-native persona and model controls, SDD assets, chains, and memory wiring.
[!NOTE]
This project supersedes Agent Teams Lite (now archived). Everything ATL provided is included here with better installation, automatic updates, and persistent memory.
Per-agent details and the complete feature matrix: Agents.
Install
Step 1 — Check prerequisites
| Requirement |
Why |
| Node.js 18+ and npm |
Required by gentle-ai install on every platform. It warns if either is missing and prints a distro-specific hint — it does not install them for you. |
| Git 2.38+ |
Used for project detection and review scoping. |
| Go 1.25.10+ |
Required on Windows, and anywhere you install from source. |
| Your AI agent |
Already installed and on your PATH. Gentle-AI configures it; it does not install it. |
Per-distro hints: Prerequisites.
Step 2 — Install the binary
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash
Windows (PowerShell)
go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest
[!WARNING]
On Windows, install from source — this is the supported path. Windows is a fully tested platform — the complete suite runs on its CI lane — but official Windows binary distribution and Scoop are unavailable. Windows installation and upgrades require Go 1.25.10+ and fail closed to source-install guidance; they never download an unsigned Gentle AI executable or execute a remote update script.
Expected result: gentle-ai version prints a version number.
Launch the interactive TUI:
gentle-ai
Select your agent(s), your components (or a preset), and your persona.
Expected result: Gentle-AI writes config files into each selected agent's global config directory — system prompts, skills, SDD agents, persona files and MCP entries. Your previous configs are snapshotted first (see Backups).
Step 4 — Verify
gentle-ai doctor
Expected result: a read-only health report covering tool binaries, state.json, Engram reachability and disk space. It also classifies broken managed paths — dangling ancestor symlinks, config symlink loops and unreadable managed files. Nothing is modified. Run this any time something looks wrong.
You are now ready to use your agent normally.
How your agent decides how to work
This is the core idea, and it applies to every configured agent — even if you never enable SDD or review.
You ask for an outcome. The agent picks the smallest route that gets there.
It does not escalate ceremony because a task "feels big".
| Situation |
What the agent does |
| Understanding needs 1–3 files, or one mechanical change is already understood |
Direct inline — just does the work |
| Understanding needs 4+ files, reading prepares a write, broad research is needed, or 2+ non-trivial files change |
Delegated direct — one narrow explorer or one focused writer, no extra artifacts |
| Durable proposal, spec, design and task artifacts would materially reduce real ambiguity |
Offers optional SDD — selected only after you ask or accept the proposal |
| Commit, push, PR, or release |
Follows ordinary repository policy |
Three rules worth internalizing:
- Size never selects SDD. File count, changed lines and perceived risk never force the heavier route on their own. Only an explicit request or an accepted proposal does.
- Routing does not decide review strength. They are independent choices.
- Per-action workers don't change the route. Running tests, builds or installs in a fresh worker keeps the selected route intact.
Deep dive: Organic Implementation Routing.
Optional: Spec-Driven Development (SDD)
What it is
SDD is a planning workflow for substantial features. Instead of jumping straight into code, the agent explores the codebase, proposes an approach you approve, writes requirements, designs the architecture, breaks it into ordered tasks, implements, then independently verifies the result against what was agreed.
When you'd want it
When the work is ambiguous enough that durable written artifacts — a proposal, a spec, a design, a task list — would genuinely reduce that ambiguity. For a bug fix or a small feature, it's overhead.
How you use it
You don't learn the phases. Say "use SDD" and the agent starts the workflow, or accept it when the agent offers. You review and approve at the decision points.
[!NOTE]
In Claude Code, every SDD command uses the /gentle-sdd-* prefix — for example, /gentle-sdd-new and /gentle-sdd-continue. Other runtimes keep the bare /sdd-* names.
Where the artifacts live
SDD artifacts can live in three places, chosen at install time:
| Store |
Best for |
| Engram |
Cross-session memory, no files in the repo |
| OpenSpec |
Versioned files committed alongside your code |
| Hybrid |
Both |
The store you declare is authoritative: phase agents are handed the locations to read and never guess where artifacts live.
Good to know
- Research lane. Immediately after Explore, you can select SDD Research when the proposal needs external evidence. This optional lane requires an exact documentation or open-web grant and records auditable evidence with source mappings. Once selected, Research must finish before Propose.
- Strict TDD. When Strict TDD is active, SDD apply works test-first, and SDD verify audits the RED/GREEN evidence before it passes.
- Independent from review. SDD status v2 runtime state is independent from review. No review binding, receipt or gate controls SDD Archive or delivery; ordinary repository policy remains authoritative for delivery.
How the SDD cycle works internally
flowchart TD
A["User: sdd-new / sdd-explore<br/>(gentle-sdd-* in Claude Code)"] --> B["Explore<br/>investigate codebase and approaches"]
B --> BR{"External research<br/>selected?"}
BR -->|"yes"| BX["Research<br/>auditable external evidence<br/>exact grant · source mappings"]
BR -->|"no"| C["Propose<br/>intent · scope · approach"]
BX --> C
C --> D{"User approves<br/>the proposal?"}
D -->|"no"| B
D -->|"yes"| E["Spec<br/>requirements + scenarios"]
E --> F["Design<br/>architecture decisions"]
F --> G["Tasks<br/>ordered deliverable checklist"]
G --> H["Apply<br/>sub-agent implements against specs<br/>(sdd-attempt acquire/settle · CAS · budgets)"]
H --> Q["Verify<br/>independent verification against<br/>spec · design · tasks"]
Q -->|"passes"| R["Archive<br/>merge delta-specs · close the cycle"]
Q -->|"fails"| H
Q -.->|"optional, informational"| I["RDD review offer"]
subgraph RDD["RDD — same machine as the organic route"]
I --> J{"Risk"}
J -->|"low"| K["Structural readback"]
J -->|"medium / high"| L["1 lens or 4R + consent"]
L --> M{"Severe findings?"}
M -->|"yes"| N["One bounded correction<br/>+ fix validator"]
M -->|"no"| O["Review outcome: approved<br/>(informational)"]
K --> O
N -->|"validates"| O
N -->|"fails"| P["Escalated → recover"]
O --> AK["review.acknowledge-approved<br/>only the exact acknowledgement<br/>burns/closes the lineage"]
end
R --> S["Ordinary repository policy"]
S --> T["Commit → Push → PR"]
style O fill:#2D4F67,color:#fff
style P fill:#B8860B,color:#fff
style T fill:#2D4F67,color:#fff
Reference: Intended Usage and OpenSpec Config.
Optional: Receipt-Driven Development (RDD)
[!IMPORTANT]
RDD is opt-in and off by default. Nothing below happens until you run gentle-ai review mode enable --scope global.
The problem it solves
An agent tells you "I fixed it and the tests pass." You have no way to check that claim except reading the whole diff yourself. RDD replaces agent narration with evidence the system can derive independently.
The vocabulary
You need six terms. Each builds on the last:
| Term |
Meaning |
| Candidate |
The exact set of bytes being reviewed — one specific change, nothing else |
| Freeze |
Locking those bytes at the start, so reviewers and the code can't drift apart mid-review |
| Lens |
One focused reviewer perspective. The four canonical ones are Risk, Resilience, Readability and Reliability ("4R") |
| Correction |
At most one bounded round of fixes for severe findings — there is no loop-until-clean |
| Outcome |
The result of the review. It is informational: it records evidence, it does not authorize or block anything |
| Acknowledgement |
The explicit confirmation that your agent received the outcome. Until it runs, the review is approved but not finished |
What it actually does
Once implementation finishes, RDD freezes the candidate and picks review effort from evidence, not from size:
| Risk (frozen at start) |
Review performed |
| Low |
Structural readback — 0 lenses, silent. A passive documentation change is approved right at the start |
| Medium |
1 focus lens, with consent |
| High |
All four lenses (4R), with consent and a |
Gentle-AI 会为你已经安装的 AI 编程助手（Claude Code、Cursor、OpenCode、Codex、Pi 等）进行配置，添加持久化记忆、精选技能库、MCP 工具服务器、面向教学的角色设定，以及可选的基于证据的审查步骤。