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

# Quickstart

> Five minutes from nothing to your first PR. Bring whatever agent you like — we're not picky.

Five minutes. One PR. Whatever agent you already use.

<Note>
  **Research Preview** — Genie is experimental. Things will break, APIs will change, and we want your feedback. Honest feedback, not polite feedback. [Tell us on Discord](https://discord.gg/automagik).
</Note>

<Steps>
  <Step title="Install Genie">
    Run the bootstrap script (see the full [Installation guide](/genie/installation) for alternatives). It installs the CLI, sets up plugins, and configures git hooks.

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

    Verify the install:

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

    Expected output:

    ```text theme={"dark"}
    ✓ genie CLI found
    ✓ Agent detected
    ✓ tmux available
    ✓ Plugin symlink active
    ✓ Git hooks configured
    ```
  </Step>

  <Step title="Choose Your Agent (or don't — we don't care)">
    Genie orchestrates agents. It is not an agent. Use whatever you like — we have opinions about orchestration, not about your vendor choices.

    | Agent             | Setup                     | Notes                                                  |
    | ----------------- | ------------------------- | ------------------------------------------------------ |
    | **Claude Code**   | Installed by default      | Deepest integration — native plugin, hooks, teams      |
    | **Codex**         | `genie setup --codex`     | OpenAI's agent. Full transcript + team support         |
    | **Open Claw**     | `genie setup --open-claw` | Open-source. Community-maintained adapter              |
    | **Custom (BYOA)** | `genie setup --custom`    | Any CLI agent with stdout/stderr. Seriously, anything. |

    Claude Code works out of the box. For others, run the setup command and Genie configures the adapter.

    <Tip>
      **You're never locked in.** Switch agents mid-project, mix them on the same team, or write your own adapter.
      See the [adapter docs](/genie/architecture/overview) if you're the kind of person who builds their own tools.
    </Tip>
  </Step>

  <Step title="Paste Into Your Agent">
    Open your agent in your project directory and paste:

    ```text theme={"dark"}
    You are now a Genie-powered agent. Run `genie` to initialize,
    then use /wizard for guided onboarding.
    ```

    Genie detects a fresh project and scaffolds everything:

    <Frame>
      <CodeGroup>
        ```bash Scaffold Flow theme={"dark"}
        $ genie
        🔍 Scanning project...

        ⚠ No AGENTS.md found — this looks like a fresh project.

        Scaffolding your agent workspace...
          Creating AGENTS.md...        ✓
          Creating SOUL.md...          ✓
          Creating .genie/wishes/...   ✓
          Creating .genie/state/...    ✓
          Configuring git hooks...     ✓

        ✨ Project scaffolded successfully!

        Your agent workspace is ready:
          AGENTS.md    → agent directory and roles
          SOUL.md      → agent identity and principles
          .genie/      → wishes, state, mailbox, chat

        Next: run /wizard for guided onboarding.
        ```
      </CodeGroup>
    </Frame>
  </Step>

  <Step title="Brainstorm Your First Idea">
    Got something you want to build? Tell the brainstorm skill about it:

    ```text theme={"dark"}
    /brainstorm Add a dark mode toggle to the settings page
    ```

    It'll walk you through the thinking you'd do anyway — but faster:

    <AccordionGroup>
      <Accordion title="Scope" icon="crosshairs">
        What's in, what's out. The brainstorm skill pushes you to name both edges before you write a line of code.
      </Accordion>

      <Accordion title="Constraints" icon="link">
        Dependencies, breaking changes, hidden invariants. If something is load-bearing, it gets called out here instead of surfacing in review.
      </Accordion>

      <Accordion title="Design" icon="compass-drafting">
        Approach and tradeoffs. This is the "why this way" that your future self will thank you for.
      </Accordion>

      <Accordion title="Readiness" icon="circle-check">
        Is this crisp enough to actually build? If not, the brainstorm keeps probing until it is.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Create a Wish">
    When the brainstorm crystallizes, turn it into something agents can execute:

    ```text theme={"dark"}
    /wish
    ```

    This produces a `WISH.md` — the contract between you and your agents:

    * Summary and scope (so nobody wanders off)
    * Acceptance criteria (checkboxes — unambiguous "done")
    * Execution groups (parallelizable work units)
    * Validation commands (proof it works)
  </Step>

  <Step title="Execute and Ship">
    Let the agents do the work:

    ```text theme={"dark"}
    /work
    ```

    When they're done, validate:

    ```text theme={"dark"}
    /review
    ```

    **SHIP** → PR created. **FIX-FIRST** → fix loop runs automatically. You don't babysit either way.
  </Step>
</Steps>

## What just happened?

You typed four slash commands and got a pull request. Your agent did the actual work. Here's what it looked like:

<Frame>
  <CodeGroup>
    ```bash /brainstorm theme={"dark"}
    $ /brainstorm Add a dark mode toggle to the settings page

    🧠 Brainstorming "dark-mode-toggle"...

    Exploring scope...
      ✓ Dark mode CSS variables
      ✓ Toggle component in settings
      ✓ Persistent preference via localStorage

    Identifying constraints...
      ✓ Must avoid FOUC on page load
      ✓ Existing component tests must pass

    Design crystallized → ready for /wish
      Draft: .genie/brainstorms/dark-mode-toggle/DESIGN.md
    ```

    ```bash /wish theme={"dark"}
    $ /wish

    📋 Converting brainstorm to wish...
      Source: .genie/brainstorms/dark-mode-toggle/DESIGN.md

    Writing WISH.md...
      ✓ Summary and scope
      ✓ 4 success criteria
      ✓ 2 execution groups (1 parallel, 1 sequential)

    Wish created: .genie/wishes/dark-mode-toggle/WISH.md
    Status: APPROVED — ready for /work
    ```

    ```bash /work theme={"dark"}
    $ /work

    🔨 Executing wish "dark-mode-toggle"...

    Wave 1 (parallel):
      ✅ Group 1: CSS Variables         engineer  done   14:30
      ✅ Group 2: Toggle Component      engineer  done   14:32

    All groups complete. Running validation...
      ✓ bun test — 42 passed, 0 failed
      ✓ bun run typecheck — no errors

    Ready for /review
    ```

    ```bash /review theme={"dark"}
    $ /review

    🔍 Reviewing wish "dark-mode-toggle"...

    Checking criteria:
      ✅ Toggle renders in settings page
      ✅ CSS variables switch between light/dark
      ✅ Preference persists across sessions
      ✅ No FOUC on page load
      ✅ All existing tests pass

    Verdict: SHIP ✨

    Creating pull request...
      PR #47: "feat: add dark mode toggle to settings"
      Branch: feat/dark-mode-toggle → dev
      URL: https://github.com/myapp/myapp/pull/47
    ```
  </CodeGroup>
</Frame>

| Step     | Skill         | Output                                                                     |
| -------- | ------------- | -------------------------------------------------------------------------- |
| Explore  | `/brainstorm` | Design document                                                            |
| Plan     | `/wish`       | WISH.md with criteria                                                      |
| Build    | `/work`       | Code changes across execution groups (tracked as PG tasks)                 |
| Validate | `/review`     | SHIP or FIX-FIRST verdict                                                  |
| Ship     | PR created    | Ready for you to merge (agents don't push to production — that's your job) |

<Note>
  Under the hood, Genie tracks every task, board, audit event, and session in an embedded PostgreSQL database. Query it with `genie events summary --today` or `genie task list --by-column` for a Kanban view.
</Note>

## What's next

<CardGroup cols={2}>
  <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="The Genie Loop" icon="arrows-rotate" href="/genie/skills/loop-overview">
    Plan → Review → Work → Ship → Monitor — the canonical lifecycle and the skills behind each phase.
  </Card>

  <Card title="Core Concepts" icon="book" href="/genie/concepts/wishes">
    Understand wishes, agents, teams, and skills in depth.
  </Card>

  <Card title="Stuck? Ask on Discord" icon="discord" href="https://discord.gg/automagik">
    Real humans. Real answers. Usually within minutes, not days.
  </Card>
</CardGroup>