The Gentle stack for engineering teams
Gentle-AI is the best practices of the market, and a few beyond it, packed into the agents your team already uses: Claude Code, Cursor, OpenCode, Codex, Pi and a dozen more. You ask in plain language; it picks the right route, remembers, verifies and proves its work. Open source, one binary per machine, no agent lock-in.
In one minute
Before the details, the whole idea in one watch: the problem it solves, and what changes once the agents your team already uses have memory, a workflow and guardrails.
How it works
Four short episodes, about a minute each. Watch them in order: the base that coordinates, the workflow it follows, the helpers it delegates to, and the review that looks at the result from outside.
You give the intent, el Gentleman coordinates. One focused question only for a real decision, a risk line and an honest report on every change, and push, PR and merge stay yours.
Seven steps from authorize to close. Small work runs inline; large work gets a feature document in your exact words, test-first changes, small commits, and resumes from memory when interrupted.
A read-only explorer, a worker that edits but never commits, and a read-only verifier. The parent delegates for a reason, never by file count, and stays accountable.
It freezes the exact candidate, rates it by what it touches, asks you first and keeps corrections bounded. On by default, and only you can turn it off.
The whole delegation policy in one sitting: work inline by default, the three named reasons to hand work off, the six high-risk items, verification in proportion to risk, bounded corrections, and why the review switch belongs to you.
Why teams hit a wall
The agent forgets yesterday's decisions, conventions and bug fixes the moment the session ends.
The agent jumps into implementation before anyone agreed what is being built.
Architectural choices live in a scrollback nobody will read again.
A small ask quietly turns into a huge multi-area diff that reviewers cannot digest.
Verification is an afterthought, so "the tests pass" is a claim you have to take on faith.
Project conventions and skills are written down, but nothing loads them at the right moment.
Organic and natural
Gentle-AI is built so everything is organic and natural. You do not need to know how anything is implemented or which command to type: you describe what you need in plain language, the agent categorises the request and takes the best route to that goal. The workflow adapts to the task, never the other way around.
"Add retries to the upload handler", "why does login flake", "plan the billing rewrite". Plain language, no ceremony, no slash commands.
A quick fix, an investigation, a substantial feature, a review. The classification decides how much process the job deserves, from the evidence, never from how big it feels.
Inline for the small and understood; one feature document that quotes your spec when the work spans sessions; a subagent only when there is a named reason for it. Size never adds ceremony on its own.
No commands to learn, no implementation details to keep in your head. The best practices of the market, and a few beyond it, become the agent's default behaviour.
What every developer gets
Engram saves decisions, bug fixes and conventions as structured, searchable observations that survive restarts and context compaction.
A curated library of coding skills the agent pulls in on demand, plus your own project and user skills.
A teaching-oriented voice, Gentleman or neutral, or a fully custom persona of your own. It explains the why, not only the how.
Tasks are sized by understanding, risk and resumability, never by file count. Work you could finish from the request and the diff alone runs inline: no subagents, no task document.
ODD runs on every request: read-only unless you ask for a change, explore the code first, resolve real uncertainty, track substantial work in one feature document that quotes your spec verbatim, implement task by task, close with observed evidence.
A subagent costs a fresh session and a handoff, so it needs a named reason: one read-only explorer when understanding outgrows a single batch of reads, parallel writers for independent units with separate files, an independent verifier for high-risk changes, or a fresh worker when a long session runs out of room.
An MCP server that fetches current framework and library docs, so the agent stops guessing from stale training data.
Per-phase model routing in OpenCode, background subagents in Pi and OpenCode, native sub-agents wherever the runtime supports them.
A permissions component with a deny list for ~/.ssh, .env and credential files, backups before every change, and a tool that never installs software silently.
What is behind it
gentle-ai writes into each agent's native configuration: system prompts, skills, ODD routing, persona files and MCP entries. Memory is an MCP server backed by a single Go binary and a SQLite file. Everything stays on the developer's machine and is snapshotted before each change.
Why it spends fewer tokens of your subscription
The most expensive tokens are the ones spent implementing on a false assumption and redoing it all afterwards. The stack is arranged so that rarely happens:
So it never implements on top of false assumptions.
Small work stays inline; a subagent runs only when it pays for its fresh session and handoff.
A feature document that quotes your spec verbatim, or Engram, so decisions are never reconstructed from scratch.
Fewer bugs, fewer retries, fewer large rewrites.
States, hashes, limits and RDD review transitions run in Go, not in the model's reasoning.
Less output, smaller diffs, nothing unnecessary.
So do not worry when it explores or verifies for a while: that activity is preventive investment. Reading ten relevant files can be far cheaper than editing three wrong ones and redoing everything afterwards.
The right metric is not "how long did it take before writing?" but:
How much rework, repeated context and unnecessary code did it avoid?
That said, exploring without converging, re-reading the same files or launching subagents without a purpose wastes tokens too. Gentle-AI works because exploration is bounded, evidence-driven and followed by minimal writing.
Gentle Shell on a local benchmark with hidden acceptance suites. Each cell is a single run (n=1); cost is API-equivalent.
| Scenario | Before | After |
|---|---|---|
| 3-line bug in one function | 335 s · 56 turns · USD 0.339 | 77 s · 10 turns · USD 0.105, inline, no subagents |
| Bug rooted in shared logic | 479 s · USD 0.361 | 276 s · USD 0.207, one explorer |
| Data migration (high risk) | 559 s · USD 0.403, needed a feedback round | 539 s · USD 0.555, accepted on the first round with one independent verifier |
| 73-line spec, 26 hidden checks | Paraphrased handoffs: 23 of 26 after two feedback rounds | Spec passed by reference to every worker |
Against the same model in Codex CLI, with blind review of every solution, Gentle Shell was accepted on the first round in every task and ranked higher on the medium (3 of 3 runs) and large tasks; it was close on the small one. The large task still took about three times longer (17.5 to 17.9 min against 6.1 min), and that gap is open work.
Sources: gentle-shell#1723, #1794, #1713
Engram for your team
Engram is a single Go binary with SQLite and FTS5 full-text search, exposed through CLI, HTTP API, MCP and a TUI. No Node.js, Python or Docker for the core path. Install it once; every agent remembers.
Pi, Claude Code, OpenCode, Gemini CLI, Codex, VS Code Copilot, Cursor, Windsurf, Antigravity and any MCP-compatible agent read and write the same memory.
The SQLite database under ~/.engram is authoritative. Your memory stays on the machine unless you decide to share it.
Engram stores curated summaries, decisions, prompts and session handoffs instead of a firehose of raw tool calls. Agents search first, then fetch only what matters.
Before the context resets, the memory protocol pushes a handoff into Engram so the next session recovers the goal, discoveries and next steps.
Every observation carries a scope, so teammates' agents find shared project knowledge without wading through personal notes.
Export memory as portable compressed chunks and share it across machines through the repository you already have.
Use Engram Cloud when you want shared, project-scoped memory across machines without giving up local-first ownership. Local SQLite remains authoritative; the cloud is optional replication plus browser visibility for teams and operators.
Easy, fast, reversible
brew install gentleman-programming/tap/gentle-ai# one formula on macOS and Linuxgentle-ai# pick your agents, a preset and a persona in the TUIgentle-ai doctor# read-only health report: binaries, state, memory, diskOne Homebrew formula on macOS and Linux. Windows is a fully tested platform that builds from source with Go, never from an unsigned download.
The TUI detects the agents on the machine and lets each developer pick a preset, the components and a persona. Previous configs are snapshotted before anything is written.
A read-only health report covers binaries, state, memory reachability and disk space. gentle-ai upgrade and gentle-ai sync refresh the binary and the managed assets together.
Opinionated, on purpose
Substantial work keeps your request verbatim in one feature document, and every handoff points at it instead of paraphrasing, so exact strings, errors and examples survive delegation.
Behavior changes are test-first by default: one failing test per requested rule, then the minimum code to pass, then refactoring while the tests stay green.
Changes arrive as commits and pull requests sized for a human to read, with tests and docs travelling with the code.
Receipt-Driven Development is an original design you will not find anywhere else. It freezes the exact bytes under review, picks depth from risk, allows one bounded correction and records an outcome derived from Git, not from the agent's summary.
Whatever can be computed instead of reasoned is computed: states, routes, hashes, limits and workflow transitions live in the binary, so the model spends its tokens on judgement.
Organic Driven Development is the only workflow: explore, decide, implement, check, with substantial work tracked in one feature document. Its routing rules came from benchmarks, not intuition.
A custom workflow and a custom TODO discipline, designed around how agents actually fail, and refined in public with the community.
Credential files are denied to the agent, nothing is installed silently, and every change to your config is backed up first.
The persona explains the concept before the code, so the team levels up instead of copy-pasting.
One stack, five tools
gentle-ai
Equips the agents already on each machine with memory, a planning workflow, a curated skill library, MCP tool servers, model routing, a persona and review guardrails. Never installs an agent for you.
View on GitHub →$ brew install gentleman-programming/tap/gentle-aigentle-ai installgentle-ai syncgentle-ai doctorgentle-ai review mode enable|disable|statusengram
One Go binary with SQLite and full-text search, exposed through CLI, HTTP API, MCP and a TUI. Local first; Git Sync shares memory across machines and Engram Cloud adds optional project-scoped replication with a browser dashboard.
View on GitHub →$ brew install gentleman-programming/tap/engramengram mcpengram search <query>engram save <title> <msg>engram doctorgentle-pi
Organic Driven Development, focused subagents delegated for a reason, background jobs, test-first evidence, reviewable work units and safety guards on top of the Pi coding agent, installable on a clean machine with a double-click installer.
View on GitHub →$ pi install npm:gentle-pi@latestpipi listpi updatepi configpi authgga
Gentleman Guardian Angel runs a provider-agnostic review as a git pre-commit hook using whichever provider you already have: Claude, Gemini, Codex, OpenCode or Ollama.
View on GitHub →$ brew install gentleman-programming/tap/ggagga installgga rungga configgga cache statusGentleman.Dots
A single TUI installer for Neovim, Fish, Zsh or Nushell, Tmux, Zellij or Herdr, Ghostty, Kitty, WezTerm or Alacritty and the Starship prompt, on macOS, Linux, WSL and Termux. Includes an RPG-style Vim trainer.
View on GitHub →$ brew install Gentleman-Programming/tap/gentleman-dotsgentleman-dotsgentleman-dots --dry-rungentleman-dots --non-interactive --shell=fishFAQ
No. It configures agent runtimes that are already present on the machine. If you select an agent it cannot detect, it refuses and prints the exact command you would run yourself. It never installs software silently.
Full delegation: Claude Code, OpenCode, Kilo Code, Gemini CLI, Cursor, VS Code Copilot, Kimi Code, Kiro IDE and Qwen Code. Pi is package-managed through gentle-pi. Solo-agent support covers Codex, Windsurf, Antigravity, OpenClaw and Trae, and Hermes is detect-only.
Locally by default, in a SQLite database under ~/.engram that stays authoritative. Git Sync exports portable compressed chunks you control, and Engram Cloud is optional, self-hosted, project-scoped replication you enrol per project. Gentle-AI itself does not send your code anywhere; your agents keep talking to their own providers as before.
No. Receipt-Driven Development is on by default and opt-out: run gentle-ai review mode disable to turn it off. A review is only due for high-risk changes, the agent picks the review lenses that fit what it touched, and the outcome is informational: it records evidence, it does not block a commit or a release.
No. Work that is understood, low risk and resumable from the diff runs inline, with no subagents and no task document. In the benchmark, a 3-line bug went from 335 s to 77 s and from USD 0.339 to USD 0.105 once small work stopped paying for delegation.
Because most agent sessions fail for operational reasons, not model reasons. The stack ships a working set of opinions (requirements first, tests as evidence, reviewable work units, security defaults) so a team stops re-litigating them, while the Custom preset still lets you keep your own persona and settings.
Lead with cost and risk, not with tooling. Cost: the stack saves tokens by avoiding wrong work (explore before editing, bounded contexts, decisions kept in memory, early verification), so the subscription you already pay for produces fewer rewrites. Risk: evidence-based review replaces "the tests pass" with an outcome derived from Git, and security defaults keep credential files away from the agent. Consistency: every developer's agent follows the same conventions, so onboarding and hand-offs stop depending on who configured what. And the decision is cheap to reverse: it is open source, there is no lock-in, it never installs agents for you, every config change is backed up, and a pilot is one command per machine. Propose a two-week pilot on one team with a measurable question: how much rework, repeated context and review time did it remove?
It describes what the agent runtime itself can do, because Gentle-AI configures each agent through its own native features. Full delegation means the runtime can hand work to focused sub-agents (Claude Code's Task tool, Cursor's or Kiro's native subagents, OpenCode's multi-mode overlay): the main conversation stays a thin coordinator while an explorer reads, a writer implements and reviewers check, each with only the context it needs, which is where most of the token savings and the review depth come from. Solo-agent means the runtime runs everything in one conversation (Codex, Windsurf, Antigravity, OpenClaw, Trae): you still get the persona, skills, memory, workflow and guardrails, but routing happens inside a single context, so the benefits of bounded contexts are smaller. Detect-only (Hermes) means Gentle-AI recognises the agent but you finish the setup by hand.
Yes. gentle-ai, engram, gentle-pi and Gentleman Guardian Angel are MIT licensed; Gentleman.Dots is Apache-2.0. The gentle-pi name and logo are trademarks, which the license does not cover.
Gentle-AI is fully tested on Windows and installs from source with Go 1.25.10 or newer; there is no unsigned binary download by design. Gentleman.Dots targets Windows through WSL.
Everyone installs the same binary and picks the same preset, so every machine gets the same baseline. Engram observations carry a project or personal scope for searching; note that scope is a search filter, not a privacy boundary: enrolling a project for sync shares both, so keep personal notes in a separate project.
Nothing changes unless you enrol a project. Engram Cloud is a self-hosted runtime (engram cloud serve, official image on GHCR) that replicates one explicit project at a time and gives the team a browser dashboard. Local SQLite stays authoritative, and there is no cloud-only mode.
Run gentle-ai upgrade followed by gentle-ai sync. Every install, sync and upgrade snapshots your configuration; backups are compressed, deduplicated and pruned to the five most recent, and you can pin the ones that matter. gentle-ai doctor is a read-only report you can run any time.
Who is behind this, and how to work with him
Alan BuscagliaGentleman Programming
The Gentle stack is not a consultant's slide deck. It is the toolset Alan Buscaglia uses every day, refined in public with a community of thousands of developers who test it on real code.
Teams usually reach him the same way: a CTO or tech lead discovers the channel, wants their developers to adopt AI, and it is not working. Reluctant devs, disorderly usage, everyone prompting their own way, no process and no quality bar. That is an adoption problem, not a prompting course.
The focus is quality and verification over raw speed, and the goal is a team that knows how to direct the AI, not one that depends on a consultant.
Diagnosis, four sessions and a deliverable, spread over the rollout
For teams that want to adopt AI with a process behind it. Combines group sessions with tech-lead alignment before and after the rollout.
Three sessions on your own code
No theory. The team sees the whole flow, gentle-ai, Engram and the 4R review, running on the problems they actually have.
Longer engagements, delivered phase by phase
For organisations that need adoption to land across several teams or quarters, with a clear scope and outcome per phase.
Speaking
Keynotes and technical talks at the main developer conferences in Spain, on code review in the age of AI, agent architecture and orchestration, and the road from vibe coding to real engineering.
AI Afterwork: Agentic StackInnoIT Consulting offices, Barcelona
A Gentleman Programming x InnoIT event on the agentic stack; the closing talk tells the story behind RDD.
With Daniel Españadero and Dany Paredes
Talent Arena NightAntiga Fàbrica Estrella Damm, Barcelona
An exclusive 25-minute keynote to a full house.
Codemotion Madrid 2026MEEU Chamartín, Madrid
The extended version of the 4R review framework at one of the largest tech events in Spain.
JSConf España 2026La Nave, Madrid
A workshop on the AI Gentle Stack: the AGENTS.md pattern, skills architecture, subagents and orchestration, built on the agent architecture used at Prowler.
GDG Barcelona: Build with AIeDreams ODIGEO, Barcelona
Two sessions that night: agents in the life cycle of open-source projects, and Build Agentic Apps with Angular, Genkit and Kendo UI.
With Dany Paredes and Rocío Cejudo
DevFest Barcelona 202542 Barcelona, GDG Barcelona
Nerdearla MadridLa Nave, Madrid
The first public presentation of the 4R review framework.
One command per machine. Open source. Nothing to unlearn if you stop using it.