Gentle-AI: A Configuration Layer for the Coding Agents You Already Run

The problem: agents that start from zero every session

A coding agent like Claude Code or Cursor writes code, but it forgets your decisions between sessions. It has no built-in opinion about your project's conventions, and it will happily summarize work you then have to read line by line to trust. Gentle-AI targets exactly this gap. It is not another agent. It is a configurator that takes the runtime already on your machine and adds the missing structure: memory that survives restarts, a workflow for planning large changes, a library of skills the agent loads on demand, MCP servers for live documentation, and an optional evidence-based review step. The intended user is a developer who already uses an AI agent daily and wants it to stop acting like a chatbot that happens to write code. Teams that need identical agent behavior across different runtimes and machines also fit the profile, because the configuration is applied consistently rather than per-agent by hand.

How the components fit together

Gentle-AI installs a set of components, and you choose them individually or through presets. The recommended set includes Engram for persistent memory across sessions, so decisions and bug fixes survive restarts, and a curated skill library that the agent loads when a task matches. Optional components layer on top. Spec-Driven Development (SDD) adds a planning workflow for substantial features. Receipt-Driven Development (RDD) is mentioned in the table of contents, which suggests an evidence-based review step, though the README excerpt does not detail how receipts are generated or verified. Context7 is an MCP server that fetches live framework documentation. Permissions adds security-first guardrails, including a deny list for paths like ~/.ssh, .env, and credential files. GGA, the Gentleman Guardian Angel, is an AI provider switcher. A theme component changes the look of Claude Code and OpenCode. The key architectural point is that Gentle-AI does not embed any of this logic into a new runtime. It configures the runtimes you already have, so the same memory and skills follow you across Claude Code, Cursor, OpenCode, and Codex.

Running it: commands and refusal behavior

The quick start is two commands. First you run 'gentle-ai' with no arguments, which lets you pick your agents, components, and persona interactively. Then you run 'gentle-ai doctor' to verify the installation. The README points to an Install section for prerequisites and platform-specific binary commands, but that section is not in the excerpt, so the exact download method is not confirmed here. What is confirmed is a deliberate constraint: Gentle-AI never installs an AI agent for you. If you select an agent it cannot detect, it refuses and prints the exact command you would run yourself. It will not silently install software. That refusal is a meaningful design choice. It keeps the tool honest about its scope, but it also means you must have the target agent present and detectable before Gentle-AI can do anything useful. The 'doctor' command suggests a diagnostic path, but the README does not specify what it checks beyond verifying the installation.

The workflow: how your agent decides how to work

The README includes a section titled 'How your agent decides how to work', which points to a mechanism where the agent picks a working style that matches the size of the task. The excerpt does not give the full logic, but the phrasing implies a size-based decision: small tasks get a direct approach, substantial features trigger the Spec-Driven Development workflow. This is a genuine attempt to solve a real problem. Agents without such a prompt will treat a one-line fix and a multi-file refactor with the same shallow planning. The trade-off is that this behavior depends on the agent actually following the configured instructions. If the runtime ignores the persona or the SDD prompt, Gentle-AI has no enforcement layer. The documentation does not claim to override an agent's own preferences. It configures, it does not compel.

A real limitation: configuration is only as strong as the agent's compliance

The most obvious failure mode is that Gentle-AI cannot force an agent to use its memory, skills, or permissions. The Permissions component includes a deny list for sensitive paths, but that list only works if the agent respects it. A malicious or heavily misaligned agent could still read ~/.ssh if it ignores the deny rules, because the guardrails are prompt-level and config-level, not a sandbox. The README does not claim kernel-level isolation. Another limitation is the dependency on agent detection. If Gentle-AI cannot detect a runtime, it refuses to proceed. That is safe but inconvenient for users with non-standard install paths or experimental agents not on the supported list. The README names Claude Code, OpenCode, Cursor, and Codex, but the exact supported versions are not listed in the excerpt. For a tool that configures external software, version drift in those agents is a constant maintenance risk. A new agent release could change config file formats and break Gentle-AI's assumptions.

Alternative approaches: agent-native configs versus a cross-agent layer

The direct alternative is to configure each agent on its own. Claude Code has its own CLAUDE.md file, Cursor has rules, and Codex has its own prompts. You can hand-write memory files, skill directories, and permission rules for each runtime. The difference in approach is that Gentle-AI abstracts over all of them with a single Go binary and a consistent component model. That saves effort when you use multiple agents, but it adds an abstraction layer you must trust to keep up with each agent's changes. Another alternative is a dedicated memory server like mem0 or a standalone MCP registry, which solve only the memory piece and not the full workflow or review step. Those tools give you finer control over one component but require you to assemble the rest yourself. Gentle-AI's bet is that a bundled, opinionated configuration is worth more than the sum of individually tuned parts.

Maintenance, license, and upgrade path

The project is written in Go and released under the MIT license, which means you can fork and modify it freely, and there is no copyleft obligation. The repository is active, with recent releases including v2.7.0 and v2.6.0. The v2.6.0 release is titled 'The Runtime Asks First', which suggests a change in how the tool interacts with runtimes, possibly asking before applying configuration. The exact upgrade mechanism is not in the excerpt, but the README has a section called 'Keeping it up to date', which implies a defined process, likely a self-update command or a re-run of the installer. The maintenance cost for you is low if you stick to presets, but it rises if you write custom personas or skills, because you must track how each agent's prompt format evolves. The Go dependency means you need a Go toolchain only if you build from source; the release binaries avoid that.

Editorial conclusion

Adopt Gentle-AI if you already rely on an AI coding agent daily and want consistent memory, conventions, and reviewable evidence across sessions and machines. Skip it if you expect it to install an agent or if you prefer to hand-tune each runtime yourself. Before adopting, verify which of your target agents the current release detects cleanly, and test the deny list against your credential file paths, since the guardrails only work if they match your project layout.

Official sources

1. Gentleman-Programming/gentle-ai on GitHub
2. License: MIT
3. Project website
4. README
5. Releases