A configuration layer for an unruly agent collection
Gentle-AI is not another coding chatbot. It sits above agents such as Claude Code, OpenCode, Cursor, Codex, Gemini CLI, Windsurf, Pi, and others, then writes the files that shape how each one works. Depending on the selection, that can include system instructions, a teaching persona, portable skills, MCP server entries, Engram memory, OpenSpec planning, model profiles, permissions, subagent definitions, and delivery review gates.
The problem is real. Developers who try several coding agents quickly accumulate different config formats, skill directories, memory behavior, delegation models, and safety rules. Gentle-AI offers one installer and one vocabulary for that estate. Its agent matrix documents where skills, MCP configuration, prompts, and agents are written, rather than pretending every runtime exposes the same hooks.
The project also makes an important boundary explicit: it does not install most agent runtimes. If Claude Code, OpenCode, Hermes, or another selected agent is absent, installation stops and prints the command the user could run. Pi is the notable package-managed exception, where Gentle-AI installs a larger companion stack after Pi itself is present.
The workflow is disciplined and unusually opinionated
The supported path is Receipt-Driven Development, or RDD. Small understood changes stay direct. Broader research or writing can be delegated. Spec-Driven Development remains optional and is intended for work where durable proposals, requirements, design, and task files reduce ambiguity. After implementation, native review freezes the candidate and can issue a content-bound receipt that commit, push, pull-request, and release gates validate.
This design tries to solve a genuine trust problem: an agent saying “I reviewed it” is not proof that it inspected the exact bytes being delivered. Gentle-AI records candidate identity, review state, evidence, and authorization in native commands. It can assign different review strength based on frozen risk, allow one bounded correction, and refuse delivery when the receipt no longer matches. Review mode remains user-owned and can be disabled globally or per clone for future candidates.
The downside is conceptual and operational weight. Users are adopting a state machine for implementation attempts, candidate trees, review lenses, evidence capture, receipts, recovery, and delivery. That machinery must be more reliable than a normal checklist because it can block the path to a commit or archive. When it fails, the developer is debugging the governance layer rather than the product code.
Installation has safeguards, but touches a lot
The installer deserves credit for showing its work. A dry-run displays platform decisions and planned changes. Global scope writes into each selected agent's normal user configuration, while workspace scope keeps supported prompts, skills, SDD agents, and persona files in the project. Some package installs and settings remain global because the target agent only reads them there.
Every platform requires Node.js 18 or newer and npm, even if the chosen selection does not obviously look like a Node workflow. macOS and Linux have signed release archives, a shell installer, and Homebrew. Windows has source compatibility but no official executable archive or Scoop package until Authenticode signing is available, so it requires Go 1.25.10 and the versioned go install path. Unsupported Linux families are refused.
Before install, sync, and upgrade, Gentle-AI snapshots the managed configuration. Backups are compressed, deduplicated, and pruned to five unpinned copies; pinned snapshots survive. Restore is atomic per file, but package-manager installations are outside rollback. After replacing the binary, users must run gentle-ai sync to refresh installed assets. gentle-ai doctor then checks tools, saved state, Engram reachability, and disk space without changing anything.
Agent support is broad, not equivalent
Claude Code, OpenCode, Cursor, VS Code Copilot, Kimi, Kiro, Qwen, Pi, and some others can use delegated subagents. Codex, Windsurf, Antigravity, OpenClaw, and Trae default to solo-agent operation, although Codex has an experimental multi-agent opt-in. Gemini's custom agents are experimental. Hermes uses native ephemeral delegation, but its permission format is undocumented, so Gentle-AI skips permission injection.
A workflow proven in OpenCode does not automatically have the same evidence in Claude Code. The 2.3.0 release explicitly says Claude Code had unit and conformance coverage but no organic terminal-review proof. A new issue filed against 2.3.0 goes further: review lens-context emits one evidence marker name, while installed Claude Code reviewer definitions require another, so no rendered prompt can satisfy the reviewer contract. That is a concrete reason not to enable mandatory Claude Code delivery gates yet.
The same release lists other known limits. Native admission can reject some non-empty reviewer findings, Engram verification rejects requirements values in one path, an OpenCode permission profile can deny review.start, Windows has an attributes-file failure, corrupted authority has no sanctioned quarantine route, and high-tier corrections can dead-end after conflicting evidence. These are core workflow paths, not cosmetic backlog items.
Remarkable activity, unsettled stability
Version 2.3.0 was released on August 8, 2026 after release-candidate testing, and the repository was pushed again later that day. GitHub reported 638 combined issues and pull requests; a separate search returned 474 open issues. Much of that queue is structured defect reporting, design work, and automated provider evidence, but the scale confirms how quickly the system is evolving. The project is intensely maintained, not abandoned.
Documentation is deep and candid. The README, agent matrix, platform notes, review threat model, rollback guide, and release notes expose limitations most projects would hide. There is one damaging inconsistency: the current README says RDD became the stable supported path in 2.2.0, while the quickstart still calls every post-1.47 RDD release unstable and recommends 1.46 for normal use. Users should follow the release line they intentionally choose, but the project needs one authoritative policy.
Gentle-AI is worth studying and piloting if agent configuration has become a project of its own. Start with dry-run, workspace scope, a pinned backup, and review mode disabled. Confirm memory, skills, and routing on one expendable repository, then test the full review and recovery path for the exact agent and operating system. The ecosystem layer is compelling; the receipt authority is not yet dependable enough to become a critical delivery gate by default.