Important
RDD is unstable. Receipt-Driven Development started in gentle-ai v1.47.0. Every release from v1.47.0 onward is part of the RDD development line and may change while remaining issues are fixed.
For a stable installation without RDD, use the last version before RDD, v1.46.0:
go install github.com/gentleman-programming/gentle-ai/cmd/gentle-ai@v1.46.0To test the latest released RDD build, use @latest. Use @main only for unreleased development changes. See the full RDD version policy.
The v1.46.0 pin above uses the unsuffixed import path; every v2.x install uses github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai, because Go requires the /vN suffix for major version 2 and above.
Gentle-AI is NOT an AI agent installer. Most agents are easy to install. It is an ecosystem configurator that equips the AI coding agent(s) you already use with persistent memory, Spec-Driven Development (SDD), curated skills, MCP servers, model routing, a teaching-oriented persona, and bounded native review.
Before: "I installed Claude Code / OpenCode / Cursor, but it's just a chatbot that writes code."
After: Your agent now has memory, skills, workflow, MCP tools, and a persona that actually teaches you.
| Agent | Delegation Model | Key Feature |
|---|---|---|
| Claude Code | Full (Task tool) | Sub-agents, output styles |
| OpenCode | Full (multi-mode overlay) | Per-phase model routing |
| Kilo Code | Full (multi-mode overlay) | OpenCode-compatible config in ~/.config/kilo |
| Gemini CLI | Full (experimental) | Custom agents in ~/.gemini/agents/ |
| Cursor | Full (native subagents) | 10 SDD agents in ~/.cursor/agents/ |
| VS Code Copilot | Full (runSubagent) | Parallel execution |
| Codex | Solo-agent | CLI-native, TOML config |
| Windsurf | Solo-agent | Plan Mode, Code Mode, native workflows |
| Antigravity | Solo-agent + Mission Control | Built-in Browser/Terminal sub-agents |
| Kimi Code | Full (native custom agents) | Modular prompt templates in ~/.kimi |
| Kiro IDE | Full (native subagents) | Native ~/.kiro/agents/ + steering orchestration |
| Qwen Code | Full (native sub-agents) | Slash commands, ~/.qwen/commands/, auto_edit mode |
| OpenClaw | Solo-agent | Workspace-first AGENTS.md / SOUL.md with global MCP config |
| Trae | Solo-agent | Desktop app by ByteDance; ~/.trae/skills/ + OS-specific rules |
| Pi | Full (package-managed subagents) | First-class gentle-pi harness with Pi-native persona/models, SDD, and Engram memory |
| Hermes | Detect-only | YAML MCP config, SOUL.md persona; install manually first |
Pi is package-managed, not just configured. Selecting Pi installs the first-class
gentle-piharness, 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.
Every configured agent receives the same outcome-first routing, even when the optional SDD component is not selected. Ask for the outcome; the agent uses exactly one implementation route and reviews the candidate only after implementation.
| Situation | Expected behavior |
|---|---|
| Understanding needs 1-3 files, or one mechanical file change is already understood | Keep the bounded action direct and inline. |
| Understanding needs 4+ files, reading prepares a write, broad research is needed, or a writer changes 2+ non-trivial files | Delegate the narrow exploration or one focused writer without creating SDD state. |
| Durable proposal, spec, design, and task artifacts would materially reduce substantial ambiguity | Offer optional SDD; select it only after an explicit request or an accepted proposal. |
| A candidate is ready for review | Freeze the exact bytes and derive review effort from evidence, never size alone. Interactive starts ask once per clone before reviewer work; non-interactive tier-1/tier-2 starts proceed without prompting and report how to disable review mode. |
| Commit, push, PR, or release | Validate the same content-bound receipt at the applicable delivery gate; never silently reopen review or create another budget. |
| Scope changes or an operation is interrupted | Use provider-owned status, recovery, and reconciliation; do not infer authority or replay safety from narration. |
Implementation routing does not decide review strength, and per-action test, build, install, or review workers do not change the selected route. Native commands own repository identity, candidate scope, lifecycle transitions, receipts, and safe continuations. See Organic Implementation Routing, the Organic RDD architecture, and the review authority threat model.
Note
gentle-ai install requires Node.js 18+ and npm on every platform (it warns if either is missing). See Prerequisites for your distro's install hint.
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bashWindows (PowerShell)
go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latestWarning
Windows source builds and CI/runtime tests remain supported, but official Windows binary distribution and Scoop are temporarily 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.
Once your agents are configured, open your AI agent in a project and run these two commands to register the project context:
| Command | What it does | When to re-run |
|---|---|---|
/sdd-init |
Detects stack, testing capabilities, activates Strict TDD Mode if available | When your project adds/removes test frameworks, or first time in a new project |
gentle-ai skill-registry refresh |
Scans installed skills and project conventions, builds the registry | After installing/removing skills, or first time in a new project |
These are not required for basic usage. The SDD orchestrator runs /sdd-init automatically if it detects no context. Startup hooks normally keep the skill registry fresh for agents that support hooks, including Codex, Claude Code, OpenCode, and Pi through gentle-pi. If you start Pi with pi -ns, startup skill loading/hooks are skipped, so run the registry refresh manually when you need updated project rules.
Run gentle-ai doctor at any time for a read-only health check of your ecosystem (tool binaries, state.json, Engram reachability, disk space).
Alternative install and scope options
Homebrew (macOS / Linux)
brew tap Gentleman-Programming/homebrew-tap
brew trust --formula gentleman-programming/tap/gentle-ai # one-time, for Homebrew tap trust
brew install gentle-aiGo install, stable pin (any platform with Go 1.25.10+)
go install github.com/gentleman-programming/gentle-ai/cmd/gentle-ai@v1.46.0The stable pin keeps the unsuffixed import path because v1.46.0 predates the
/v2 module path. Releases on the v2.x line install from
github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai.
Scoop (Windows) — temporarily unavailable while official Windows binary distribution is held for public-trust Authenticode signing. Use the Windows go install command above.
By default, gentle-ai install writes agent-scoped files to each selected agent's global config directory. To keep the Gentleman stack isolated to one project, run:
gentle-ai install --scope=workspaceWorkspace scope applies to selected agents for agent-scoped files such as system prompts, skills, SDD agents, and persona files. Global-only integrations remain global by design.
Beta channel — use only to test unreleased main builds. It requires Go 1.25.10+:
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash -s -- --channel beta
# Windows (PowerShell)
$env:GENTLE_AI_CHANNEL="beta"; go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@mainReceipt-Driven Development (RDD) started in gentle-ai v1.47.0 on 2026-07-10, with the first bounded native review transactions. Every release from v1.47.0 onward is part of the unstable RDD development line. New releases will continue improving RDD until the project declares the line stable. The stable version for normal use without RDD is the last release before RDD, v1.46.0.
Use @latest when you want to try the latest released RDD build. Use @main only when you explicitly want unreleased RDD development changes. The negotiated public review contract was published in v2.1.6.
Stable version (v1.46.0)
go install github.com/gentleman-programming/gentle-ai/cmd/gentle-ai@v1.46.0
gentle-ai versionLatest released RDD build (unstable)
go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest
gentle-ai versionUnreleased RDD development build (main)
go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@main
gentle-ai versionThe managed installer tracks the channel's latest version and does not accept an arbitrary release pin. Use go install when reproducibility requires an exact version.
- Install and configure. Run the installer, select the agents and components you want, then open your agent in a project.
- Use the smallest implementation route. Keep bounded work direct, delegate actions that need fresh context, and use SDD only after an explicit request or an accepted proposal. SDD artifacts can live in Engram for cross-session memory, OpenSpec for versioned files, or hybrid for both.
- Build with discipline.
/sdd-initdetects project testing capabilities; when Strict TDD is active, SDD apply works test-first. SDD verify audits RED/GREEN evidence and runs verification. Agents that support delegation use focused subagents instead of one growing conversation. - Review one candidate. After implementation, bounded native review freezes the candidate and issues one content-bound receipt. Commit, push, and PR validate that same receipt. Releases validate native authority and its receipt, unless the protected-main fast path has the exact tag/current
origin/mainSHA, exact-SHA successful CI, a remote-head recheck, and no fresh risk.
Trust what the system can derive, not agent narration. Chapter 21 — Verifiable Trust explains the mental model: agents assess the candidate; native authority and delivery gates independently derive what may be trusted.
-
Upgrade, then sync. Refresh the binary and the managed agent assets together:
gentle-ai upgrade gentle-ai sync
Review mode is user-owned and available independently of the review lifecycle:
gentle-ai review mode status --cwd .
gentle-ai review mode disable --cwd .
gentle-ai review mode enable --cwd .status is read-only. Any global or clone-local disabled source wins; a clone can opt out with --scope clone but cannot force review on. Re-enabling applies only to future candidates, while declining a one-candidate review prompt does not change the mode. When review is disabled, existing exact governing receipts remain authoritative; otherwise native review gates report disabled/unmanaged and defer delivery to ordinary repository policy without fabricating approval.
The current unstable RDD line still has two limitations, both about SDD while review mode is disabled. The SDD pre-verify status path can still require review. And the native archive gate now defers correctly, but the sdd-archive skill's own contract still requires reviewGate.result: allow, so the agent-facing rule blocks where the product no longer does. See Organic RDD known limitations.
Official macOS and Linux release archives require an authenticated checksums.txt. The built-in upgrader verifies its Minisign signature, its exact Gentleman-Programming/gentle-ai + release-tag binding, and the selected archive checksum before replacing the installed binary. Release archives are capped at 128 MiB, including chunked or unknown-length responses. Missing, oversized, malformed, untrusted, or placeholder key material fails closed without changing the installed binary.
To verify a release manually, obtain the production public-key payload and fingerprint from a maintainer-controlled channel, then download checksums.txt and checksums.txt.minisig from the same release:
minisign -VQm checksums.txt -x checksums.txt.minisig -P "$GENTLE_AI_MINISIGN_PUBLIC_KEY"
# Expected output: repo=Gentleman-Programming/gentle-ai;tag=vX.Y.Z
sha256sum --check --strict --ignore-missing checksums.txtDo not bootstrap trust from a public key downloaded only beside the artifacts it verifies. See Release signing and key rotation for the first-signed-release procedure, exact CI injection points, and rotation runbook.
Windows archives and Scoop publication remain omitted until publicly trusted RSA Authenticode signing is provisioned (prefer managed OIDC with Azure Artifact Signing), both amd64 and arm64 executables are signed before archive and checksum generation, and release verification fails if either executable is unsigned.
For a monorepo or shared worktree, explicitly review exactly what is in the Git index:
git add apps/my-service
git diff --cached
gentle-ai review start --projection stagedThe staged projection freezes the complete existing index, including all previously staged paths. It starts review but does not itself issue an approved receipt; unstaged and untracked worktree content is excluded. The default workspace projection remains the complete workspace review, and an existing authority is never auto-converted between projections. See the review authority threat model for delivery and base-ref details.
Every install, sync, and upgrade automatically snapshots your config files. Backups are compressed (tar.gz), deduplicated (identical configs are not re-backed up), and auto-pruned (keeps the 5 most recent). Pin important backups via the TUI (p key) to protect them from pruning.
See Backup & Rollback Guide for details.
Assign different AI models to different SDD phases -- a powerful model for design, a fast one for implementation, a cheap one for exploration. OpenCode uses gentle-orchestrator as the base SDD conductor, and generated named profiles still appear as sdd-orchestrator-{name} entries.
# Via CLI
gentle-ai sync --profile cheap:openrouter/qwen/qwen3-30b-a3b:free
gentle-ai sync --profile-phase cheap:sdd-design:anthropic/claude-sonnet-4-20250514
# Or via TUI: gentle-ai → "OpenCode SDD Profiles" → CreateAfter creating a profile, open OpenCode and press Tab to switch between gentle-orchestrator (default) and your custom profiles.
| What you need | Use this |
|---|---|
| Default SDD conductor | gentle-orchestrator |
| Legacy configs | sdd-orchestrator is migrated to gentle-orchestrator on sync |
| Named model profiles | sdd-orchestrator-cheap, sdd-orchestrator-premium, etc. |
Full guide: OpenCode SDD Profiles
Your AI agent automatically remembers decisions, bugs, and context across sessions. You don't need to do anything -- but when you do:
engram projects list # See all projects with memory counts
engram projects consolidate # Fix name drift ("my-app" vs "My-App")
engram search "auth bug" # Find a past decision from the terminal
engram tui # Visual memory browserFull reference: Engram Commands
| Your task | Start here |
|---|---|
| Understand the Gentle-AI mental model | Intended Usage |
| Choose direct, delegated, or optional SDD routing | Organic Implementation Routing |
| Plan substantial work with SDD | Intended Usage and OpenSpec Config |
| Configure a supported agent | Agents for the feature matrix and per-agent notes |
| Use the Pi package harness | Pi Agent for packages, Pi-native commands, models, and troubleshooting |
| Configure OpenCode phase models | OpenCode SDD Profiles |
| Review or deliver a change safely | Review Integration Contract for provider consumers; Review Authority Threat Model for technical boundaries; Chapter 21 — Verifiable Trust for the mental model |
| Find or share persistent context | Engram Commands |
| Refresh or troubleshoot an installation | Usage, Backup & Rollback, and Platforms |
| Extend or contribute to Gentle AI | Codebase Guide, Components, Skills & Presets, Skill Registry, and Architecture & Development |
| Understand how agent behavior is tested | Testing Agents Deterministically for the real-agent E2E and its model fixture |
This project gets better when the community builds on top of it.
- sub-agent-statusline — optional OpenCode TUI plugin that shows sub-agent activity, status, elapsed time, and token/context usage when OpenCode exposes it.
- sdd-engram-plugin — optional OpenCode TUI plugin to manage SDD profiles and browse Engram memories directly from OpenCode, with runtime profile activation and no restart required.
When you select OpenCode in the installer, Gentle-AI asks whether to register each community plugin and offers a browser shortcut to review the repository first. Gentle-AI only ensures ~/.config/opencode/tui.json exists and adds the plugin package names to its plugin array; OpenCode installs/loads those packages the next time it starts. Once OpenCode has materialized a plugin under ~/.config/opencode/node_modules/, gentle-ai update can compare its local package.json version with the plugin's GitHub releases.
This project exists because of the community. See CONTRIBUTORS.md for the full list.
- Just installed? Read Intended Usage for the mental model, then run
gentle-ai doctorif anything looks wrong. - Starting work? Read Organic Implementation Routing to understand direct, delegated, and optional SDD behavior.
- Reviewing a focused change? Start with the Organic RDD architecture and review authority threat model.
- Maintaining Gentle AI? Use the Codebase Guide to find package ownership and review boundaries.
- Using Pi? Read Pi Agent for the
gentle-piharness, Pi commands, persona, and model assignments. - Ready to contribute? Check CONTRIBUTING.md and the open issues.
