Add Memory, Workflow, and Evidence to Your Agent with Gentle-AI

Your agent writes code, then forgets everything: no memory of yesterday's decisions, no opinion about your project, no way to prove what it did. Gentle-AI — an 8k-star MIT project — attacks exactly that. It is a deterministic engineering environment for the agent you already use, and the README is explicit that it never installs an agent for you.

Why This Skill Matters

Three pieces carry the pitch. Engram is memory: the agent writes down what it learns as it works and checks its memory before asking you to re-explain. ODD (Organic Driven Development) keeps small work small — tasks are sized by understanding, risk, and resumability, never by file count, so an understood, contained fix runs inline with no subagents and no task document. RDD (Receipt-Driven Development) is review that cannot drift: the candidate change is frozen before anything reads it, and the result is informational — commit, push, and release stay your call. RDD is on by default; gentle-ai review mode disable turns it off.

Delegation is rule-bound too: the orchestrator may only delegate when it can name the reason — exploration beyond one inline batch, parallel writers with disjoint edit surfaces, a context backstop for long sessions, or an independent verifier for a high-risk change.

Installation

macOS with Homebrew:

brew install gentleman-programming/tap/gentle-ai

macOS and Linux also have a curl installer, and Windows installs from source with Go 1.25.10+:

go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.1.1

Then run the setup wizard and the health check:

gentle-ai
gentle-ai doctor

The wizard asks which agents to configure — the README lists 17 integrations including Claude Code, Codex, Cursor, Gemini CLI, OpenCode, and Pi. doctor is read-only: it reports the state of your installation and changes nothing.

Real Workflow: A Small Fix, Then a Risky One

1. Configure your existing agent once with gentle-ai, then use the agent normally — your configs are snapshotted before every write.
2. Ask for a small fix, such as a mobile overflow bug. ODD keeps it inline: the agent explores before touching code, writes one failing test for the requested rule, makes it pass, and refactors with tests green.
3. Ask for something high-risk, such as a data migration. The routing rules hand it an independent verifier, and RDD freezes the finished candidate so the review evidence belongs to the exact version you rely on.
4. When the agent stops, the gentle-ai binary — not the model — decides the next valid transition. The README names four public states: Working, Checking, Ready, or Needs your decision.

On the project's own local benchmark — single runs, not averages — routing a three-line bug inline cut it from 335 seconds and 56 turns to 77 seconds and 10 turns.

Tips

• Run gentle-ai doctor whenever something feels off; if it cannot read state.json, inspect the reported file and directory before touching anything — doctor never edits it.
• The security deny-list blocks ~/.ssh, .env, and credential files from agent access.
• Optional extras live in the same wizard: the Context7 MCP for live framework docs, CodeGraph (a read-only symbol graph of your codebase), personas, and model assignment per agent or review role where supported.
• Gentle Shell — the polished Pi workspace from the same team — is a separate package with its own runtime; installing the gentle-ai binary does not establish Pi parity.

When Not to Use This

Gentle-AI does not build agents, pick your stack, or replace your judgment — it configures the agent you already have. And because each integration uses that agent's native capabilities, features such as delegation and RDD review can differ across the 17 supported tools; check the capability matrix before assuming parity.

See the leaderboard for more skills.