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.
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.
Gentle-AI's workflow guidance keeps the parent/orchestrator thread thin. Once a task stops being small, delegation or an explicit SDD phase boundary is expected rather than optional.
| Trigger | Expected behavior |
|---|---|
| Reading 4+ files to understand a flow | Delegate exploration or run an exploration phase. |
| Touching 2+ non-trivial files | Use one focused writer and validate the result. |
| Implementation ready for review | Start one bounded native review that freezes the candidate and creates a content-bound receipt. |
| Commit, push, or PR | Validate that same receipt against the live Git candidate; never silently reopen review or create a new budget. |
| Release | Validate native authority/receipt, or use protected-main only with an exact tag/current origin/main SHA, exact-SHA CI, remote-head recheck, and no fresh risk. |
| Wrong cwd, worktree/git accident, merge recovery, or confusing test/env issue | Stop, preserve the review scope, and investigate or validate the existing receipt before proceeding. |
| Long monolithic session with accumulating complexity | Pause and delegate, re-plan, or justify why not. |
The workflow guidance directs agents; the native review commands bind receipts and lifecycle gates to the Git candidate they inspect. They protect against accidental scope or identity drift, not a malicious local actor. See the review authority threat model for boundaries and assumptions.
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/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.0Scoop (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/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/cmd/gentle-ai@latest
gentle-ai versionUnreleased RDD development build (main)
go install github.com/gentleman-programming/gentle-ai/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.
- Plan when it helps. SDD is optional for substantial work. Its 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
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 |
| 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 | Components, Skills & Presets, Skill Registry, and Architecture & Development |
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. - Planning substantial work? Learn the SDD and OpenSpec conventions in Intended Usage and OpenSpec Config.
- Reviewing a focused change? Start with the review authority threat model, including staged-index 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.
