Skip to content

usage.md

Latest commit

 

History

History
338 lines (238 loc) · 16.3 KB

usage.md

File metadata and controls

338 lines (238 loc) · 16.3 KB
Raw

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.

Codex, Claude Code, and OpenCode installs wire this command into startup/plugin hooks. Pi gets the equivalent behavior from gentle-pi; keep those hook/plugin 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

# 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. When files change, the summary reports the changed file count and lists the changed file paths.

sync refreshes the managed component set for the selected agents. It does not support --component; use --include-permissions or --include-theme for the opt-in components that are excluded from the default sync scope.

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.

For Hermes, gentle-ai is detect-only: it cannot install Hermes. Install Hermes manually first. Detection is driven by the ~/.hermes config directory (the binary being on PATH is reported separately). Once Hermes is detected, gentle-ai install --agent hermes injects context7 and Engram MCP blocks into ~/.hermes/config.yaml, writes the SDD orchestrator and persona into ~/.hermes/SOUL.md, and copies skills to ~/.hermes/skills/. Use gentle-ai sync --agent hermes to update the managed configuration after upgrades.

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.

If Homebrew refuses an upgrade from an untrusted tap, trust only the artifact Homebrew names and retry the upgrade:

# Formula tools, for example gentle-ai
brew trust --formula gentleman-programming/tap/gentle-ai
brew upgrade gentle-ai

# Cask tools, for example engram
brew trust --cask gentleman-programming/tap/engram
brew upgrade engram

Self-update prompt behavior (changed in v1.x slice 5 — GENTLE_AI_CONFIRM_UPDATE removed):

Situation Behavior
Interactive terminal (TTY) Always prompts Apply now? [Y/n]. Empty Enter accepts.
Non-TTY (CI, pipe, script) Auto-declines — never hangs.
GENTLE_AI_YES=1 Auto-accepts without prompting (for scripted upgrades). This variable is inherited by subprocesses, so scope it to a single invocation when needed (e.g. GENTLE_AI_YES=1 gentle-ai …).
GENTLE_AI_NO_SELF_UPDATE=1 Skips the self-update check entirely.

GENTLE_AI_CONFIRM_UPDATE was removed in slice 5. It is now ignored if set.

GENTLE_AI_SELF_UPDATE_DONE is an internal loop guard and should not be set manually.

model assignment

The TUI Configure Models screen can assign different models to SDD phases, sdd-onboard, and Judgment Day agents (jd-judge-a, jd-judge-b, jd-fix-agent) when the selected agent supports those slots. This lets you keep review or apply phases on stronger models while routing cheaper phases to faster models.

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)
--sdd-mode SDD orchestrator mode: single or multi
--scope Install scope for agent-scoped files: global (default, writes to each selected agent's global config directory) or workspace (writes to the current 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)
--skill, --skills Skills to sync (comma-separated; defaults to selected preset skills)
--sdd-mode SDD orchestrator mode: single or multi
--strict-tdd Enable Strict TDD Mode for SDD agents
--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)
--dry-run Preview the sync plan without applying changes

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

Homebrew upgrade troubleshooting

Homebrew 6 can require explicit trust for non-official taps and, on Linux, can sandbox builds with Bubblewrap. gentle-ai upgrade and scripts/install.sh auto-trust only the Gentle AI formula, but manual upgrades may still need this one-time command:

brew trust --formula gentleman-programming/tap/gentle-ai
brew upgrade gentle-ai

On Linux, if Homebrew reports that Bubblewrap cannot create a rootless sandbox, there is nothing for Gentle AI to install: Bubblewrap is already present, but the host blocks the rootless namespace primitives it needs. This is a security tradeoff and should be an explicit admin decision. If your policy allows it, fix the host namespace policy first:

sudo sysctl -w kernel.unprivileged_userns_clone=1
sudo sysctl -w user.max_user_namespaces=28633
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 || true

Use HOMEBREW_NO_SANDBOX_LINUX=1 brew upgrade gentle-ai only as a final workaround when your distro policy forbids the namespace settings; it disables Homebrew's Linux sandbox for that command.

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