AI Gentle Stack

⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣠⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣴⣾⣿⡽⠟⠛⠻⣶⣄⠀⢀⣐⣒⣒⣶⣴⣾⡿⢷⣶⣽⡢⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡾⣿⣿⢿⠋⠀⠀⠀⠀⠀⠉⠛⠓⠒⠛⠚⠛⠉⣿⠀⠀⣧⡏⠻⣷⣽⡦⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣻⡾⠋⣇⢸⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠀⠀⠉⠀⠀⢸⠙⠻⣿⣷⣶⣄⡀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⣠⣶⣿⠋⠈⠀⠛⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⠀⠀⠀⠀⠀⠀⠀⠉⠀⠀⠈⡿⣷⣽⣇⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⢀⣞⡿⠟⣟⠀⠀⠀⠀⠀⠀⠀⠀⠸⡆⠀⠀⠀⣆⠀⠀⡀⢸⠇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠁⠈⠻⣯⡳⣄⠀⠀⠀⠀⠀
⠀⠀⠀⠀⢀⣽⠟⠁⠀⠘⠃⠀⠀⠀⠀⢰⡀⠀⠀⢹⡀⠀⠀⢸⡄⢀⣇⡾⣠⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⢻⣾⣅⠀⠀⠀⠀
⣀⣀⣠⡴⠿⣅⠐⢦⡀⠀⠀⠀⠲⣄⠀⠀⣙⣦⣶⣾⣻⣶⣶⠾⠿⠾⢿⣿⣿⣻⢷⣢⢤⣀⠀⠀⠀⠀⠀⠀⠀⡀⠀⣴⠛⣿⣷⣄⡀⠀
⠹⠿⢿⣷⣦⣼⣷⣤⣻⣶⣤⣀⣀⣬⣷⡯⠷⠾⢿⣿⣭⣄⣀⣀⣀⣀⣀⣤⣭⡿⠿⢾⣿⣿⣿⣦⣤⣤⣤⣶⢾⡷⣿⣷⣾⣷⣿⡿⠿⠟
⠀⠀⠘⣿⡝⣿⡿⢻⣿⡿⢩⡞⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠉⠀⠀⠀⠀⠀⠀⠀⠀⠰⡄⠀⠀⠀⠀⠘⢦⠹⣮⢷⠹⣷⣿⠀⠀⠀
⠀⠀⠀⠙⣷⣿⠁⡞⣾⠀⡞⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤⡇⠀⠀⠀⠀⠀⢸⡆⢸⢸⣦⡟⠁⠀⠀⠀
⠀⠀⠀⠀⠈⢻⣄⡏⣿⠀⡇⠀⠀⠀⠀⠀⢰⠀⠀⠀⠀⠀⠀⠀⢐⣧⠀⠀⠀⠀⠀⠀⠀⠈⠁⠀⠀⠀⠀⠀⣼⡇⠘⣼⠏⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠙⠻⣧⣧⢣⠀⠀⠀⠀⠀⢸⠀⠀⠀⠀⠀⠀⠀⠸⠏⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣸⢹⣠⡾⠃⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⢿⣧⡘⣆⠀⠀⠘⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⠀⠀⣴⣷⣿⡋⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠙⠻⠷⣤⣀⣹⣄⠀⠀⠀⠀⠀⠀⡇⠀⠀⢀⠀⡆⠀⠀⣀⣴⣧⣴⣟⠯⠛⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠽⠿⠿⠷⠶⢤⣤⣴⣿⣦⣶⣾⣿⣷⣾⣻⣿⠝⠛⠉⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠉⠉⠉⠛⠛⠛⠛⠛⠊⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀

AI Gentle Stack

One command. Any agent. Any OS. The Gentleman AI ecosystem -- configured and ready.

What It Does

This is NOT an AI agent installer. Most agents are easy to install. This is an ecosystem configurator -- it takes whatever AI coding agent(s) you use and supercharges them with the Gentleman stack:

Engram -- persistent cross-session memory
SDD -- Spec-Driven Development workflow (plan before you code)
Skills -- curated coding patterns (SDD workflow + foundation skills like Go testing and skill creation)
MCP servers -- Context7 for real-time library documentation
GGA -- Gentleman Guardian Angel AI provider switcher
Persona & config -- security-first permissions, teaching-oriented persona, themes

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.

Quick Start

macOS / Linux

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

Windows (PowerShell)

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

This downloads the latest release for your platform and launches the interactive TUI. No Go toolchain required.

Install

Homebrew (macOS / Linux)

brew tap Gentleman-Programming/homebrew-tap
brew install gentle-ai

Go install (any platform with Go 1.24+)

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

Windows (PowerShell)

# Option 1: PowerShell installer (downloads binary from GitHub Releases)
irm https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.ps1 | iex

# Option 2: Go install (requires Go 1.24+)
go install github.com/gentleman-programming/gentle-ai/cmd/gentle-ai@latest

From releases

Download the binary for your platform from GitHub Releases.

Supported Agents

Agent	ID	Skills	MCP	Sub-agents	Output Styles	Slash Commands	Config Path
Claude Code	`claude-code`	Yes	Yes	Yes	Yes	No	`~/.claude`
OpenCode	`opencode`	Yes	Yes	Yes	No	Yes	`~/.config/opencode`
Gemini CLI	`gemini-cli`	Yes	Yes	Yes (experimental)	No	No	`~/.gemini`
Cursor	`cursor`	Yes	Yes	Yes	No	No	`~/.cursor`
VS Code Copilot	`vscode-copilot`	Yes	Yes	Yes	No	No	`~/.copilot` + VS Code User profile

All agents receive the full SDD orchestrator (agent-teams-lite) injected into their system prompt, plus skill files written to their skills directory. Every agent supports sub-agent delegation natively, enabling the full SDD orchestration workflow with parallel sub-agents.

Notes

Gemini CLI sub-agents are experimental and require experimental.enableAgents: true in settings.json. Custom sub-agents are defined as markdown files in ~/.gemini/agents/.
Cursor supports async sub-agents (v2.5+) that can run in background and spawn nested sub-agent trees.
VS Code Copilot uses the runSubagent tool with support for parallel execution and custom agent definitions.
Output Styles are currently a Claude Code exclusive feature (~/.claude/output-styles/).
Slash Commands are currently supported by OpenCode only.
VS Code Copilot stores skills under ~/.copilot/skills/ (global), system prompt under Code/User/prompts/gentle-ai.instructions.md, and MCP config under Code/User/mcp.json.

Components

Component	ID	Description
Engram	`engram`	Persistent cross-session memory
SDD	`sdd`	Spec-Driven Development workflow (9 phases)
Skills	`skills`	Curated coding skill library
Context7	`context7`	MCP server for live framework/library documentation
Persona	`persona`	Gentleman, neutral, or custom behavior mode
Permissions	`permissions`	Security-first defaults and guardrails
GGA	`gga`	Gentleman Guardian Angel -- AI provider switcher
Theme	`theme`	Gentleman Kanagawa theme overlay

GGA Behavior

gentle-ai --component gga installs/provisions the gga binary globally on your machine.

It does not run project-level hook setup automatically (gga init / gga install) because that should be an explicit decision per repository.

After global install, enable GGA per project with:

gga init
gga install

Skills

11 curated skill files organized by category, injected into your agent's configuration:

SDD (Spec-Driven Development)

Skill	ID	Description
SDD Init	`sdd-init`	Bootstrap SDD context in a project
SDD Explore	`sdd-explore`	Investigate codebase before committing to a change
SDD Propose	`sdd-propose`	Create change proposal with intent, scope, approach
SDD Spec	`sdd-spec`	Write specifications with requirements and scenarios
SDD Design	`sdd-design`	Technical design with architecture decisions
SDD Tasks	`sdd-tasks`	Break down a change into implementation tasks
SDD Apply	`sdd-apply`	Implement tasks following specs and design
SDD Verify	`sdd-verify`	Validate implementation matches specs
SDD Archive	`sdd-archive`	Sync delta specs to main specs and archive

Foundation

Skill	ID	Description
Go Testing	`go-testing`	Go testing patterns including Bubbletea TUI testing
Skill Creator	`skill-creator`	Create new AI agent skills following the Agent Skills spec

These foundation skills are installed by default with both full-gentleman and ecosystem-only presets.

Presets

Preset	ID	What's Included
Full Gentleman	`full-gentleman`	All components + all skills + gentleman persona
Ecosystem Only	`ecosystem-only`	All components + P0 skills + gentleman persona
Minimal	`minimal`	Engram + Persona + Permissions only
Custom	`custom`	You pick components, skills, and persona individually

Persona Modes

Persona	ID	Description
Gentleman	`gentleman`	Teaching-oriented mentor persona -- pushes back on bad practices, explains the why
Neutral	`neutral`	Clean, professional tone -- no personality, just facts
Custom	`custom`	Bring your own persona instructions

Usage

Interactive TUI

Just run it -- the Bubbletea TUI guides you through agent selection, components, skills, and presets:

gentle-ai

CLI Mode

# Full ecosystem for multiple agents
gentle-ai install \
  --agent claude-code,opencode,gemini-cli \
  --preset full-gentleman

# Minimal setup for Cursor
gentle-ai install \
  --agent cursor \
  --preset minimal

# Pick specific components and skills
gentle-ai install \
  --agent claude-code \
  --component engram,sdd,skills,context7,persona,permissions \
  --skill go-testing,skill-creator \
  --persona gentleman

# Dry-run first (preview plan without applying changes)
gentle-ai install --dry-run \
  --agent claude-code,opencode \
  --preset full-gentleman

CLI Flags

Flag	Description
`--agent`, `--agents`	Agents to configure (comma-separated)
`--component`, `--components`	Components to install (comma-separated)
`--skill`, `--skills`	Skills to install (comma-separated)
`--persona`	Persona mode: `gentleman`, `neutral`, `custom`
`--preset`	Preset: `full-gentleman`, `ecosystem-only`, `minimal`, `custom`
`--dry-run`	Preview the install plan without applying changes
`--version`, `-v`	Print version and exit

Dependency Management

gentle-ai auto-detects prerequisites before installation and provides platform-specific guidance:

Detected tools: git, curl, node, npm, brew, go
Version checks: validates minimum versions where applicable
Platform-aware hints: suggests brew install, apt install, pacman -S, or winget install depending on your OS
Dependency-first approach: detects what's installed, calculates what's needed, shows the full dependency tree before installing anything, then verifies each dependency after installation

Supported Platforms

Platform	Package Manager	Status
macOS (Apple Silicon + Intel)	Homebrew	Supported
Linux (Ubuntu/Debian)	apt	Supported
Linux (Arch)	pacman	Supported
Windows 10/11	winget	Supported

Derivatives are detected via ID_LIKE in /etc/os-release (Linux Mint, Pop!_OS, Manjaro, EndeavourOS, etc.).

Release binaries are built for linux, darwin, and windows on both amd64 and arm64.

Windows Notes

winget is used as the default package manager (pre-installed on Windows 10/11).
npm global installs do not require sudo on Windows (user-writable by default).
curl is pre-installed on Windows 10+ and does not require separate installation.
PowerShell is the default shell when $SHELL is not set.
Release archives use .zip format on Windows (.tar.gz on macOS/Linux).

Windows Security Verification

Some antivirus products can flag unsigned Go binaries heuristically.

Use the release checksum to verify integrity:

# 1) Download checksums.txt from the same release tag
# 2) Compute local hash
Get-FileHash .\gentle-ai_<VERSION>_windows_amd64.zip -Algorithm SHA256

# 3) Compare the hash with checksums.txt entry for that file

If the hash matches checksums.txt, the file is authentic for that release.

Windows Config Paths

Agent	Windows Config Path
Claude Code	`%USERPROFILE%\.claude\`
OpenCode	`%USERPROFILE%\.config\opencode\`
Gemini CLI	`%USERPROFILE%\.gemini\`
Cursor	`%USERPROFILE%\.cursor\`
VS Code Copilot	`%APPDATA%\Code\User\` (settings, MCP, prompts) + `%USERPROFILE%\.copilot\` (skills)

Architecture

cmd/gentle-ai/             CLI entrypoint
internal/
  app/                     Command dispatch + runtime wiring
  model/                   Domain types (agents, components, skills, presets, personas)
  catalog/                 Registry definitions (agents, skills, components)
  system/                  OS/distro detection, dependency checks, platform guards
  cli/                     Install flags, validation, orchestration, dry-run
  planner/                 Dependency graph, resolution, ordering, review payloads
  installcmd/              Profile-aware command resolver (brew/apt/pacman/winget/go install)
  pipeline/                Staged execution + rollback orchestration
  backup/                  Config snapshot + restore
  assets/                  Embedded skill files + persona templates
  components/              Per-component install/inject logic
    engram/  sdd/  skills/  mcp/  persona/  theme/  permissions/  gga/
    filemerge/             Marker-based file merging (inject without clobbering)
  agents/                  Agent adapters (config strategy per agent)
    claude/  opencode/  gemini/  cursor/  vscode/
  verify/                  Post-apply health checks + reporting
  tui/                     Bubbletea TUI (Rose Pine theme)
    styles/  screens/
scripts/                   Installer scripts (bash + PowerShell)
e2e/                       Docker-based E2E tests (Ubuntu + Arch)
testdata/                  Golden test fixtures

Testing

# Unit tests
go test ./...

# Docker E2E (Ubuntu + Arch, requires Docker)
RUN_FULL_E2E=1 RUN_BACKUP_TESTS=1 ./e2e/docker-test.sh

# Dry-run smoke test (macOS/Linux)
gentle-ai install --dry-run --agent claude-code --preset minimal

# Dry-run smoke test (Windows PowerShell)
gentle-ai.exe install --dry-run --agent claude-code --preset minimal

Test coverage:

26 test packages across the codebase
260+ test functions covering all agent adapters, components, and system detection
78 E2E test functions running in Docker containers (Ubuntu + Arch)
17 golden files for snapshot testing component output
Full pipeline tested: detection, planning, execution, backup, restore, verification
All 5 agent adapters have unit tests with cross-platform path validation

Relationship to Gentleman.Dots

	Gentleman.Dots	AI Gentle Stack
Purpose	Dev environment (editors, shells, terminals)	AI development layer (agents, memory, skills)
Installs	Neovim, Fish/Zsh, Tmux/Zellij, Ghostty	Configures Claude Code, OpenCode, Gemini CLI, Cursor, VS Code Copilot
Overlap	None -- complementary	None -- different layer

Install Gentleman.Dots first for your dev environment, then AI Gentle Stack for the AI layer on top.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
.github/workflows		.github/workflows
cmd/gentle-ai		cmd/gentle-ai
docs		docs
e2e		e2e
internal		internal
scripts		scripts
testdata/golden		testdata/golden
.dockerignore		.dockerignore
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
PRD.md		PRD.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

AI Gentle Stack

Table of Contents

What It Does

Quick Start

macOS / Linux

Windows (PowerShell)

Install

Homebrew (macOS / Linux)

Go install (any platform with Go 1.24+)

Windows (PowerShell)

From releases

Supported Agents

Notes

Components

GGA Behavior

Skills

SDD (Spec-Driven Development)

Foundation

Presets

Persona Modes

Usage

Interactive TUI

CLI Mode

CLI Flags

Dependency Management

Supported Platforms

Windows Notes

Windows Security Verification

Windows Config Paths

Architecture

Testing

Relationship to Gentleman.Dots

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 41

Packages 0

Uh oh!

Contributors 5

Languages

Packages