swarm

Swarm is a local-first control plane designed for developers running multiple AI coding agents simultaneously. It runs as a single daemon on your machine, reading the hooks, transcripts, and session logs that agents like Claude Code, Codex CLI, Gemini CLI, Grok, Aider, and opencode already produce — requiring zero instrumentation changes to your repositories. All state lives in ~/.swarm/ and the dashboard binds to 127.0.0.1, so nothing leaves your machine, no account is needed, and it works offline. The core value is observability and coordination. The Fleet view shows every session across every project in real time: which agent is running, on which branch, what it is doing right now, model, output tokens, context size, cost, and age. A session that starts repeating a failing command gets a Stuck badge and a desktop notification. The Session view streams an agent's reasoning and tool calls live, with per-turn cost, cache hit rate, thinking share, and a tool histogram. Replay steps through tool calls one at a time with full input and output, and an ended session can be resumed from where it died. The Board serves as a coordination ledger for a project. It tracks tasks from a markdown backlog, GitHub Issues, or Linear, with pass/fail gates and Run/Dispatch actions. Task claims are held in isolated git worktrees, each with branch, drift, dirty/unpushed state, and the session inside it. Runtime resources — ports, dev servers, databases — are held as named singletons. Incidents record every command the rules asked about or denied, with a Codify action that turns one into a .swarm.toml rule and a CLAUDE.md lesson. Rules are guardrails on the Bash commands a Claude Code session runs: shared_tree, destructive_git, pattern_kill, protected_ports, no_foreign_worktree, and claim_required_to_write. Each is set to ask, deny, or off per repo in .swarm.toml. A deny is returned to Claude Code as a real permission denial. Ports held as resources are protected automatically. These are guardrails against accidents, not a sandbox. Swarm can also spawn agents: swarm run --task X claims a task and spawns claude -p in its worktree, steerable by stdin and stoppable by pid. swarm dispatch --ready hands every claimable task to its own run, N at a time. Run profiles (full, no-edits, read-only) narrow what a spawned agent may do. Gates declared in .swarm.toml are executed in the task's worktree — exit 0 passes, the output tail is the evidence. Every session that pauses leaves an auto-handoff with files edited, last verification command, and last request; the next session in that worktree gets it injected at start. An agent that hits a decision only a human can make calls swarm_ask; the question shows on the session page with options as buttons, Fleet shows an Asking badge, a desktop notification fires, and the answer reaches the agent on its own. Declarative workflows in .swarm.toml advance automatically: run steps spawn an agent, gate steps must pass to continue, and pr pushes the branch and opens the pull request. Agent-to-agent messaging via swarm_send reaches another session by id, whoever holds a task, or the lead session. The PRs view provides one merge queue across GitHub and GitLab, read through your already-authenticated gh or glab CLI. No tokens are stored. The Timeline shows session lanes per project, coloured by agent, over 3–72 hours. Spend and Stats break down cost by project, model, agent, and task, with a context-budget table ranking sessions by how much context they re-read. Per-repo budgets enforce daily or weekly ceilings that warn, ask, or stop. Outcomes track whether work survived: sessions join to a branch, the branch to its PR, the PR to merged or reverted, scored per model and per agent with merge rate, median time to merge, and dollars per merge. A live bipartite graph shows running sessions against the files they touch; a file two sessions hold with at least one writer turns red — a merge conflict you can still prevent. Swarm is available as a CLI (bunx @ra3orblade/swarm setup), a desktop app (macOS signed and notarized, Windows, Linux .deb/.rpm), and an MCP server that lets agents coordinate themselves. The team daemon (swarm-teamd) is a self-hosted second service for multi-machine setups, forwarding audit events, spend rollups, and claims — never transcript text unless a machine opts in. The team package is source-available under FSL-1.1-ALv2, converting to Apache-2.0 two years after each release; everything else is Apache-2.0.