Configuration

Huskies is configured via three TOML files in your .huskies/ directory. All files are created by huskies init with sensible defaults.

project.toml

Project-wide settings. Lives at .huskies/project.toml.

Component setup

The [[component]] sections define how to build and verify each part of your project. The server runs setup commands before accepting a story's QA and teardown commands after merging.

[[component]]
name = "frontend"
path = "frontend"
setup = ["npm ci", "npm run build"]
teardown = []

[[component]]
name = "server"
path = "."
setup = ["mkdir -p frontend/dist", "cargo check"]
teardown = []

Story front matter overrides

Individual stories can override project defaults using YAML front matter:

---
name: "My Complex Story"
qa: agent        # override default_qa
agent: opus      # use the opus coder agent
---

agents.toml

Agent definitions. Lives at .huskies/agents.toml. Each [[agent]] block defines one agent slot.

Template variables

The following variables are interpolated into prompt and system_prompt at agent start time:

Example: adding an opus coder

[[agent]]
name = "coder-opus"
stage = "coder"
role = "Senior engineer for complex tasks."
model = "opus"
max_turns = 80
max_budget_usd = 20.00
prompt = "You are working on story {{story_id}} ..."
system_prompt = "You are a senior full-stack engineer ..."

To use this agent for a specific story, add agent: opus to the story's front matter, or run start <number> opus in chat.

Project-local agent prompt (.huskies/AGENT.md)

Place a file at .huskies/AGENT.md in your project root to append project-specific guidance to every agent's initial prompt at spawn time.

How it works

• Huskies reads .huskies/AGENT.md each time an agent is spawned — no caching, no restart required.
• The file content is appended after the baked-in agent prompt, so project guidance refines core instructions without overriding them.
• Applies to all agent roles: coder, QA, mergemaster, and supervisor.
• If the file is missing or empty, agents spawn normally — no warnings, no errors.
• When the file exists and is non-empty, a single INFO log line is emitted showing the file path and byte count.

Ordering

1. Baked-in agent prompt (from agents.toml or project.toml)
2. Project-local content from .huskies/AGENT.md
3. Resume context (only on agent restart after a gate failure)

Example

# .huskies/AGENT.md

## Documentation
Docs live in `website/docs/*.html`, not Markdown files.
Edit the relevant .html file when a story asks for documentation.

## Quality gates
Run `cargo clippy -- -D warnings` before committing. Zero warnings allowed.

Edit the file at any time — the next agent spawn picks up the latest content automatically.

bot.toml

Chat transport configuration. Lives at .huskies/bot.toml. This file is gitignored as it contains credentials. Copy the appropriate example file to get started:

cp .huskies/bot.toml.matrix.example .huskies/bot.toml

Only one transport can be active at a time. See the Chat transports guide for setup instructions for each platform.

Common fields