Skip to content

usage.md

Latest commit

 

History

History
279 lines (195 loc) · 12.7 KB

usage.md

File metadata and controls

279 lines (195 loc) · 12.7 KB

Usage

← Back to README

Persona Modes

Persona ID Description
Gentleman gentleman Teaching-oriented mentor persona — pushes back on bad practices, explains the why
Neutral neutral Same teacher, same philosophy, no regional language — warm and professional
Custom custom Keep your existing persona/config unmanaged — gentle-ai does not inject a persona

custom is a compatibility/ownership choice, not a persona editor. Use it when you already have your own persona instructions and want gentle-ai to leave them alone.

Interactive TUI

Just run it — the Bubbletea TUI guides you through agent selection, components, skills, presets, and managed uninstall flows:

gentle-ai

The uninstall flow is also available from the TUI menu. It lets you:

  • select one or more configured agents
  • select which managed components to remove (for example sdd, persona, or context7)
  • confirm the exact uninstall scope before applying changes

Before any managed file is modified, gentle-ai creates a backup snapshot so the configuration can be restored later if needed.

CLI Commands

install

First-time setup — detects your tools, configures agents, injects all components. When installing a single agent with --agent X, gentle-ai merges the new agent into the existing installed_agents list in state.json and preserves any existing model_assignments — it does not overwrite the full state.

# 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

# OpenClaw setup after installing OpenClaw manually
gentle-ai install \
  --agent openclaw \
  --preset full-gentleman

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

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

skill-registry refresh

Refresh the project-local skill registry used by orchestrators before they delegate work:

gentle-ai skill-registry refresh
gentle-ai skill-registry refresh --force
gentle-ai skill-registry refresh --cwd /path/to/project --quiet

The command scans project skills first (skills/, .opencode/skills/, .claude/skills/, .github/skills/, and other supported workspace skill roots), then global agent skill directories. Project-local skills win over same-name global skills.

The command writes .atl/skill-registry.md and .atl/.skill-registry.cache.json. The cache fingerprint includes schema version plus each discovered SKILL.md file path, mtime, and size, so normal startup is a cheap cache-hit when skills have not changed.

Claude Code and OpenCode installs wire this command into startup/plugin hooks. Pi gets the equivalent behavior from gentle-pi; keep that extension's scan roots in sync when changing these discovery rules.

See Skill Registry for the full index-first flow and diagrams.

sync

Refresh managed assets to the current version. Use after brew upgrade gentle-ai or when you want your local configs aligned with the latest release. Does NOT reinstall binaries (engram, GGA) — only updates prompt content, skills, MCP configs, and SDD orchestrators.

Important: gentle-ai sync updates the agents recorded as installed by Gentle AI, not every AI agent config directory on your machine.

Gentle AI stores your selected install targets in ~/.gentle-ai/state.json. Future sync runs use that stored selection so Gentle AI does not accidentally write into tools you did not choose to manage. If you rerun install and select only one agent, that new selection becomes the default sync scope.

Before syncing, you can preview the active scope with gentle-ai sync --dry-run. If you want to sync agents outside the stored selection, pass them explicitly with --agent.

# Preview which agents sync will update
gentle-ai sync --dry-run

# Sync the agents currently registered in ~/.gentle-ai/state.json
gentle-ai sync

# Sync specific agents only
gentle-ai sync --agent claude-code --agent opencode

# Sync a specific component
gentle-ai sync --component sdd
gentle-ai sync --component skills
gentle-ai sync --component engram

# Refresh OpenClaw workspace instructions and MCP config
gentle-ai sync --agent openclaw

Sync is safe and idempotent — running it twice produces no changes the second time.

For OpenClaw, sync reads the active workspace from ~/.openclaw/openclaw.json (agents.defaults.workspace). It writes AGENTS.md / SOUL.md into that workspace, while MCP servers stay in the global OpenClaw config under mcp.servers.

uninstall

Remove only the gentle-ai managed configuration from one or more agents. This does not uninstall external packages or binaries — it removes managed prompt sections, MCP entries, skills/config fragments, and other managed files, then updates state.json accordingly.

Before any change is applied, gentle-ai creates a backup snapshot of the affected files.

# Partial uninstall for specific agents
gentle-ai uninstall \
  --agent claude-code \
  --agent opencode

# Partial uninstall for specific components only
gentle-ai uninstall \
  --agent claude-code \
  --component sdd,persona,context7

# Complete uninstall of managed config from all supported agents
gentle-ai uninstall --all

# Skip confirmation prompt
gentle-ai uninstall --agent cursor --component skills --yes

If no --component flag is provided for a partial uninstall, gentle-ai removes all managed uninstallable components for the selected agent set.

update / upgrade

Check for and install new versions of gentle-ai itself. The pre-upgrade backup snapshot covers only the agents recorded in state.InstalledAgents (~/.gentle-ai/state.json) — not every agent config directory that exists on your machine.

# Check if a newer version is available
gentle-ai update

# Upgrade to the latest release (downloads new binary, replaces current)
gentle-ai upgrade

After upgrading, run gentle-ai sync to refresh all managed assets to the new version's content.

If GitHub rate-limits update checks, export GITHUB_TOKEN or GH_TOKEN before running gentle-ai update/upgrade.

Set GENTLE_AI_CONFIRM_UPDATE=1 to have gentle-ai prompt for confirmation (y/N) before applying a self-update. Default behavior (no env var) applies the update without an interactive prompt.

doctor

Read-only ecosystem health diagnostics — no changes made to your configuration:

gentle-ai doctor

Checks performed:

Check What it verifies
Tool binaries Required tools present on PATH; shadow detection (wrong binary resolves first)
state.json validity Parses ~/.gentle-ai/state.json and reports any schema/corruption issues
Engram MCP reachability Confirms the Engram MCP server responds
Disk space Warns when available space is critically low

Each check reports pass, warn, or fail with an optional remedy hint. Run doctor first when troubleshooting an unexpected install or sync result.

version

gentle-ai version
gentle-ai --version
gentle-ai -v

CLI Flags (install)

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 (custom keeps your existing persona unmanaged)
--preset Preset: full-gentleman, ecosystem-only, minimal, custom (custom means manual component/skill selection)
--scope Install scope: global (default, writes to ~) or workspace (writes to ./, project root). Also settable via GENTLE_AI_INSTALL_SCOPE env var for CI/non-interactive use.
--dry-run Preview the install plan without applying changes

CLI Flags (sync)

Flag Description
--agent, --agents Agents to sync (defaults to all installed agents)
--component Sync a specific component only: sdd, engram, context7, skills, gga, permissions, theme
--profile Create or update an SDD profile: name:provider/model (sets the default model for all phases)
--profile-phase Override a specific phase in a profile: name:phase:provider/model
--sdd-profile-strategy OpenCode profile sync strategy: generated-multi or external-single-active
--include-permissions Include permissions sync (opt-in)
--include-theme Include theme sync (opt-in)

Profile examples:

# Create a "cheap" profile using a free model for all phases
gentle-ai sync --profile cheap:openrouter/qwen/qwen3-30b-a3b:free

# Override the design phase to use a stronger model
gentle-ai sync --profile-phase cheap:sdd-design:anthropic/claude-sonnet-4-20250514

# Create multiple profiles in one command
gentle-ai sync \
  --profile cheap:openrouter/qwen/qwen3-30b-a3b:free \
  --profile premium:anthropic/claude-sonnet-4-20250514

# Use compatibility mode with an external OpenCode profile manager
gentle-ai sync --agent opencode --sdd-profile-strategy external-single-active

See OpenCode SDD Profiles for the full guide.

CLI Flags (uninstall)

Flag Description
--agent, --agents Agents to uninstall managed config from (required unless using --all)
--component, --components Managed components to remove only from the selected agents
--all Remove managed configuration from all supported agents
--yes, -y Skip the confirmation prompt

Typical Workflow

# First time: install everything
brew install gentleman-programming/tap/gentle-ai
gentle-ai install --agent claude-code,cursor --preset full-gentleman

# After a new release: upgrade + sync
brew upgrade gentle-ai
gentle-ai sync

# Remove only managed SDD + persona config from one agent
gentle-ai uninstall --agent claude-code --component sdd,persona

# Adding a new agent later
gentle-ai install --agent windsurf --preset full-gentleman

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, dnf install, or winget install depending on your OS
  • Node LTS alignment: on apt/dnf systems, Node.js hints use NodeSource LTS bootstrap before package install
  • 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