Development

Development setup, build process, and contribution workflow for swarm.

Prerequisites

Clone and Build

git clone <repo-url> swarm
cd swarm
cargo build

The workspace has a single member crate at swarm/.

Build with WASM Support

To enable the WASM sandbox feature:

cargo build --features wasm-sandbox

This requires wasmtime v41 and adds significant compile time. Only enable it if you're working on WASM tool functionality.

Release Build

cargo build --release

Project Structure

swarm/
├── swarm/                    # Main crate
│   ├── src/
│   │   ├── lib.rs            # Module declarations (22+ pub modules)
│   │   ├── main.rs           # Entry point
│   │   ├── cli.rs            # CLI argument parsing (clap)
│   │   ├── config.rs         # Configuration loading and validation
│   │   ├── orchestrator.rs   # Session lifecycle management
│   │   ├── session.rs        # Session info and lockfile
│   │   ├── router.rs         # Message routing and urgent polling
│   │   ├── mailbox.rs        # SQLite messaging
│   │   ├── worktree.rs       # Git worktree operations
│   │   ├── prompt.rs         # 14-section prompt pipeline
│   │   ├── errors.rs         # 6 error enums (thiserror)
│   │   ├── agent/
│   │   │   ├── state.rs      # Agent state machine (8 states)
│   │   │   ├── runner.rs     # Agent execution loop
│   │   │   └── registry.rs   # Agent registry
│   │   ├── tools/
│   │   │   ├── mod.rs        # Tool trait, ToolResult, ExecutionMode
│   │   │   ├── registry.rs   # ToolRegistry
│   │   │   ├── context.rs    # ToolContext
│   │   │   ├── bash.rs       # BashTool
│   │   │   ├── read.rs       # ReadTool
│   │   │   ├── write.rs      # WriteTool
│   │   │   ├── edit.rs       # EditTool
│   │   │   ├── glob.rs       # GlobTool
│   │   │   ├── grep.rs       # GrepTool
│   │   │   ├── web_fetch.rs  # WebFetchTool
│   │   │   ├── web_search.rs # WebSearchTool
│   │   │   ├── mailbox.rs    # MailboxTool
│   │   │   ├── task.rs       # TaskTool
│   │   │   ├── ask_user.rs   # AskUserTool
│   │   │   ├── skill.rs      # SkillTool
│   │   │   ├── notebook_edit.rs # NotebookEditTool
│   │   │   └── wasm/         # WASM sandbox (feature-gated)
│   │   ├── skills/           # Skill discovery and resolution
│   │   ├── permissions/      # Permission evaluation
│   │   ├── mcp/              # MCP server integration
│   │   ├── hooks/            # Lifecycle hooks
│   │   └── tui/              # Terminal UI (ratatui)
│   └── Cargo.toml
├── specs/                    # Specification documents
├── docs/                     # mdBook documentation
├── wit/                      # WASM Interface Types
├── Cargo.toml                # Workspace root
└── CLAUDE.md                 # Agent instructions

Key Dependencies

Running Tests

cargo test

Run tests for a specific module:

cargo test --lib tools::bash

Run with logging:

RUST_LOG=debug cargo test -- --nocapture

Logging

Swarm uses the tracing crate with tracing-subscriber. Control verbosity via RUST_LOG:

# Default
RUST_LOG=info cargo run -- start

# Debug output
RUST_LOG=debug cargo run -- start

# Per-module filtering
RUST_LOG=swarm=debug,rusqlite=warn cargo run -- start

# Quiet
RUST_LOG=warn cargo run -- start

Error Handling Conventions

Swarm follows ADR-009:

• Library code: Use thiserror enums for precise, typed errors. There are 6 error enums in errors.rs covering config, git, mailbox, agent, workflow, and session errors.
• Binary/orchestrator: Use anyhow for ergonomic error propagation with the ? operator.
• All thiserror types automatically convert to anyhow::Error.

Contribution Workflow

Swarm uses a spec-first workflow. See Spec Workflow for full details.

Quick Summary

1. Pick a task: bd ready
2. Claim it: bd update <id> --status in_progress
3. If the task involves new design, write specs first in specs/
4. Implement the code
5. Write tests
6. Run quality gates: cargo test && cargo clippy
7. Close the task: bd close <id>
8. Commit and push:

git add <files>
git commit -m "feat: description of change"
git pull --rebase
bd sync
git push

Commit Messages

Use conventional commits:

Session Completion

When ending a work session, you must complete the landing sequence:

1. File issues for remaining work (bd create)
2. Run quality gates (cargo test, cargo clippy)
3. Update issue status (bd close, bd update)
4. Push to remote:

   git pull --rebase
   bd sync
   git push
   git status  # Must show "up to date with origin"
   

Work is not complete until git push succeeds.

CI

The project uses GitHub Actions for CI. The docs pipeline is configured in .github/workflows/docs.yml for building and deploying the mdBook site.

Quality gates that should pass before pushing:

• cargo build — Successful compilation
• cargo test — All tests pass
• cargo clippy — No lint warnings

Related

• Spec Workflow — How to write specs and file tasks
• Adding Tools — How to add new tools
• Architecture — System architecture overview