Skip to content

docs(genie): fix plugin installation instructions #77

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mvmvasconcelos wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(genie): fix plugin installation instructions #77

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 67 additions & 16 deletions genie/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,8 +47,8 @@ curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh
<Step title="Install the package">
Downloads and installs `@automagik/genie` globally using your system's package manager.
</Step>
<Step title="Link the Claude Code plugin">
Symlinks the plugin to `~/.claude/plugins/genie` so Claude Code can discover every slash command.
<Step title="Register the Claude Code plugin">
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.
</Step>
Comment on lines +50 to 52

@gemini-code-assist gemini-code-assist Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

If the bootstrap script (install.sh) does not automate the registration of the Claude Code plugin, listing this step under the "One-line bootstrap" <Steps> block can be misleading to users. If this is a manual step that the user must perform after running the bootstrap script, we should explicitly clarify that in the description.

  <Step title="Register the Claude Code plugin">
    Requires manual registration. Run `claude plugin marketplace add automagik-dev/genie` and `claude plugin install genie@automagik` to register Genie in Claude Code's plugin marketplace system (`~/.claude/plugins/installed_plugins.json`) so its skills — `/wish`, `/work`, `/review`, `/brainstorm`, and friends — are discoverable.
  </Step>

<Step title="Configure git hooks">
Wires up hooks for agent identity injection and event capture.
Expand Down Expand Up @@ -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

────────────────────────────────────────
```

<Warning>
`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.
</Warning>

### 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
```

<Note>
**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.
</Note>
Comment on lines +165 to +167

@gemini-code-assist gemini-code-assist Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Instead of requiring a full session restart, Claude Code also supports reloading active plugins dynamically during a session using the /reload-plugins command. We should mention this as a quicker alternative to restarting the entire session.

<Note>
  **Restart or reload 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, or when you run `/reload-plugins` within an active session. If a slash command doesn't autocomplete, reload or restart your `claude` session before assuming the install failed.
</Note>


## Environment variables

| Variable | Default | Description |
Expand All @@ -142,13 +182,24 @@ genie update # Stable channel
genie update --next # Development builds
```

<Warning>
`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.
</Warning>
Comment on lines +185 to +194

@gemini-code-assist gemini-code-assist Bot Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Similarly, we can mention the /reload-plugins command here as an alternative to restarting the Claude Code session after recovering from a version downgrade.

<Warning>
  `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 or run /reload-plugins.


## 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

Expand Down