Skip to main content
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

ToolRequiredPurpose
Node.js 18+ or BunYesRuntime for the CLI
Claude CodeYesAI agent backend (or swap for Codex, Open Claw, or a BYOA adapter)
tmuxYesAgent process management
GitYesVersion control and worktrees
GitHub CLI (gh)RecommendedPR 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
1

Install the package

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

Link the Claude Code plugin

Symlinks the plugin to ~/.claude/plugins/genie so Claude Code can discover every slash command.
3

Configure git hooks

Wires up hooks for agent identity injection and event capture.
4

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 every component is wired up: 
genie doctor

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.

​
Environment variables

VariableDefaultDescription
GENIE_HOME~/.genieRelocates 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

​
Uninstalling

genie uninstall
This removes the CLI, plugin symlink, and git hooks. Your project’s .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.