Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt

Use this file to discover all available pages before exploring further.

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.