# Quickstart

Get huskies running in your project in a few minutes. This guide covers Docker setup, running from a binary, your first story, and your first agent run.

## Option A: Docker (recommended)

The easiest way to run huskies is with Docker Compose. This requires Docker and a Claude API key.

1. Get the compose file. Download `docker-compose.yml` from the releases page or copy it from the repository's `docker/` directory.
2. Set your API key. Create a `.env` file next to the compose file:

       ANTHROPIC_API_KEY=sk-ant-...

3. Mount your project. Edit the compose file to mount your project directory:

       volumes:
         - /path/to/your/project:/workspace

4. Start the server.

       docker compose up

   Open http://localhost:3000 to see the pipeline board.

## Option B: Binary

Download the pre-built binary for your platform from the releases page and place it somewhere on your `PATH`.

### macOS (Apple Silicon)

    curl -L https://code.crashlabs.io/crashlabs/huskies/releases/download/latest/huskies-aarch64-apple-darwin \
      -o /usr/local/bin/huskies
    chmod +x /usr/local/bin/huskies

### Linux (x86-64)

    curl -L https://code.crashlabs.io/crashlabs/huskies/releases/download/latest/huskies-x86_64-unknown-linux-musl \
      -o /usr/local/bin/huskies
    chmod +x /usr/local/bin/huskies

## Option C: Build from source

Requires Rust (stable), Node.js, and npm.

    git clone https://code.crashlabs.io/crashlabs/huskies
    cd huskies
    cargo build --release
    # Binary is at target/release/huskies

## Initialise your project

From your project directory, run the init command. This creates the `.huskies/` directory with the pipeline structure and configuration files.

    cd /path/to/your/project
    huskies init --port 3000

This creates:

- `.huskies/project.toml` — project-wide settings
- `.huskies/agents.toml` — agent definitions (coder, QA, mergemaster)
- `.huskies/work/` — the 6-stage pipeline directory
- `.mcp.json` — MCP server config for Claude Code integration
- `.huskies/specs/` — placeholder spec files for your project context

Claude Code integration: The `.mcp.json` file automatically registers huskies' MCP tools with Claude Code. Open a Claude Code session in your project and it will discover tools like `create_story`, `start_agent`, and `get_pipeline_status` automatically.

## Start the server

    huskies --port 3000

Open http://localhost:3000 to see the pipeline board, agent status, and chat interface.

## Run the setup wizard

Open a Claude Code session in your project directory (or use the web chat UI), and tell Claude:

    help me set up this project with huskies

Claude will walk you through the setup wizard — generating project context (`specs/00_CONTEXT.md`), tech stack docs (`specs/tech/STACK.md`), and test/release scripts. Review each step and confirm or ask to retry.

## Create your first story

In the chat UI or via a chat transport, type:

    I want to add a health check endpoint to the API

Claude will create a story file in `.huskies/work/1_backlog/` with a user story and acceptance criteria. Review it, then move it to current:

    move <story-number> current

## Start an agent

Once a story is in `2_current/`, start a coding agent:

    start <story-number>

The agent creates an isolated git worktree, implements the feature against the acceptance criteria, runs quality gates (clippy, tests, biome), and exits. The server automatically advances the story to QA if all gates pass.

## Review and merge

Once QA passes, the story moves to `4_merge/`. To merge:

    start <story-number>

The mergemaster agent resolves any conflicts and squash-merges to your main branch. The worktree is cleaned up automatically.

Tip: Use `status` in the chat at any time to see the current pipeline state, active agents, and their progress.