Gentleman-Programming/gentle-ai

Gentle‑AI™ – Deterministic engineering environment for AI‑code agents

What it is – Gentle‑AI is a command‑line tool that sits on top of the code‑generation agents you already use (e.g., Pi, Claude‑Code, Codex, VS Code Copilot, Gemini CLI, etc.). It adds a lightweight, deterministic workflow that gives the agent memory, structured delegation, and verifiable review evidence, so the agent’s output can be trusted and reproduced.

Key concepts

• Engram™ – a persistent project‑wide memory that records decisions the agent makes during a session. The next session can query Engram instead of re‑explaining the same context.
• Organic‑Driven Development (ODD) – a rule‑based approach that keeps tiny changes inline and only spawns sub‑agents for larger, higher‑risk work. The system decides why it delegates (exploration, parallel writers, context back‑stop, independent verifier) rather than delegating by file count.
• Receipt‑Driven Development (RDD) – automatic, risk‑aware reviews that freeze the exact candidate change before any read‑only checks run. For high‑risk changes the full 4R review (Risk, Resilience, Readability, Reliability) is performed; low‑risk changes get a lightweight structural read‑back.
• Deterministic state machine – the gentle‑ai binary reads the on‑disk state and always returns one of four public states (Working, Checking, Ready, Needs your decision), removing model‑driven nondeterminism from the workflow.
• Gentle Shell – a bundled workspace for the Pi agent that includes the same workflow, a skills library, live documentation (Context7 MCP), a read‑only symbol graph (CodeGraph), and safety features (credential deny‑list, config snapshots, health‑check doctor).

Supported agents – 17 integrations (Pi, OpenCode, Claude‑Code, Codex, Cursor, VS Code Copilot, Gemini CLI, Kilo Code, Kimi Code, Kiro IDE, Qwen Code, Hermes, Antigravity, Windsurf, OpenClaw, Trae, Conductor). Each integration uses the native capabilities of the underlying model while adding Gentle‑AI’s workflow.

Main components

Component	Role
Skills library	Auto‑loaded when a task matches a known skill.
Context7 MCP	Optional live framework/library docs.
CodeGraph	Read‑only symbol graph of the codebase.
Security deny‑list	Blocks accidental exposure of SSH keys, .env, etc.
Config backups	Snapshots before every write operation.
Doctor	gentle‑ai doctor – read‑only health report.
Personas	Optional mentor‑style guidance (e.g., “Gentleman”).
Themes	Visual themes for the CLI.
Model assignment	Choose which agent model handles generation vs. review.

Typical workflow

1. Install the binary (Homebrew, curl script, or go install).
2. Run gentle‑ai to pick your preferred agent, components, and optional persona.
3. Use your agent as usual; Gentle‑AI intercepts every write, snapshots configs, and updates Engram.
4. For larger tasks, the orchestrator may spawn a sub‑agent according to the ODD trigger rules.
5. When a change is ready, RDD automatically runs a risk‑based review and produces evidence tied to the exact candidate version.
6. The deterministic state machine tells you whether the change is Working, Checking, Ready, or needs your manual decision.

Installation

# macOS (Homebrew)
brew install gentleman-programming/tap/gentle-ai

# macOS / Linux (curl script)
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash

# Windows (PowerShell) – requires Go 1.25.10+
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.1.1

After install, run gentle-ai to configure and gentle-ai doctor to verify the setup.

Why it matters – Modern code‑generation agents are powerful but stateless; they forget project context and provide no audit trail. Gentle‑AI turns them into deterministic assistants that remember decisions, enforce test‑first development, and produce verifiable review artifacts, making AI‑driven coding safer for production codebases.

License – MIT (per the repository badge).

---

All information above is taken directly from the repository’s README; no additional features have been inferred.