Swarmit

Persistent task coordination for AI coding agents.

AI coding agents try to maintain context through markdown plans and limited subagent memory — but those are fragile, siloed, and invisible to other agents. Swarmit replaces that with a shared, persistent task board every agent reads and writes through the same CLI. One source of truth across sessions and agents.

Break a project into epics and tasks, set up dependency graphs, then let multiple agents pick up work in parallel — each one aware of what the others are doing. Come back tomorrow and the plan is still there, with full history of who did what.

Why Swarmit

Long-term planning. Agents create epics with tasks, dependencies, and priorities that survive across sessions. Pick up where you left off — or let a fresh agent continue the work.

Multi-agent collaboration. Multiple agents claim tasks before starting, leave progress comments, and mark work done — all through the same CLI. No duplicate work, no stepping on each other.

Full visibility. A live terminal dashboard shows what's happening right now: who's working on what, what's blocked, what's done. Every mutation is recorded in an append-only event log with complete history.

Agent-native. JSON output on every command. Pipe-friendly. Comes with a Claude Code skill that teaches agents the workflow automatically.

  Agent A          Agent B          Agent C
    │                 │                │
    │  swarmit CLI    │  swarmit CLI   │  swarmit CLI
    └────────┬────────┘                │
             ▼                         │
       shared task state  ◄────────────┘
             │
             ▼
         swarmit TUI
    (live-refreshing dashboard
     you watch while agents run)

Install

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 .

Requires Rust 1.80+.

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

The plugin teaches Claude Code agents to use swarmit instead of the built-in todo tools. Once installed, agents automatically:

• Check for existing tasks before creating new ones
• Create epics with dependency graphs for multi-step work
• Claim tasks before starting (prevents duplicate work)
• Leave progress comments visible in the TUI in real time
• Mark tasks done when finished — or blocked with an explanation
• Dispatch parallel subagents in waves based on the dependency graph

Install:

/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 groups

Common examples

# 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

Markdown materialization

Swarmit can export its state as markdown files — one file per epic and task. This is a downstream, one-way export: swarmit writes markdown from its event log, never the reverse. Editing the markdown files has no effect on swarmit state.

By default, auto-materialization is off. Enable it in your project config:

swarmit init --name "My Project" --auto-materialize --agent me
# or update an existing project:
swarmit project update --auto-materialize true --agent me

You can also run swarmit sync at any time to generate (or regenerate) all markdown:

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

TUI

Run swarmit with no arguments in a TTY to open the live dashboard:

swarmit

The TUI watches for file changes and refreshes automatically as agents update state. Two-pane layout with collapsible epic groups, three detail tabs (description, comments, insights), and inline editing via $EDITOR.

Catppuccin theme with automatic light/dark detection:

SWARMIT_THEME=latte     swarmit   # light
SWARMIT_THEME=mocha     swarmit   # dark
SWARMIT_THEME=frappe    swarmit
SWARMIT_THEME=macchiato swarmit

Key bindings

What's in the box

• Epics and tasks with priority, assignee, and status
• Typed relationships between items (blocks, blocked_by, parent, child, relates_to, duplicates)
• Comments and code insights on any task
• Full history with swarmit log
• JSON output on every command — pipe-friendly for agents and scripts
• TUI with sort, filter, live refresh, inline editing, and resizable split panes
• Catppuccin theme with auto dark/light detection
• Claude Code skill file that wires everything together
• CI/CD with GitHub Actions — pre-built binaries for Linux and macOS

Project layout

src/
  main.rs         # Binary entry point (mode detection)
  lib.rs          # Public API, re-exports
  models/         # Domain types: Task, Epic, ItemId, Status, etc.
  events/         # Event sourcing: Operation, append, locking
  state/          # Materializer, snapshot, index, markdown sync
  cli/            # CLI commands (clap)
  tui/            # Terminal UI (ratatui + crossterm)
plugin/
  skills/
    swarmit/      # Claude Code skill files
.swarmit/
  operations.log  # Append-only event log (source of truth)
  project.toml    # Project config
  state/          # Optional materialized markdown (downstream output)

Development

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

Tests use tempfile for isolated directories — no global state.

License

MIT