Installation

Genie runs on Linux and macOS. Windows is not supported today (WSL2 works but is not on the tested matrix). You’ll also need Node.js 18+ or Bun, Claude Code (or another agent), tmux, Git, and — recommended — the GitHub CLI.

Prerequisites

Tool	Required	Purpose
Node.js 18+ or Bun	Yes	Runtime for the CLI
Claude Code	Yes	AI agent backend (or swap for Codex, Open Claw, or a BYOA adapter)
tmux	Yes	Agent process management
Git	Yes	Version control and worktrees
GitHub CLI (`gh`)	Recommended	PR creation and issue tracking

Install Genie

Pick the path that matches how you manage tools on your machine. The one-line bootstrap is the fastest; npm/Bun are the most familiar; “from source” is for contributors.

Homebrew (macOS / Linuxbrew)

A first-class Homebrew tap (automagik/tap/genie) is on the roadmap but not published yet. Until then, macOS users can run the one-line bootstrap below — it auto-detects Homebrew and uses it to install any missing prerequisites (Node, tmux, gh). Track the tap rollout in the GitHub release workflow.

# Coming soon — tap not yet public
brew tap automagik/tap
brew install automagik/tap/genie

One-line bootstrap

The bootstrap script detects your system and installs via the best available method (including Homebrew on macOS for prerequisites):

curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh | bash

Install the package

Downloads and installs @automagik/genie globally using your system’s package manager.

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.

Configure git hooks

Wires up hooks for agent identity injection and event capture.

Run genie doctor

Verifies prerequisites and config, then prints a green checklist (or tells you what’s missing).

npm

npm install -g @automagik/genie

Bun

bun install -g @automagik/genie

From source

git clone https://github.com/automagik-dev/genie.git
cd genie
bun install
bun run build
bun link

Post-install setup

After installing, run the setup wizard:

genie setup

Session management

tmux session naming and window layout, so every agent lands in a predictable pane.

Terminal preferences

Default shell, timeouts, and read-line counts tuned to your environment.

Shell integration

Shell aliases and tmux keybindings to keep the hot-path commands a keystroke away.

Codex integration

Optional — wire up OpenAI Codex alongside Claude Code for mixed-provider teams.

Verify your install

Run the diagnostic tool to confirm the CLI, prerequisites, and local config are wired up:

genie doctor

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:

claude plugin list

You should see:

Installed plugins:

  ❯ genie@automagik
    Version: 5.x.x
    Scope: user
    Status: ✔ enabled

If it’s missing, register it manually:

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
`GENIE_HOME`	`~/.genie`	Relocates all global state
`GENIE_AGENT_NAME`	—	Agent identity for hook dispatch
`GENIE_TEAM`	—	Default team when `--team` omitted
`GENIE_IDLE_TIMEOUT_MS`	—	Auto-suspend idle agents

Updating

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:

claude plugin marketplace update automagik
claude plugin update genie@automagik

Then restart your Claude Code session.

Uninstalling

genie uninstall

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

Configure your setup

Tune session layout, shortcuts, shell integration, and provider adapters.

Learn the CLI

Tour the genie command surface — agents, spawning, events, and more.

Quickstart

Five-minute smoke test from install to first pull request.

Full onboarding walkthrough

The 15-minute tour: install → smoke test → wizard → first wish → first PR → first monitor.

Security & Trust

How Genie is signed, distributed, and verified — the trust contract, the verification stack, and the path away from npm.

Getting Started

Core Concepts

The Genie Loop

Power Skills

CLI Reference

Configuration

Security & Trust

Architecture

Observability

Hacks & Tips

Contributing

Prerequisites

Install Genie

Homebrew (macOS / Linuxbrew)

One-line bootstrap

npm

Bun

From source

Post-install setup

Session management

Terminal preferences

Shell integration

Codex integration

Verify your install

Verify the plugin is registered

Environment variables

Updating

Uninstalling

What’s next

Configure your setup

Learn the CLI

Quickstart

Full onboarding walkthrough

Security & Trust

​Prerequisites

​Install Genie

​Homebrew (macOS / Linuxbrew)

​One-line bootstrap

​npm

​Bun

​From source

​Post-install setup

Session management

Terminal preferences

Shell integration

Codex integration

​Verify your install

​Verify the plugin is registered

​Environment variables

​Updating

​Uninstalling

​What’s next

Configure your setup

Learn the CLI

Quickstart

Full onboarding walkthrough

Security & Trust

Prerequisites

Install Genie

Homebrew (macOS / Linuxbrew)

One-line bootstrap

npm

Bun

From source

Post-install setup

Verify your install

Verify the plugin is registered

Environment variables

Updating

Uninstalling

What’s next