Gentleman-Programming/gentle-ai

Gentle‑AI™ – an ecosystem configurator for existing AI coding agents

What it does

• Gentle‑AI does not provide an AI model itself. Instead it takes a coding‑assistant you already have installed (Claude Code, Cursor, OpenCode, etc.) and wires it up with a suite of optional components that give the agent memory, planning, skill libraries, security guardrails and a review workflow.
• The tool runs as a small Go binary (gentle-ai). After a one‑time installation you launch an interactive terminal UI, pick the agent(s) you use, choose a preset or individual components, and the program writes the appropriate configuration files into the agent’s native config directories.

Key components

Component	Purpose
Engram™	Persistent memory that survives restarts, so the agent remembers past decisions, bug‑fixes and context.
Skills	A curated library of coding “skills” that the agent automatically loads when a task matches.
Persona	Optional teaching‑oriented voice (e.g., Gentleman or neutral) that can be customized.
Spec‑Driven Development (SDD)	A planning workflow for larger features: explore → propose → spec → design → task list → implement → verify.
Context7	An MCP (metadata‑centric‑proxy) server that fetches live framework and library documentation during a session.
Permissions	Security guardrails that deny access to sensitive paths such as ~/.ssh or .env.
GGA (Gentleman Guardian Angel)	An AI‑provider switcher that can route requests to different back‑ends.
Theme	Optional visual themes for supported agents (Claude Code, OpenCode).

Presets bundle these components for quick setup:

• full‑gentleman – everything (memory, SDD, all skills, etc.)
• ecosystem‑only – core components without optional extras
• minimal – just Engram and SDD
• custom – pick any combination you like.

Supported agents Gentle‑AI works with a long list of existing coding agents, ranging from Claude Code and OpenCode (which support sub‑agents) to solo‑agent tools like Windsurf. For each agent it generates the native configuration format (e.g., TOML for Codex, files under ~/.cursor/agents/ for Cursor) and respects the agent’s own delegation model.

Installation & usage

1. Prerequisites – Node 18+, npm, Git 2.38+, and Go 1.25.10+ (the latter only needed on Windows or when building from source). Your chosen AI agent must already be on the PATH.
2. Install the binary – a one‑liner curl … | bash for macOS/Linux or go install … for Windows.
3. Run the TUI – gentle-ai lets you select agents, components, and persona. It backs up any existing config before overwriting.
4. Verify – gentle-ai doctor produces a read‑only health report (binary presence, Engram reachability, disk space, broken symlinks, etc.).

How it decides what to do Gentle‑AI adds a routing layer that chooses the smallest‑possible workflow for a given request:

• Small, well‑scoped changes → direct inline execution.
• Medium‑size changes (≥ 4 files, broader research) → a delegated sub‑agent handles the work without extra artifacts.
• Ambiguous, large features → the agent offers the optional SDD workflow; it only proceeds if you accept the proposal. The routing decision is independent of any later review step.

Spec‑Driven Development (SDD)

• Triggered by saying “use SDD” or by accepting the agent’s proposal.
• Generates durable artifacts (proposal, spec, design, task list) that can be stored in Engram, in version‑controlled files (OpenSpec), or both.
• Includes an optional Research lane that records auditable external evidence.
• Works with strict TDD if enabled, but remains separate from the later Receipt‑Driven Development (RDD) review.

Receipt‑Driven Development (RDD) (opt‑in)

• Provides an evidence‑based review after implementation.
• Defines a candidate (the exact bytes changed), freeze (snapshot at start), and a set of lenses (Risk, Resilience, Readability, Reliability).
• The amount of review effort is chosen based on the declared risk level, not on file count.
• Results in an outcome (informational evidence) and an acknowledgement that the agent has recorded the review result.

Documentation & community

• Full docs live in the repository’s docs/ folder and on a public wiki.
• A “doctor” command helps troubleshoot.
• The project is MIT‑licensed and supports macOS, Linux and Windows.

Bottom line Gentle‑AI is a configuration layer that turns a stand‑alone AI coding assistant into a more disciplined development partner, adding memory, planning, skill selection and optional evidence‑based review without installing a new model.