Gentle-AI

Gentle-AI — Ecosystem, Frameworks, Workflows for AI coding agents.

What It Does

Gentle-AI is NOT an AI agent installer. Most agents are easy to install. It is an ecosystem configurator -- it takes whatever AI coding agent(s) you use and supercharges them with persistent memory, Spec-Driven Development workflows, curated coding skills, MCP servers, an AI provider switcher, a teaching-oriented persona with security-first permissions, and per-phase model assignment so each SDD step can run on a different model.

Before: "I installed Claude Code / OpenCode / Cursor, but it's just a chatbot that writes code."

After: Your agent now has memory, skills, workflow, MCP tools, and a persona that actually teaches you.

15 Supported Agents

Note: This project supersedes Agent Teams Lite (now archived). Everything ATL provided is included here with better installation, automatic updates, and persistent memory.

Delegation Triggers

Gentle-AI keeps the parent/orchestrator thread thin. Once a task stops being small, delegation or an explicit SDD phase boundary is expected rather than optional.

The goal is not ceremony. The goal is to avoid accidental chaos while preserving one responsible orchestrator and one writer thread.

Quick Start

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash

Windows

irm https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.ps1 | iex

This installs to %LOCALAPPDATA%\gentle-ai\bin and works with Gentle AI's built-in updater.

Try the beta channel (test main before a release)

The beta channel builds Gentle AI straight from main, so you need Go 1.24+ installed first. Use it to try unreleased changes and report issues early.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash -s -- --channel beta

Windows (PowerShell)

$env:GENTLE_AI_CHANNEL="beta"; irm https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.ps1 | iex

To keep upgrading on beta later, run $env:GENTLE_AI_CHANNEL="beta"; gentle-ai upgrade on Windows or GENTLE_AI_CHANNEL=beta gentle-ai upgrade on macOS/Linux. To return to stable, reinstall with the default installer.

After install: project-level setup

Once your agents are configured, open your AI agent in a project and run these two commands to register the project context:

These are not required for basic usage. The SDD orchestrator runs /sdd-init automatically if it detects no context. Startup hooks normally keep the skill registry fresh for agents that support hooks, including Codex, Claude Code, OpenCode, and Pi through gentle-pi. If you start Pi with pi -ns, startup skill loading/hooks are skipped, so run the registry refresh manually when you need updated project rules.

Run gentle-ai doctor at any time for a read-only health check of your ecosystem (tool binaries, state.json, Engram reachability, disk space).

Install

Recommended

# macOS / Linux
brew tap Gentleman-Programming/homebrew-tap
brew trust --formula gentleman-programming/tap/gentle-ai  # one-time, for Homebrew tap trust
brew install gentle-ai

# Windows
irm https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.ps1 | iex

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

scoop bucket add gentleman https://github.com/Gentleman-Programming/scoop-bucket
scoop install gentle-ai

By default, gentle-ai install writes agent-scoped files to each selected agent's global config directory. To keep the Gentleman stack isolated to one project, run:

gentle-ai install --scope=workspace

Workspace scope is not Claude-only; it applies to selected agents for agent-scoped files such as system prompts, skills, SDD agents, and persona files. Global-only integrations remain global by design.

Backups

Every install, sync, and upgrade automatically snapshots your config files. Backups are compressed (tar.gz), deduplicated (identical configs are not re-backed up), and auto-pruned (keeps the 5 most recent). Pin important backups via the TUI (p key) to protect them from pruning.

See Backup & Rollback Guide for details.

Key Features You Should Know About

OpenCode SDD Profiles

Assign different AI models to different SDD phases -- a powerful model for design, a fast one for implementation, a cheap one for exploration. OpenCode uses gentle-orchestrator as the base SDD conductor, and generated named profiles still appear as sdd-orchestrator-{name} entries.

# Via CLI
gentle-ai sync --profile cheap:openrouter/qwen/qwen3-30b-a3b:free
gentle-ai sync --profile-phase cheap:sdd-design:anthropic/claude-sonnet-4-20250514

# Or via TUI: gentle-ai → "OpenCode SDD Profiles" → Create

After creating a profile, open OpenCode and press Tab to switch between gentle-orchestrator (default) and your custom profiles.

Full guide: OpenCode SDD Profiles

Engram (Persistent Memory)

Your AI agent automatically remembers decisions, bugs, and context across sessions. You don't need to do anything -- but when you do:

engram projects list          # See all projects with memory counts
engram projects consolidate   # Fix name drift ("my-app" vs "My-App")
engram search "auth bug"      # Find a past decision from the terminal
engram tui                    # Visual memory browser

Full reference: Engram Commands

Documentation

Community Highlights

This project gets better when the community builds on top of it.

Community Integrations

• sub-agent-statusline — optional OpenCode TUI plugin that shows sub-agent activity, status, elapsed time, and token/context usage when OpenCode exposes it.
• sdd-engram-plugin — optional OpenCode TUI plugin to manage SDD profiles and browse Engram memories directly from OpenCode, with runtime profile activation and no restart required.

When you select OpenCode in the installer, Gentle-AI asks whether to register each community plugin and offers a browser shortcut to review the repository first. Gentle-AI only ensures ~/.config/opencode/tui.json exists and adds the plugin package names to its plugin array; OpenCode installs/loads those packages the next time it starts. Once OpenCode has materialized a plugin under ~/.config/opencode/node_modules/, gentle-ai update can compare its local package.json version with the plugin's GitHub releases.

Contributors

This project exists because of the community. See CONTRIBUTORS.md for the full list.

Next Steps

• Just installed? Read Intended Usage -- the one page that explains the mental model.
• Using OpenCode? Set up SDD Profiles to assign different models per phase.
• Using Pi? Read Pi Agent for Pi commands, persona, model assignments, and package behavior.
• Want to share memory across machines? Learn engram sync in the Engram reference.
• Ready to contribute? Check CONTRIBUTING.md and the open issues.