Swarm Swarm

Getting started

Swarm is a local-first control plane for AI-agent development. One background daemon watches every Claude Code session on your machine, keeps a ledger of task claims, worktrees and runtime resources, enforces a few coordination rules as real permission decisions, and streams all of it to a dashboard at http://127.0.0.1:7777.

Nothing is added to your repositories. State lives in ~/.swarm/.

Requirements

  • Bun 1.3 or newer
  • Claude Code — claude on your PATH
  • git
  • Optional: gh and/or glab, authenticated — only needed for the PRs view

Swarm also picks up OpenAI Codex CLI, Grok CLI, Gemini CLI, Aider and opencode sessions from their own session logs and databases, with no extra setup, but Claude Code is the agent it integrates with through hooks and MCP (the MCP server is also registered for Codex and Gemini CLI when they are installed).

Install

Run setup once. You can do it without installing anything:

bunx @ra3orblade/swarm setup

Or install the CLI globally so swarm is always on your PATH:

bun add -g @ra3orblade/swarm
swarm setup

Prefer a native window with a tray icon and auto-updates? Use the desktop app instead — it runs the same daemon.

What setup does

swarm setup does four things and prints a line for each:

  1. Starts the daemon (swarmd) in the background on port 7777. If that port is taken it picks a free one and records the real URL in ~/.swarm/daemon.json, so every other command still finds it.
  2. Installs hooks into ~/.claude/settings.json for eleven Claude Code events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop, SessionEnd, Notification, PreCompact, PermissionRequest). Each hook is a small command that posts the event to the daemon, with a 5-second timeout — except Stop and PermissionRequest, which may wait on the gates or on you (see the repair loop and the permission card). Your existing hooks are left in place.
  3. Registers an MCP server named swarm in the same file, so agents can claim tasks and resources themselves. See MCP.
  4. Opens the dashboard in your browser.

Hooks are installed at the Claude Code user level, so every session on the machine reports in — any folder, any repo. Sessions that were already running need a restart before they appear.

A status line, optionally

swarm install --statusline

adds one thing more: Claude Code's statusLine becomes swarm statusline, and the footer of every session shows the model, context used, session cost and (for Pro / Max plans) the 5-hour and 7-day windows, then a bar, then what only Swarm knows — the task whose worktree you are in and its lease, the budget when it is not fine, open incidents, and whether a question of yours is waiting for an answer:

Opus · ctx 42% · $1.23 · 5h 24% · 7d 41% │ M12.2 41m · 2 incidents · waiting on you

It is opt-in because a custom status line replaces Claude Code's footer hints. If you already have a status line it is left alone (doctor tells you), and swarm uninstall removes exactly ours. Like the hooks it has a 400 ms budget, falls back to the left half when the daemon is down, and never starts it.

First look

Start claude in any folder. Within a few seconds it shows up in the Fleet view with its project, model, current tool call, token counts and cost. Click a row to open the session and watch its reasoning and tool calls stream live.

The project sidebar fills itself from the sessions it sees. Projects you start Claude in are listed under Unpinned; pin the ones you care about, or add a folder explicitly:

swarm add ~/code/my-app            # register (pin) a project
swarm add ~/code/my-app --name app # with a display name
swarm ls                           # ● pinned, ○ seen

The dashboard guide walks through every view.

Check your setup

swarm doctor

Doctor checks for bun, the claude CLI, a running daemon, installed hooks and the MCP registration, and prints the fix next to anything missing:

✓ bun (/Users/you/.bun/bin/bun)
✓ claude CLI on PATH
✓ daemon (pid 41234, http://127.0.0.1:7777)
✓ hooks installed
✓ MCP server registered

settings: /Users/you/.claude/settings.json
daemon cmd: /Users/you/.bun/bin/swarmd
url: http://127.0.0.1:7777

It exits non-zero when the daemon is not running.

Stop, start, restart

swarm stop
swarm start
swarm restart

You rarely need these: any CLI command (and the MCP server) starts the daemon automatically if it is not running. The hook never does — it must stay fast — so with the daemon stopped, Claude Code keeps working and Swarm simply records nothing until the daemon is back.

Uninstall

swarm uninstall      # remove Swarm's hooks and MCP entry from ~/.claude/settings.json
swarm stop           # stop the daemon

Then remove the package (bun remove -g @ra3orblade/swarm) and, if you want a clean slate, delete ~/.swarm/ — that is the only place Swarm writes. Your repositories are untouched, with one caveat: worktrees created by swarm claim live under ~/.swarm/worktrees/ and are registered with their repo's git; release them first or run git worktree prune in the repo. See Privacy and FAQ.

Next

Source: docs/guide/01-getting-started.md · v0.16.0.