From 3282b749bc8bdc5876cf8388b0a3838b67173dfa Mon Sep 17 00:00:00 2001 From: Vinicius Vasconcelos Date: Wed, 8 Jul 2026 14:46:38 -0300 Subject: [PATCH] docs(genie): fix plugin installation instructions The install docs describe symlinking ~/.claude/plugins/genie directly, but the current CLI (dist/genie.js syncPlugin()) manages the plugin through Claude Code's marketplace system instead (~/.claude/plugins/marketplaces/automagik, installed_plugins.json). Following the documented symlink approach leaves the plugin undiscoverable and slash commands missing. - Replace the symlink step with the actual `claude plugin marketplace add` / `claude plugin install` flow - Update the genie doctor sample output to match real v4 output, and note that doctor does not check plugin registration - Add a "Verify the plugin is registered" section using `claude plugin list`, plus a restart-required note (plugin changes need a fresh Claude Code session to load) - Warn that `genie update` can downgrade the marketplace plugin version as a side effect (npm/Bun dist-tag lags the marketplace source), with the recovery command - Correct the uninstall section: it doesn't remove the npm/Bun package or unregister the Claude Code plugin, contrary to the current text --- genie/installation.mdx | 83 ++++++++++++++++++++++++++++++++++-------- 1 file changed, 67 insertions(+), 16 deletions(-) diff --git a/genie/installation.mdx b/genie/installation.mdx index c130a03..0ab4fd4 100644 --- a/genie/installation.mdx +++ b/genie/installation.mdx @@ -47,8 +47,8 @@ curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh Downloads and installs `@automagik/genie` globally using your system's package manager. - - Symlinks the plugin to `~/.claude/plugins/genie` so Claude Code can discover every slash command. + + Runs `claude plugin marketplace add automagik-dev/genie` and `claude plugin install genie@automagik`, which registers Genie in Claude Code's plugin marketplace system (`~/.claude/plugins/installed_plugins.json`) so its skills — `/wish`, `/work`, `/review`, `/brainstorm`, and friends — are discoverable. Wires up hooks for agent identity injection and event capture. @@ -105,27 +105,67 @@ genie setup ## Verify your install -Run the diagnostic tool to confirm every component is wired up: +Run the diagnostic tool to confirm the CLI, prerequisites, and local config are wired up: ```bash genie doctor ``` ```text -Genie Doctor — Checking your setup... - -✓ genie CLI found (v4.260324.8) -✓ Claude Code installed -✓ tmux available (3.4) -✓ Git configured -✓ GitHub CLI authenticated -✓ Plugin symlink active (~/.claude/plugins/genie → ...) -✓ Git hooks configured -✓ Config file exists (~/.genie/config.json) - -All checks passed. +Genie Doctor +──────────────────────────────────────── + +Prerequisites: + ✓ tmux + ✓ jq + ✓ bun / node + ✓ Claude Code + +Installer Resolution: + ✓ Resolved binary ... + +Configuration: + ✓ Genie config exists ~/.genie/config.json + ✓ Setup complete + ✓ Claude settings exists ~/.claude/settings.json + +──────────────────────────────────────── ``` + + `genie doctor` checks the CLI and local config — it does **not** currently verify that the Claude Code plugin is registered. Use the plugin check below as well; a green `genie doctor` does not by itself mean your slash commands will work. + + +### Verify the plugin is registered + +`genie doctor` doesn't check plugin registration, so confirm it separately with Claude Code's own CLI: + +```bash +claude plugin list +``` + +You should see: + +```text +Installed plugins: + + ❯ genie@automagik + Version: 5.x.x + Scope: user + Status: ✔ enabled +``` + +If it's missing, register it manually: + +```bash +claude plugin marketplace add automagik-dev/genie +claude plugin install genie@automagik +``` + + + **Restart required.** After any install or update, Claude Code only picks up plugin changes ("skills"/slash commands like `/wish`, `/work`, `/review`) on the *next* session start. If a slash command doesn't autocomplete, restart your `claude` session before assuming the install failed. + + ## Environment variables | Variable | Default | Description | @@ -142,13 +182,24 @@ genie update # Stable channel genie update --next # Development builds ``` + + `genie update` pulls the CLI from npm/Bun's dist-tag, which can lag behind the plugin marketplace source on GitHub. If `genie update` reports an older version than what `claude plugin list` shows, it can overwrite the plugin's marketplace metadata down to the older version as a side effect. Recover with: + + ```bash + claude plugin marketplace update automagik + claude plugin update genie@automagik + ``` + + Then restart your Claude Code session. + + ## Uninstalling ```bash genie uninstall ``` -This removes the CLI, plugin symlink, and git hooks. Your project's `.genie/` state directory is preserved. +This removes the hook script, orchestration rules, `~/.local/bin` CLI symlinks, and the global `~/.genie` directory. It does **not** remove the npm/Bun package itself — the command will remind you to also run `bun remove -g @automagik/genie` or `npm uninstall -g @automagik/genie`. It also does **not** unregister the Claude Code plugin; run `claude plugin uninstall genie@automagik` separately if you want that removed too. Your project's local `.genie/` state directory is preserved. ## What's next