Gentle Ai

Gentle-AI™

Turn the AI coding agent you already use into a configured engineering environment.

Website • Wiki • Engram

Quick start

First time here? Follow [Install](#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?](#what-is-gentle-ai)
• [What you get](#what-you-get)
• [Which agents it works with](#which-agents-it-works-with)
• [Install](#install)
• [How your agent decides how to work](#how-your-agent-decides-how-to-work)
• [Optional: Spec-Driven Development (SDD)](#optional-spec-driven-development-sdd)
• [Optional: Receipt-Driven Development (RDD)](#optional-receipt-driven-development-rdd)
• [Keeping it up to date](#keeping-it-up-to-date)
• [Reference](#reference)
• [Documentation](#documentation)
• [Community](#community)
• [About the author](#about-the-author)

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.

Back to top

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](docs/components.md).

Back to top

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](docs/pi.md) 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](docs/agents.md).

Back to top

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](docs/quickstart.md#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.

Step 3 — Configure your agents

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](#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.

Back to top

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](docs/trigger-rules.md).

Back to top

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(gentle-sdd-* in Claude Code)"] --> B["Exploreinvestigate codebase and approaches"]
    B --> BR{"External researchselected?"}
    BR -->|"yes"| BX["Researchauditable external evidenceexact grant · source mappings"]
    BR -->|"no"| C["Proposeintent · scope · approach"]
    BX --> C
    C --> D{"User approvesthe proposal?"}
    D -->|"no"| B
    D -->|"yes"| E["Specrequirements + scenarios"]
    E --> F["Designarchitecture decisions"]
    F --> G["Tasksordered deliverable checklist"]
    G --> H["Applysub-agent implements against specs(sdd-attempt acquire/settle · CAS · budgets)"]
    H --> Q["Verifyindependent verification againstspec · design · tasks"]
    Q -->|"passes"| R["Archivemerge 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+ fix validator"]
        M -->|"no"| O["Review outcome: approved(informational)"]
        K --> O
        N -->|"validates"| O
        N -->|"fails"| P["Escalated → recover"]
        O --> AK["review.acknowledge-approvedonly the exact acknowledgementburns/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](docs/intended-usage.md) and [OpenSpec Config](docs/openspec-config.md).

Back to top

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

If reviewers find severe findings caused by the candidate itself, RDD permits one bounded correction, then a read-only validator checks it. Pre-existing findings become follow-ups, not blockers.

Approval waits to be acknowledged

> In stable v2.6.0, a review does not end when it is approved. It ends when your agent confirms it received that approval.

Why this exists: previously, approval destroyed its own authority and returned a response. If that response never reached the host — a crash, a dropped connection — the review was

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Gentleman-Programming
• Source: Gentleman-Programming/gentle-ai
• License: MIT
• Homepage: https://gentle-ai.gentlemanprogramming.com/

Install and usage instructions live in the source repository linked above.