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

# Installation

> Install Genie CLI, configure prerequisites, and verify your setup.

<Note>
  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.
</Note>

## Prerequisites

| Tool                                                          | Required    | Purpose                                                                                    |
| ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| [Node.js](https://nodejs.org/) 18+ or [Bun](https://bun.sh/)  | Yes         | Runtime for the CLI                                                                        |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Yes         | AI agent backend (or swap for [Codex, Open Claw, or a BYOA adapter](/genie/concepts/byoa)) |
| [tmux](https://github.com/tmux/tmux)                          | Yes         | Agent process management                                                                   |
| [Git](https://git-scm.com/)                                   | Yes         | Version control and worktrees                                                              |
| [GitHub CLI](https://cli.github.com/) (`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)

<Warning>
  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](https://github.com/automagik-dev/genie).
</Warning>

```bash theme={"dark"}
# 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):

```bash theme={"dark"}
curl -fsSL https://raw.githubusercontent.com/automagik-dev/genie/main/install.sh | bash
```

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

  <Step title="Configure git hooks">
    Wires up hooks for agent identity injection and event capture.
  </Step>

  <Step title="Run genie doctor">
    Verifies prerequisites and config, then prints a green checklist (or tells you what's missing).
  </Step>
</Steps>

### npm

```bash theme={"dark"}
npm install -g @automagik/genie
```

### Bun

```bash theme={"dark"}
bun install -g @automagik/genie
```

### From source

```bash theme={"dark"}
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:

```bash theme={"dark"}
genie setup
```

<CardGroup cols={2}>
  <Card title="Session management" icon="layer-group">
    tmux session naming and window layout, so every agent lands in a predictable pane.
  </Card>

  <Card title="Terminal preferences" icon="terminal">
    Default shell, timeouts, and read-line counts tuned to your environment.
  </Card>

  <Card title="Shell integration" icon="keyboard">
    Shell aliases and tmux keybindings to keep the hot-path commands a keystroke away.
  </Card>

  <Card title="Codex integration" icon="plug">
    Optional — wire up OpenAI Codex alongside Claude Code for mixed-provider teams.
  </Card>
</CardGroup>

## Verify your install

Run the diagnostic tool to confirm every component is wired up:

```bash theme={"dark"}
genie doctor
```

```text theme={"dark"}
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

| 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

```bash theme={"dark"}
genie update          # Stable channel
genie update --next   # Development builds
```

## Uninstalling

```bash theme={"dark"}
genie uninstall
```

This removes the CLI, plugin symlink, and git hooks. Your project's `.genie/` state directory is preserved.

## What's next

<CardGroup cols={2}>
  <Card title="Configure your setup" icon="sliders" href="/genie/config/setup">
    Tune session layout, shortcuts, shell integration, and provider adapters.
  </Card>

  <Card title="Learn the CLI" icon="terminal" href="/genie/cli/agents">
    Tour the `genie` command surface — agents, spawning, events, and more.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/genie/quickstart">
    Five-minute smoke test from install to first pull request.
  </Card>

  <Card title="Full onboarding walkthrough" icon="route" href="/genie/onboarding">
    The 15-minute tour: install → smoke test → wizard → first wish → first PR → first monitor.
  </Card>

  <Card title="Security & Trust" icon="shield-check" href="/genie/security">
    How Genie is signed, distributed, and verified — the trust contract, the verification stack, and the path away from npm.
  </Card>
</CardGroup>