Swarmit

Swarmit demo

Persistent task coordination for AI coding agents. Break projects into epics and tasks with dependency graphs, let multiple agents claim and complete work in parallel, and watch progress in a live terminal dashboard. State persists across sessions in a single SQLite database.

Install

From crates.io (recommended)

cargo install swarmit

Requires Rust 1.80+. Published at crates.io/crates/swarmit.

Pre-built binaries

Download the latest release from GitHub Releases:

Linux x86_64: swarmit-linux-x86_64.tar.gz
macOS ARM64: swarmit-macos-arm64.tar.gz

# Example: macOS ARM64
tar xzf swarmit-macos-arm64.tar.gz
mv swarmit /usr/local/bin/

From source

git clone https://github.com/zeapo/swarmit
cd swarmit
cargo install --path .

Quick start

# Initialize a project
swarmit init --name "My Project" --agent me

# Plan the work
swarmit epic create --title "Authentication" --agent me
swarmit task create --title "Implement login flow" --epic EPIC-001 --agent me
swarmit task create --title "Add session middleware" --epic EPIC-001 --agent me
swarmit link add --from TASK-001 --to TASK-002 --type blocks --agent me

# Agents claim before starting, comment as they go, done when finished
swarmit task claim TASK-002 --agent claude-1
swarmit comment add TASK-002 --body "OAuth flow implemented, tests passing" --agent claude-1
swarmit task done  TASK-002 --agent claude-1

All mutation commands require --agent <ID> (or SWARMIT_AGENT env var). Output is pretty-printed on a TTY and JSON when piped — useful for scripting and agent-to-agent communication.

Claude Code plugin

Teaches Claude Code agents to use swarmit instead of the built-in todo tools.

/plugin marketplace add zeapo/swarmit
/plugin install swarmit

Or copy the skill file manually into your .claude/skills/ directory — see plugin/skills/swarmit/.

CLI

Command	Description
`swarmit init`	Initialize a project in the current directory
`swarmit epic`	Create, list, show, update, delete epics
`swarmit task`	Create, list, show, update, claim, done, delete tasks
`swarmit link`	Add / remove / list typed relationships
`swarmit comment`	Add comments to any task
`swarmit insight`	Attach code insights to tasks
`swarmit log`	Inspect the history of all changes
`swarmit compact`	Prune and snapshot history
`swarmit project`	Show or update project metadata
`swarmit sync`	Regenerate markdown files from state

# List all open tasks
swarmit task list --status todo

# Tasks for a specific epic, as JSON
swarmit task list --epic EPIC-001 --status todo --json

# Show task detail with relationships and comments
swarmit task show TASK-007

# Link tasks
swarmit link add --from TASK-001 --to TASK-002 --type blocks --agent me

# Add a progress comment
swarmit comment add TASK-001 --body "OAuth flow implemented, tests passing" --agent me

# Review recent activity
swarmit log --tail 20

Full reference: plugin/skills/swarmit/cli-reference.md

TUI

Run swarmit with no arguments to open the live dashboard. It polls for changes and refreshes automatically as agents update state.

Catppuccin theme with automatic light/dark detection (SWARMIT_THEME=latte|mocha|frappe|macchiato).

Key bindings

Key	Action
`j`/`k` or `↑`/`↓`	Navigate list / scroll detail
`Enter`	Open detail pane
`Space`	Collapse / expand epic group
`Tab`	Cycle detail tabs
`h`/`l` or `←`/`→`	Cycle detail tabs
`Shift+H/J/K/L`	Switch pane focus
`n`	New task
`e`	Edit description in `$EDITOR`
`a`	Add comment in `$EDITOR`
`S`	Change task status
`E`	Change task epic
`f`	Filter
`s`	Sort
`r`	Refresh
`\|`	Toggle split direction
`=` / `-`	Resize detail pane
`?`	Help
`q` / `Esc`	Quit / back

Markdown export

One-way export of state as markdown files (one per epic and task). Editing the files has no effect on swarmit state.

# Enable auto-export on init
swarmit init --name "My Project" --auto-materialize --agent me

# Or toggle on an existing project
swarmit project update --auto-materialize true --agent me

# Manual one-off export
swarmit sync                        # writes to .swarmit/state/ (default)
swarmit sync --path ./docs/tasks    # writes to a custom directory

Development

cargo build          # Build
cargo test           # Run all tests
cargo run -- --help  # CLI help

Tests use tempfile for isolated directories — no global state.

License

Apache 2.0

swarmit 1.2.0