gentle-ai
Gentleman-Programming · Gentleman-Programming/gentle-ai
Provides persistent memory, a structured workflow, and evidence for AI coding agents like Claude Code and Cursor.
Gentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.
Preview
What you can do with it
- Enable your AI agent to remember project context and past decisions across sessions.
- Implement Organic-Driven Development for a structured and traceable coding workflow.
- Utilize bounded review to ensure quality and control over agent-generated code changes.
Safety check
Usable, but read the notes first.
- ●Installer downloads a remote script and pipes it to the shell.
scripts/install.sh - ●Asks for administrator (sudo) rights.
scripts/install.sh
Automated scan of the repo files. Always review code you run.
From the README
Gentle-AI™
The deterministic engineering environment for the AI agent you already use.
Website • Quickstart • Docs • Wiki
Your agent writes code, then forgets everything. It has no opinion about your project, and no way to prove what it did beyond asking you to read every line. Gentle-AI gives it memory, a workflow, and evidence.
See it in action
One prompt, from idea to reviewed commit: memory, workflow, and evidence in a real session.
https://github.com/user-attachments/assets/fa5c0cfe-06e7-4c0d-bd6e-8ac7cb934339
Prefer Spanish subtitles?
https://github.com/user-attachments/assets/6d2bc422-a4dd-4ecf-a04b-fcd3bea7fea9
If Gentle-AI made your agent worth trusting, a star helps other people find it.
WORKS WITH THE AGENT YOU ALREADY HAVE
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
17 integrations · native configuration · compare capabilities →
Features
Engram™ — Keep your project context
The cost of a fresh session is not the tokens — it is you, re-explaining the same decisions every morning. Engram removes that: your agent writes down what it learns as it goes and reaches for it before it reaches for you, so context accumulates instead of resetting.
ODD — Keep small work small
Small changes should not need a planning pipeline, and larger work should not lose its context between sessions. Organic Driven Development (ODD) keeps understood changes lightweight and gives substantial, authorized work one recoverable feature document. The agent explores before changing code, checks the results, and keeps progress current so work can resume without rebuilding the plan.
Test-first by default — Prove each requested rule
ODD applies test-first development by default when a relevant runnable test and a clear expected outcome exist: capture a failing behavior test before implementation, make it pass, then refactor while tests stay green. Each requested rule gets one RED test, each touched existing command or option gets one test proving its previous behavior still holds, and nothing else is padded in. Without a meaningful runnable test, the agent explains the exception and runs applicable functional checks anyway.
RDD — Check finished work at the right depth
Receipt-Driven Development (RDD) is on by default and opt-out: run gentle-ai review mode disable to turn it off. Explicit global or clone-local OFF choices remain OFF. Its point is that a review cannot drift: the candidate is frozen before anything reads it, so the evidence belongs to the exact version you are about to rely on — not to whatever the worktree looked like a moment later. The depth comes from that frozen candidate rather than from the model's judgment, and the result is informational. Commit, push and release stay your call.
Deterministic by design — Know the next valid step
A model that guesses the next step guesses differently tomorrow, and differently again for your teammate. That is the gap between a workflow and a suggestion. The gentle-ai binary owns native RDD review transitions; ODD guidance keeps ordinary work proportional to the request. Review evidence is bound to the candidate rather than a model's recollection.
Gentle Shell — A complete workspace for Pi
Gentle Shell is a separate Pi integration package. Gentle AI configures supported agents; Gentle Shell owns its own Pi runtime, agents, and interface. Installing or updating this binary does not itself establish Pi behavior parity.
17 agents — Keep the agent you already use
Gentle-AI brings its shared workflow to Pi, OpenCode, Claude Code, Codex, and thirteen more agents. Each integration uses that agent's native capabilities, so available features such as delegation and RDD review can differ.
Also in the box
| Component | What it does |
|---|---|
| Skills library | Loaded automatically when the task matches |
| Context7 MCP | Optional, selectable live framework and library documentation |
| CodeGraph | Read-only symbol graph of your codebase |
| Security deny-list | Blocks ~/.ssh, .env and credential files |
| Config backups | Snapshotted before every single write |
| Doctor | gentle-ai doctor — read-only health report |
| Personas | Optional personas; Gentleman is a caring but rigorous mentor who guides you toward your goal |
| Themes | Gentleman and Gentleman-Cute |
| Model assignment | Configure supported agent and review-role models where available |
Every component, skill and preset: Full breakdown →
Back to top
Get started
# macOS (Homebrew)
brew install gentleman-programming/tap/gentle-ai
# macOS / Linux (curl)
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash
# Windows (PowerShell) — source install of the latest release, needs Go 1.25.10+
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.0.0
gentle-ai # pick your agents, components and persona
gentle-ai doctor # veri