huskies/README.md

# Huskies

A story-driven development server that manages work items, spawns coding agents, and runs them through a pipeline from backlog to done. Ships as a single Rust binary with an embedded React frontend.

## Getting started with Claude Code

1. Download the huskies binary (or build from source — see below).

2. From your project directory, scaffold and start the server:

```bash
huskies init --port 3000
```

This creates a `.huskies/` directory with the pipeline structure, `project.toml`, and `.mcp.json`. The `.mcp.json` file lets Claude Code discover huskies' MCP tools automatically.

Huskies also ships an embedded React frontend. Once the server is running, open `http://localhost:3000` to see the pipeline board, agent status, and chat interface.

3. Open a Claude Code session in the same project directory, or visit http://localhost:3000/. 

4. Tell Claude: "help me set up this project with huskies." Claude will walk you through the setup wizard — generating project context, tech stack docs, and test/release scripts. Review each step and confirm or ask to retry.

Once setup is complete, Claude can create stories, start agents, check status, and manage the full pipeline via MCP tools — no commands to memorize.

## Chat transports

Huskies can be controlled via bot commands in **Matrix**, **WhatsApp**, and **Slack**. Configure a transport in `.huskies/bot.toml` — see the example files:

- `.huskies/bot.toml.matrix.example`
- `.huskies/bot.toml.whatsapp-meta.example`
- `.huskies/bot.toml.whatsapp-twilio.example`
- `.huskies/bot.toml.slack.example`

## Prerequisites for building

- Rust (2024 edition)
- Node.js and npm
- Docker (for Linux cross-compilation and container deployment)
- `cross` (`cargo install cross`) optional, for Linux static builds. Only needed if you are building for a different architecture, e.g. if you want to build a Linux binary from a Mac.

You only need these installed if you want to build Huskies yourself. Alternately, you can just download and run the `huskies` binary for your system from https://code.crashlabs.io/crashlabs/huskies/releases

## Building for production

```bash
cargo build --release
```

The release binary embeds the frontend via `rust-embed`. Output: `target/release/huskies`.

For a static Linux binary (musl, zero dynamic deps):

```bash
cross build --release --target x86_64-unknown-linux-musl
```

Docker:

```bash
docker compose -f docker/docker-compose.yml build
```

## Running in development

```bash
# Run tests
script/test

# Run the server
cargo run -- --port 3000

# In another terminal, run the frontend dev server
cd frontend && npm install && npm run dev
```

Configuration lives in `.huskies/project.toml`. See `.huskies/bot.toml.*.example` for transport setup.

## Releasing

Requires a Gitea API token in `.env` (`GITEA_TOKEN=your_token`).

```bash
script/release 0.7.1
```

This bumps version in `Cargo.toml` and `package.json`, builds macOS arm64 and Linux amd64 binaries, tags the repo, and publishes a Gitea release with changelog and binaries attached.

## License

GPL-3.0. See [LICENSE](LICENSE).