gentle-ai

[!IMPORTANT]
Receipt-Driven Development (RDD) is the supported stable path, and it is opt-in. v2.2.0 was the historical release where that path became supported after RDD began in v1.47.0: small work stays direct, broader implementation is delegated, SDD stays optional, and once RDD is enabled every route converges on structural proof, bounded review, an exact receipt, and delivery authorization. RDD is off until you enable it with gentle-ai review mode enable --scope global.

The current stable release is v2.3.0. @latest is the stable channel:

bash Copy

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest

To opt into the current prerelease, v2.4.0-rc.1, install its exact tag:

bash Copy

go install github.com/gentleman-programming/gentle-ai/v2/cmd/[email protected]

Use @main only for unreleased development changes. See the full RDD version policy.

Note the /v2 suffix: Go requires it for major version 2 and above. Releases before v2.0.0 use the unsuffixed import path.

What It Does Copy Chapter

Gentle-AI is NOT an AI agent installer. It adapts the agent runtime(s) already on your machine; it never installs one for you. If a selected agent isn't detected, Gentle-AI refuses and names the exact command you'd run yourself instead. 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.

Supported Agent Integrations Copy Section

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.

Organic Routing and Review Boundaries Copy Section

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.

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.

Quick Start Copy Chapter

Install (recommended) Copy Section

[!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 | bash

Windows (PowerShell)

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest

[!WARNING]
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.

[!IMPORTANT]
After replacing or upgrading the gentle-ai binary, run gentle-ai sync to refresh its managed assets. See the sync and upgrade reference.

Configure project context Copy Section

Once your agents are configured, open your AI agent in a project and run these two commands to register the project context:

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-ai

Go install: stable channel (any platform with Go 1.25.10+)

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest

Note the /v2 in the module path: Go requires it for major version 2 and
above. Releases before v2.0.0 use the unsuffixed path.

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=workspace

Workspace 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.

Unreleased development channel (main) — use only to test changes that are not part of a release. The managed beta installer tracks main; 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@main

RDD version policy Copy Section

Receipt-Driven Development (RDD) started in gentle-ai v1.47.0 on 2026-07-10, with the first bounded native review transactions, and became the supported stable path in v2.2.0. Those are historical milestones; the negotiated public review contract was published in v2.1.6.

The current stable release is v2.3.0. The current prerelease is v2.4.0-rc.1. main is unreleased development.

Stable channel (@latest, currently v2.3.0)

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest
gentle-ai version

Prerelease channel (v2.4.0-rc.1)

go install github.com/gentleman-programming/gentle-ai/v2/cmd/[email protected]
gentle-ai version

Unreleased development (main)

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@main
gentle-ai version

The 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.

Core Workflow Copy Chapter

1. Install and configure. Run the installer, select the agents and components you want, then open your agent in a project.
2. 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.
3. Build with discipline. /sdd-init detects 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.
4. 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/main SHA, 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.

5. Upgrade, then sync. Refresh the binary and the managed agent assets together:

   bash Copy

   gentle-ai upgrade
   gentle-ai sync

The flow at a glance Copy Section

Once you enable it, both implementation routes converge on RDD: a bounded native review freezes the candidate and issues the one receipt that every delivery gate validates — review is never reopened for unchanged content. RDD is opt-in, so with it off both routes deliver under ordinary repository policy instead.

Organic route (no SDD) — the agent picks the smallest useful route and RDD enters at the end, over the frozen candidate:

flowchart TD
    A["User requests a change(Claude Code · OpenCode · Codex...)"] --> B{"Implementationroute"}
    B -->|"decide/verify1–3 files"| C["Direct inline"]
    B -->|"4+ file explorationor 2+ non-trivial writes"| D["Delegated direct(one bounded worker)"]
    C --> E["Implementation + tests"]
    D --> E
    E --> F{"RDD enabled?(user-owned, opt-in)"}
    F -->|"off (default)"| Z["Ordinary deliveryreports disabled/unmanaged"]
    F -->|"on (explicitly enabled)"| G["review status --next-transition(provider-owned negotiated route)"]
    G --> H{"Risk frozenat START"}
    H -->|"low"| I["Structural readback0 lenses · silent"]
    H -->|"standard"| J["1 focus lens+ consent"]
    H -->|"high"| K["Canonical 4R + consent + forecastRisk · Readability · Reliability · Resilience"]
    J --> L["Reviewers inspect the immutable candidate(review inspect-candidate)"]
    K --> L
    L --> M{"Severe candidate-causedfindings?"}
    I --> N["Receipt: approved"]
    M -->|"no"| N
    M -->|"yes"| O["One bounded correction(frozen budget)"]
    O --> P["Fix validator(read-only, immutable trees)"]
    P -->|"passes"| N
    P -->|"fails with evidence"| Q["Escalated"]
    P -->|"no access to the diff"| R["Inconclusive: attempt notconsumed, capture again"]
    R --> P
    Q --> S["review recover(authorized successor)"]
    N --> T["Delivery gatespre-commit → pre-push → pre-prvalidate the SAME receipt"]
    T --> U["Commit → Push → PR"]
    Z --> U

    style N fill:#2D4F67,color:#fff
    style Q fill:#B8860B,color:#fff
    style U fill:#2D4F67,color:#fff

SDD route — durable planning artifacts first, then apply, with RDD reviewing the candidate before verify and archive requiring the receipt:

flowchart TD
    A["User: sdd-new / sdd-explore(or sdd-ff to fast-forward planning)"] --> B["Exploreinvestigate codebase and approaches"]
    B --> C["Proposeintent · scope · approach"]
    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 --> I["RDD over the frozen candidate"]

    subgraph RDD["RDD — same machine as the organic route"]
        I --> J{"Risk"}
        J -->|"low"| K["Structural readback"]
        J -->|"standard / high"| L["1 lens or 4R + consent"]
        L --> M{"Severe findings?"}
        M -->|"yes"| N["One bounded correction+ fix validator"]
        M -->|"no"| O["Receipt: approved"]
        K --> O
        N -->|"validates"| O
        N -->|"fails"| P["Escalated → recover"]
    end

    O --> Q["Verifyindependent verification againstspec · design · tasks"]
    Q -->|"passes"| R["Archivemerge delta-specs · close the cycle(requires reviewGate allow or disabled)"]
    Q -->|"fails"| H
    R --> S["Delivery gatesvalidate the same receipt"]
    S --> T["Commit → Push → PR"]

    style O fill:#2D4F67,color:#fff
    style P fill:#B8860B,color:#fff
    style T fill:#2D4F67,color:#fff

Size, file count, or perceived risk never select SDD on their own — only an explicit request or an accepted proposal does. Either way, one candidate gets one review, one possible correction, and one receipt.

Control receipt-driven development Copy Section

Review mode is user-owned and available independently of the review lifecycle. Receipt-driven development is opt-in: it is off until you turn it on.

gentle-ai review mode status --cwd .
gentle-ai review mode enable --scope global --cwd .
gentle-ai review mode disable --cwd .

status is read-only. With no source expressing an opinion the effective mode is off, reported as decided by default; only an explicit global enable turns review on. Any global or clone-local disabled source wins; a clone can opt out with --scope clone but cannot force review on, so --scope global is the only way in. Enabling applies only to future candidates, while declining a one-candidate review prompt does not change the mode. When review is off, existing exact governing receipts remain authoritative; otherwise native review gates report disabled/unmanaged and defer delivery to ordinary repository policy without fabricating approval.

Historical note: v2.2.2 introduced the native delivery-gate disabled/unmanaged disposition. Current SDD status does not use that disposition: with review disabled, it skips review authority, emits no reviewGate, and pre-verify continues without routing to a review that cannot start. Archive proceeds under ordinary repository policy when reviewGate is absent; a present reviewGate.result: allow is required only for discovered review activity. This differs from native delivery gates, which report disabled/unmanaged when review is disabled.

Release verification Copy Section

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.txt

Do 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.

Review a focused staged candidate Copy Section

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 staged

The 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.

Backups Copy Section

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.

Key Features You Should Know About Copy Chapter

OpenCode SDD Profiles Copy Section

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" → Create

After creating a profile, open OpenCode and press Tab to switch between gentle-orchestrator (default) and your custom profiles.

Full guide: OpenCode SDD Profiles

Engram (Persistent Memory) Copy Section

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 browser

Full reference: Engram Commands

Documentation Copy Chapter

Community Highlights Copy Chapter

This project gets better when the community builds on top of it.

Community Integrations Copy Section

• 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.

Contributors Copy Section

This project exists because of the community. See CONTRIBUTORS.md for the full list.

Next Steps Copy Chapter

• Just installed? Read Intended Usage for the mental model, then run gentle-ai doctor if 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-pi harness, Pi commands, persona, and model assignments.
• Ready to contribute? Start at the Community Roadmap — everything labelled up-for-grabs is scoped, approved and unclaimed. Then read CONTRIBUTING.md.