Autonomous agent swarm CLI written in Go. Give it a goal and it breaks the work into a DAG of parallel tasks, each executed by an independent Claude subprocess. The filesystem is the database.
- Go 1.22+
ANTHROPIC_API_KEYenvironment variable set
go build -o swarm .
./swarm run "your goal here"Or directly:
go run . run "your goal here"swarm <command> [options]
| Command | Description |
|---|---|
run [flags] "goal" |
Run an autonomous agent swarm |
workflow <cmd> |
Run multi-phase workflows from .swarm.yaml files |
learn [goal] |
Show learning insights from past runs |
list |
List all runs with metadata |
status <run-id> |
Show the status of a run |
resume <run-id> |
Resume an interrupted run |
cancel <run-id> |
Cancel a running swarm |
replay <run-id> |
Replay the timeline of a run |
clean [flags] |
Delete old run directories |
| Flag | Description |
|---|---|
--budget <tokens> |
Maximum token budget (0 = unlimited) |
--tag <name> |
Human-readable tag for the run directory |
--tui |
Enable live TUI dashboard (bubbletea) |
--dry-run |
Plan only — do not execute agents |
| Flag | Description |
|---|---|
--older-than <dur> |
Delete runs older than duration (default: 7d, supports Nd or Go durations) |
--dry-run |
Show what would be deleted without deleting |
swarm "your goal here" # equivalent to: swarm run "your goal here"# Plan without executing
swarm run --dry-run "build a CLI tool in Go"
# Run with a budget, tag, and live dashboard
swarm run --budget 50000 --tag coffee --tui "build a landing page for a coffee shop"
# Check on a run
swarm status coffee
# Resume an interrupted run
swarm resume coffee
# Replay what happened
swarm replay coffee
# View learning insights
swarm learn
swarm learn "build a landing page"
# Run a multi-phase workflow
swarm workflow run dev.swarm.yaml --var topic="caching"
# Clean up old runs
swarm clean --older-than 7dTwo-phase orchestration with dynamic replanning:
PHASE 1: PLANNING
Cross-run learning scans past runs → writes learning_context.md
Claude planner agent → plan.json (strict JSON, 1 retry)
Go validates DAG (cycles, dangling deps)
--dry-run exits here
PHASE 2: EXECUTION (Go-owned)
Go loads DAG → spawns ready tasks in parallel → monitors → repeats
Budget enforcement, signal handling, error recovery
All child processes tracked via process groups
REPLAN (triggered on stall or agent request)
Go writes replan_context.md (completed/failed task summary)
Claude replanner → updated plan.json (preserves completed work)
Go merges new plan into DAG, spawns newly ready tasks
Max 3 replans per run to prevent infinite loops
- The planner runs once to produce a
plan.json. Go owns execution from there. - Each task is a separate Claude subprocess spawned via
os/exec. - If execution stalls or an agent sets
replan_requested: true, the replanner is invoked. - State files are plaintext
key: value— easy for agents to write without a schema library. - Process groups (
setpgid) enable graceful shutdown via SIGTERM propagation.
{
"tasks": [
{
"id": "t1-short-name",
"name": "Human-readable task name",
"prompt": "Detailed instructions for the agent...",
"depends_on": []
}
]
}Enable with --tui for a live terminal dashboard powered by bubbletea:
swarm run --tui "build a landing page"The dashboard shows:
- DAG panel — task status with dependency visualization
- Agent status — live table of agent IDs, statuses, current tasks, and token counts
- Cost meter — progress bar with token usage and USD cost
- Log tailing — real-time output from each agent's log file
Keybindings: tab to cycle agent logs, 1-9 to select, up/down to scroll, q to cancel.
Chain multiple swarm runs into reusable multi-phase workflows with .swarm.yaml files:
name: research-implement-test
description: Standard development workflow
phases:
- name: research
goal: "Research {{.topic}} and write findings to artifacts/research.md"
budget: 30000
- name: implement
goal: "Based on artifacts/research.md, implement {{.topic}}"
budget: 50000
depends_on: [research]
- name: test
goal: "Write tests for the implementation in artifacts/"
budget: 30000
depends_on: [implement]
variables:
topic: "" # Required, no default# Run a workflow with variable substitution
swarm workflow run dev.swarm.yaml --var topic="caching layer"
# Validate without running
swarm workflow validate dev.swarm.yaml
# List available workflows
swarm workflow listEach phase executes as a full swarm run. Artifacts from completed phases are automatically copied to a shared workflow directory and available to subsequent phases.
Swarm learns from past runs to improve future planning. Before each planning phase, it scans completed runs for similar goals (using keyword similarity) and writes a learning_context.md file with:
- Average task count and token usage for similar goals
- Success rates and common task patterns
- Duration estimates
The planner reads this context as guidance (not gospel) to make better decomposition decisions.
# View overall statistics
swarm learn
# Get insights for a specific goal
swarm learn "build a landing page for a coffee shop"Output example:
Swarm Learning - Insights for: "build a landing page for a coffee shop"
========================================
Similar runs found: 2
Avg task count: 3
Avg tokens: 40000
Avg duration: 5m0s
Success rate: 100%
Recommendations:
- Similar goals typically use 3 tasks.
- Expected token usage: ~40000 tokens.
- Common task patterns: frontend, research, review.
main.go CLI entrypoint and subcommand routing
internal/
cmd/ Subcommand handlers (run, list, status, resume, cancel, replay, clean, workflow, learn)
manager/manager.go Two-phase orchestration with dynamic replanning
dag/dag.go Task dependency graph with cycle detection and replan merging
prompts/prompts.go Agent prompts (planner, replanner, subagent)
process/process.go Child process lifecycle and signal handling
cost/cost.go Token tracking and budget enforcement
cost/parse.go Real cost tracking via Claude CLI output parsing
events/events.go Structured event logging
display/display.go Colored terminal output
state/state.go State file parsing (including replan_requested flag)
tasks/tasks.go Human task queue parsing
messages/messages.go Agent-to-agent filesystem message bus
tui/ Bubbletea TUI dashboard (DAG panel, agent status, cost meter, log tailing)
workflow/workflow.go Workflow config parsing, validation, variable resolution
learning/learning.go Cross-run learning (scan, similarity, insights, planner context)
runs/<tag>-<timestamp>/
├── goal.md # The swarm's objective
├── plan.json # Task DAG produced by planner
├── learning_context.md # Cross-run learning insights for planner
├── human_tasks.md # Append-only human task queue
├── events.log # Structured event timeline
├── run.log # Run metadata
├── swarm.pid # PID file (removed on clean exit)
├── final_report.md # Completion or interruption report
├── costs.json # Token usage summary
├── replan_context.md # Context for replanning (if triggered)
├── state/ # Per-agent state files (key: value)
├── summaries/ # Per-agent completion summaries
├── artifacts/ # Agent output files
├── logs/ # Per-agent stdout/stderr capture
└── messages/ # Agent-to-agent messages
go test ./...MIT