Skip to content

quickstart.md

Latest commit

 

History

History
204 lines (138 loc) · 11.5 KB

quickstart.md

File metadata and controls

204 lines (138 loc) · 11.5 KB
Raw

Quickstart

Prerequisites

macOS

  • Homebrew installed and available in PATH.
  • git available.
  • If Homebrew requires trust, run brew trust --formula gentleman-programming/tap/gentle-ai once for Gentle AI™ only.
    • To install several tools from this tap, use brew trust gentleman-programming/tap instead. It trusts all current and future formulas, casks, and external commands published in the tap.

Ubuntu/Debian (and derivatives like Linux Mint, Pop!_OS)

  • apt-get available (standard on these distros).
  • sudo access for package installs.
  • git available.
  • If Node.js is missing, gentle-ai install prints this install hint: NodeSource LTS setup + apt-get install -y nodejs (npm comes bundled).
  • If using Homebrew on Linux, Bubblewrap may require unprivileged user namespaces; see docs/usage.md#homebrew-upgrade-troubleshooting.

Arch Linux (and derivatives like Manjaro, EndeavourOS)

  • pacman available (standard on these distros).
  • sudo access for package installs.
  • git available.
  • If Node.js is missing, gentle-ai install prints this install hint: pacman -S --noconfirm nodejs npm.

Fedora / RHEL family (Fedora, CentOS Stream, Rocky Linux, AlmaLinux)

  • dnf available (standard on these distros).
  • sudo access for package installs.
  • git available.
  • If Node.js is missing, gentle-ai install prints this install hint: NodeSource LTS setup + dnf install -y nodejs (npm comes bundled).

Homebrew component installs

When you select Engram or GGA, Gentle AI taps the repository and, if brew help trust succeeds, runs brew trust --formula for only the selected component before installing it. This applies to macOS and Homebrew on Linux; it does not trust the entire tap. Older Homebrew versions without trust keep the tap-and-install flow. The capability probe checks PATH first, then Homebrew's standard prefixes (/opt/homebrew, /usr/local, and /home/linuxbrew/.linuxbrew) so Engram installs still authorize the formula when Homebrew is outside PATH.

All platforms

  • Git.
  • Go 1.25.10+ (for building from source).
  • Node.js 18+ and npm: gentle-ai install checks these as required prerequisites on every platform and prints a warning with an install hint if either is missing (the Node.js hints for the distros above are listed there; npm's hint asks you to install Node.js first) — regardless of which agents/components you select. It does not install them for you, and it does not install agent runtimes either: most selected agents are configured even when their runtime isn't detected, so install those yourself. Pi and OpenCode are the exceptions: gentle-ai install stops until pi is on PATH (for Pi) or opencode --version succeeds (for OpenCode). Node.js/npm are strictly required if you select the CodeGraph community tool, which gentle-ai does install via npm install -g.
  • Pi installed and available as pi on PATH if you select the Pi agent.

Windows

  • Go 1.25.10+, because Windows installs and upgrades through go install. Official Windows binaries and the Scoop bucket are temporarily unavailable while publicly trusted Authenticode signing is provisioned, so nothing unsigned is ever fetched. With Go on PATH, gentle-ai upgrade updates itself automatically by running go install …/cmd/gentle-ai@vX.Y.Z pinned to the release tag and verified against the Go checksum database; without Go it fails closed and just prints that command. See platforms.md and the restoration gate.
# Stable channel: the latest release (v4.0.0)
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@v4.0.0

Go requires a major-version suffix (/v4) in the module path for major version 2 and above. Installing the old /v3 module path stays on the v3 line and never reaches v4.

Version Policy

The latest published stable release is v4.0.0. @latest on the /v4 module path tracks the stable channel. Use @main only to test unreleased development changes.

Install the stable channel

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

To update a source installation on Linux/macOS, run gentle-ai upgrade with Go on PATH. Source builds without an embedded release key use go install pinned to the target release, retaining the normal Go checksum database settings. Official signed binaries keep minisign-verified downloads; Homebrew-owned installations keep Homebrew. If Go is unavailable, the upgrader prints a manual source-install command without changing files. After a manual binary update, run gentle-ai sync to refresh the managed assets.

Install unreleased development changes

Only use main when testing changes that are not part of a release yet:

# macOS / Linux
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@main
gentle-ai version

# Windows (PowerShell)
go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@main
gentle-ai version

go install ignores GENTLE_AI_CHANNEL; gentle-ai reads it on later runs, where beta tracks main instead of the latest release. Tools that Homebrew manages keep updating through Homebrew. To update a beta installation later, preserve the beta channel:

# macOS / Linux
GENTLE_AI_CHANNEL=beta gentle-ai upgrade

# Windows (PowerShell)
$env:GENTLE_AI_CHANNEL="beta"; gentle-ai upgrade

gentle-ai upgrade advances the gentle-ai binary from main and refreshes managed tools on macOS, Linux, and Windows with Go on PATH.

If you re-run an installer, pass beta explicitly because both installers default to stable:

# 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

Go module proxy cache: proxy.golang.org can lag behind new commits on main for up to several hours. If manual go install ...@main does not update to the newest commit, bypass the cache with GOPROXY=direct go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@main (PowerShell: $env:GOPROXY="direct"; go install github.com/gentleman-programming/gentle-ai/v4/cmd/gentle-ai@main).

The managed install scripts select the latest version for their chosen channel and do not accept arbitrary release pins. Use go install with an exact tag when you need a reproducible prerelease or stable version.

Run

gentle-ai install --dry-run

Use --dry-run first to validate selections and execution plan without applying changes. The dry-run output includes a Platform decision line showing the detected OS, distro, package manager, and support status.

From a source clone, run go run ./cmd/gentle-ai install (with or without --dry-run) instead.

First real install

gentle-ai install

The installer detects your platform automatically — no flags needed to select macOS vs Linux. On Linux, it uses the first supported package manager it finds on PATH; see Supported Platforms for the full list and detection order.

For a beta install that selects Engram, Go must be on PATH. If it is missing, dependency preflight stops before the backup snapshot or component apply and prints a platform-specific installation hint.

Stable Engram installs and beta plans without Engram do not gain a Go requirement.

After completion, verify that agent configs and selected components were installed to their expected paths.

The agents you select during install become the default scope for future gentle-ai sync runs. Gentle AI records that selection in ~/.gentle-ai/state.json and does not automatically sync every agent config directory that exists on your machine. To check what will be updated after an upgrade, run:

gentle-ai sync --dry-run

To update a different set explicitly, pass every target agent:

gentle-ai sync --agent claude-code --agent opencode

Verification outcome

When checks pass, the installer prints a ready message that names the agent commands you installed, for example:

You're ready. Run `claude` or `opencode` and start building.

If something looks wrong after install, run gentle-ai doctor for a read-only health check. It verifies tool binaries, state.json validity, Engram™ MCP reachability, and disk space — each check reports pass/warn/fail with a remedy hint.

For state.json read errors, inspect the file and parent directory; check permissions and ownership when access is denied, and keep the existing state. For invalid JSON, restore a valid backup or repair the content while preserving your installation settings. Re-run gentle-ai doctor afterward; it never changes the file or its permissions.

For a Pi-only install, the plan shows the Pi package stack instead of Gentle AI components. It installs gentle-pi, gentle-engram, pi-web-access, and pi-btw through Pi's package manager, without a separate pi-engram init registration. Engram exposes native Pi tools; Pi's built-in MCP support (Pi >= 0.99.0) runs other servers, such as CodeGraph, from mcp.json. Install and sync also repair unambiguous Engram package duplicates while preserving the retained version and object options; conflicting declarations require manual resolution. Gentle AI removes a previously installed pi-mcp-adapter, because an extension that registers /mcp replaces Pi's built-in MCP support.

Start working with ODD

Open your agent in the project and describe an outcome, for example: "Add CSV export using the existing report filters." Organic Driven Development (ODD) is the development workflow: explore, implement authorized work, and check it. Substantial work keeps one recoverable feature document; small/read-only work avoids durable artifacts.

Hardening recommendations for users

Gentle AI pins versions and disables postinstall scripts on every npm install it generates. When you install the permissions component, a sensitive-paths deny list is applied to Claude Code and OpenCode blocking access to ~/.ssh/*, **/*.pem, **/*.key, **/.env*, ~/.aws/credentials, and other credential paths. See Components for the full list.

For broader protection across npm packages you install yourself, set these once on your machine:

  • npm config set ignore-scripts true — blocks postinstall scripts globally; the primary supply-chain attack vector.
  • npm config set min-release-age 3 — skip packages published in the last 3 days; catches malicious typosquats before you install them.
  • npm config set allow-git none — block git: dependencies, which can be moving targets.

Optional wrapper tools for extra defense:

  • npq — audits a package against several heuristics before it installs.
  • sfw (Socket Firewall) — runtime guard that intercepts suspicious behavior at install/run time.

Unsupported platforms

If you run the installer on an unsupported OS or Linux distro, it exits immediately with an error:

  • unsupported operating system: only macOS, Linux, and Windows are supported (detected <os>)
  • unsupported linux distro: no package manager found on PATH (detected distro <distro>). The full error lists the package managers it searched, in order, and a command to check which ones your machine has.