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

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.