agent-swarm

Agent Swarm

Plan and deliver software with a team of coding agents you supervise from your Mac.

Agent Swarm is a local tool with three parts:

• A daemon (swarm) that keeps a board of epics, stories, tasks, bugs and spikes, spawns coding agents in detached tmux sessions, and relays messages and checkpoints between them.
• A web board at http://127.0.0.1:7777 with hierarchy, kanban and dependency-graph views.
• A menu bar app (Swarm.app) showing running agents, requests that need you, usage per agent, and notifications.

Supported agents: Claude Code (default), Codex, Antigravity CLI (agy), Cursor CLI (cursor-agent), Muse and Grok Build (grok). Delivery roles are orchestrator, coder, reviewer, UI reviewer, designer, researcher, debugger and mechanical worker.

How work flows

1. Start a spike. From the menu bar (New orchestrator), the board (New spike) or swarm new. Give it a name, pick feature or debug, and optionally suggest repositories.
2. Confirm repositories. The spike works out which repositories the work needs, suggests any you missed, and asks you to confirm. Agents only create worktrees in confirmed repositories.
3. Research, design and approve. The spike delegates research questions, uses a designer and UI reviewer for new screens, and asks you to approve each spec section. Approvals happen in the menu bar or on the board.
4. Get an epic (or a bug). The plan assigns a workflow to every task and batches related TDD units into packages. You see plan lint and batching warnings before approval. Materialization creates the approved tree, including its roles, verify commands and dependencies.
5. Start delivery. Press Start orchestrator on the epic. The orchestrator creates worktrees and calls swarm_workflow start for each Ready package. One coder executes its units in order; the daemon starts one package review after the units are committed. Story review and root integration follow, then you accept the result.
6. Supervise. Open any agent's terminal from the menu bar or board, pause one agent or everything, and read checkpoints instead of transcripts.

Specs and plans live in ~/.swarm/specs and ~/.swarm/plans, not in your repositories. Commits and PRs are made under your name and signature, with no agent attribution.

Requirements

• macOS 14 or later, logged in to the GUI session
• Homebrew
• Go 1.27+, tmux 3.6+, Node 22 + pnpm 10 (to build the board), Xcode 16+ command line tools (to build the menu bar app)
• Ghostty 1.3+
• Ollama with qwen3-embedding:0.6b (knowledge base search)
• At least one agent CLI, signed in: claude, codex, agy, cursor-agent
• Nothing to install for superpowers: swarm install installs the superpowers plugins for every agent it finds (Cursor must be signed in first)
• graphify 0.9.71 (Graphify-Labs/graphify), installed by swarm install through uv
• Git commit signing enabled (commit.gpgsign=true) in repositories agents work in

brew install go tmux pnpm uv
brew install --cask ghostty ollama
ollama pull qwen3-embedding:0.6b

Install

git clone https://github.com/AlexanderTar/agent-swarm.git
cd agent-swarm
make install        # builds swarm into ~/.swarm/bin and Swarm.app into /Applications
swarm install       # launchd service, tmux config, agent MCP/hooks/skill, first-run checks
swarm doctor        # verify everything
open /Applications/Swarm.app

swarm install does the following:

• writes ~/Library/LaunchAgents/dev.swarm.daemon.plist and starts the daemon on 127.0.0.1:7777
• writes ~/.swarm/tmux.conf (agents run on a private tmux socket, tmux -L swarm)
• for each installed agent, installs the superpowers plugins it supports, and adds the swarm MCP server, the Swarm hooks (inactive outside Swarm sessions) and the Swarm role skills (swarm, swarm-orchestrator, swarm-spike, swarm-workflows, swarm-batching and worker/reviewer skills)
• installs graphify 0.9.71 with uv and gives every agent the graphify skill
• scans your home folder for git repositories (hidden folders, ~/Library, ~/Music, ~/Pictures, ~/Movies, and ~/Downloads are skipped by default; change exclusions in Settings)
• removes hooks and config left by Agent Swarm 1.x
• links swarm into ~/.local/bin

The first time the menu bar app opens a terminal, macOS asks for permission to control Ghostty. Allow it. The app also asks to send notifications.

Code signing and macOS permissions

Local builds are signed with codesign. If ad-hoc signing (-) is used, macOS binds TCC privacy permissions to the binary's cryptographic hash (cdhash), causing permission prompts to re-appear whenever swarm is recompiled.

To keep permissions trusted permanently across rebuilds and redeploys, create a persistent local self-signed code-signing certificate named Swarm Dev:

# 1. Create a certificate configuration
cat << 'EOF' > /tmp/swarm-cert.conf
[ req ]
default_bits        = 2048
distinguished_name  = req_dn
prompt              = no
x509_extensions     = v3_code_sign

[ req_dn ]
CN = Swarm Dev

[ v3_code_sign ]
keyUsage = critical, digitalSignature
extendedKeyUsage = critical, codeSigning
basicConstraints = critical, CA:FALSE
EOF

# 2. Generate private key and certificate
openssl req -new -x509 -days 3650 -config /tmp/swarm-cert.conf -nodes -keyout /tmp/swarm-key.pem -out /tmp/swarm-cert.pem
openssl pkcs12 -export -legacy -inkey /tmp/swarm-key.pem -in /tmp/swarm-cert.pem -out /tmp/swarm-cert.p12 -passout pass:swarmdev -name "Swarm Dev"

# 3. Import and trust in your login keychain
security import /tmp/swarm-cert.p12 -k ~/Library/Keychains/login.keychain-db -P swarmdev -T /usr/bin/codesign
security add-trusted-cert -p codeSign -k ~/Library/Keychains/login.keychain-db /tmp/swarm-cert.pem
rm -f /tmp/swarm-cert.conf /tmp/swarm-key.pem /tmp/swarm-cert.pem /tmp/swarm-cert.p12

The Makefile automatically detects Swarm Dev when present in your keychain and uses it to sign bin/swarm. You can also override the identity via SWARM_SIGN_IDENTITY="<Your Certificate Name>".

Keychain access (per-agent usage numbers)

To show 5h/weekly usage in the menu bar, the daemon reads most agents' own login token via security find-generic-password, the same way any local CLI would. Not every agent touches the keychain, and Muse deliberately doesn't:

Agent	Keychain item	Prompts?
Claude	Claude Code-credentials (account: your macOS username)	No
Cursor	cursor-access-token (account: cursor-user)	No
Codex	— reads its own CLI locally, no keychain	—
agy	— reads ~/.gemini/antigravity-cli/antigravity-oauth-token directly, no keychain	—
Muse	— no keychain at all, see below	—
Grok	— no keychain: reads the weekly SuperGrok limit from grok's CLI billing API with the token grok caches in auth.json (no grok process; a rejected token is renewed by running grok models); per-session tokens and cost come from grok usage, and an exhausted quota seen in a session shows as a full meter	—

Claude's and Cursor's items are created with the default apple-tool: keychain partition, so security (partition apple-tool:) can read them silently — clicking Allow once elsewhere is enough.

Muse's own login item (ai.meta.dev.credentials) is different: muse login locks it to Muse's own code-signing team (partition_id: teamid:V9WTTPBFK9), which excludes security regardless of how many times you click Always Allow — that dialog only grants the app-list ACL, a separate check that isn't the one blocking. Worse, security set-generic-password-partition-list to widen it is not durable: every time Muse's own client refreshes its token, it rewrites the item and resets the partition list back to team-only, silently undoing the widen and bringing the prompt back on Muse's own refresh cadence. So swarm doesn't touch this item at all — Muse usage is read by spawning a short-lived muse serve session and asking its MSP usage/read method directly (internal/usage/muse.go), which costs one cheap, zero-effort model turn on the normal poll cadence instead. No keychain access, no prompts, ever.

Upgrading from Agent Swarm 1.x

swarm migrate --dry-run   # shows what will be imported and archived
swarm migrate

The old database is kept as ~/.swarm/swarm-v1.db. The knowledge base is re-embedded in the background (swarm kb status).

Menu bar app

• The menu bar shows active agents and each enabled agent's 5-hour usage (Cursor shows monthly usage, marked M).
• Needs you: answer questions and open approvals.
• Agents: orchestrators with their sub-agents; open a terminal or pause any row, or Pause all.
• Usage: pick an agent to see all its limits (for example Claude 5h, weekly, and per-model weekly).
• Notifications: everything that happened; Read all clears them.
• Settings: enabled agents, default agent/model/effort per role (model and effort lists come from each agent and refresh daily), the advisor model, notification categories, concurrency limits (orchestrators have their own limit), repository discovery.

Board

Open http://127.0.0.1:7777 (or Open board in the menu bar).

• Hierarchy: epics, bugs and spikes with their children.
• Kanban: tasks (or stories, or top-level items) by status, in swimlanes per top-level item. Drag to change status; Swarm refuses moves that break the rules and says why.
• Dependencies: the dependency graph for an item's tree or its neighbourhood.
• Needs you: the same requests as the menu bar, with full spec sections for review.
• Start orchestrator: on any epic, bug or spike, with agent/model defaults you can override.

CLI

swarm install [--plugins] [--yes]  set up launchd, tmux, superpowers plugins and agent integrations (--plugins: only install/update plugins) (--yes: remove the Agent Swarm 1.x release folders without asking)
swarm doctor [--legacy]            check prerequisites, agents, auth, superpowers, skills, Ollama, signing (--legacy: report Agent Swarm 1.x state still on this Mac)
swarm status                       daemon, active agents, open requests
swarm new --name N --intent feature|debug|chore [--repo PATH...] [--agent A --model M --effort E] [--request TEXT]
swarm start KEY [--agent A --model M --effort E] [--repo PATH...]
swarm agents [--all]               list agents as a tree
swarm attach NAME                  attach to an agent's tmux session here
swarm pause NAME|--all [--group]   pause an agent, its group, or everything
swarm resume NAME
swarm cancel NAME
swarm retry NAME [--note TEXT]     new attempt for a failed, crashed or interrupted agent
swarm ack NAME                     move a failed, crashed or interrupted agent to history
swarm requests                     list open requests
swarm answer REQ TEXT
swarm approve REQ
swarm confirm-repos REQ PATH... [--comment TEXT]
swarm request-changes REQ COMMENT
swarm items [--type T] [--status S] [-q TEXT]
swarm open [KEY]                   open the board
swarm kb search QUERY | kb status
swarm repos [--rescan] | repos add PATH
swarm usage [--refresh]
swarm migrate [--dry-run | --resume | --rollback] [--live]
swarm uninstall                    remove launchd job and agent integrations (keeps data)

Advisor

Every agent can consult a stronger model before big decisions, when stuck, and before finishing. Claude agents use Claude Code's built-in advisor (set with the Advisor default, e.g. Fable). Codex, Antigravity, Cursor and Grok agents call swarm_advise; Swarm runs the advisor model you chose on a condensed copy of the agent's session and returns the answer. Muse has no advisor yet: its read-only form is built but stays off until a live test proves it blocks writes. Advice shows up in each item's Checkpoints tab.

How agents talk to Swarm

Each agent runs swarm mcp as an MCP server. Tools: swarm_sync, swarm_checkpoint, swarm_ask, swarm_send, swarm_read, swarm_kb, swarm_report_bug (records a bug in Swarm itself in the local store, with your transcript attached; list them with swarm bugs, file one on GitHub with swarm bugs --issue ID, board: true also files a Draft bug), swarm_advise (agents without Claude's built-in advisor), and for orchestrators swarm_items, swarm_artifact, swarm_worktree, swarm_spawn, swarm_control, swarm_materialize, swarm_role_overrides, swarm_catalog. Messages are stored in SQLite first; hooks and short notices only tell the agent to fetch them. Nothing an agent sends counts as your approval.

Files

Path	What
~/.swarm/swarm.db	board, agents, sessions, checkpoints, messages
~/.swarm/kb/	knowledge base (markdown)
~/.swarm/run/daemon.token	API token for the board and menu bar
~/.swarm/logs/	daemon logs
~/.swarm/tmux.conf	tmux config for agent sessions
~/.swarm/specs, ~/.swarm/plans	specs and plans written by spikes

Troubleshooting

• Agent shows "Not signed in": run the agent once in a terminal and sign in (claude, codex login, agy, cursor-agent login, muse login, grok login), then Check again in Settings.
• Grok shows "Not signed in" after grok login: Swarm's grok home links auth.json and auth.json.lock to ~/.grok/; rerun swarm install to restore the links, and swarm doctor to check them. Never start grok with --debug-file for a Swarm session: the file holds MCP bearer tokens and your account email in clear text.
• Hooks fail with node: command not found: the daemon's PATH comes from the launchd plist; rerun swarm install after installing Node.
• Terminal button does nothing: allow Swarm to control Ghostty in System Settings → Privacy & Security → Automation.
• Usage shows -- or a dimmed value: the source was unreachable or the agent's login expired; open the agent once to refresh its login.
• Search unavailable: ollama pull qwen3-embedding:0.6b.
• Doctor reports graphify as missing or too old: run swarm install (install uv first with brew install uv if it is missing).
• Commit signing fails in an agent session: make sure gpg-agent has your key unlocked (sign one commit in any terminal), then resume the agent.
• See agent sessions directly: tmux -L swarm ls.

Development

make test      # go test ./... + web tests + swift test
make e2e       # end-to-end run with the fake agent (no model calls)
make dev       # daemon on :17777 with a scratch ~/.swarm-dev

Contributing

Bug reports and pull requests are welcome. Read CONTRIBUTING.md for setup, the test and coverage gate, commit style, and how to let your own Swarm agents file the Swarm bugs they hit as issues or pull requests here. Everyone taking part follows the Code of Conduct.

License

Apache License 2.0. See LICENSE and NOTICE.

Third-party material keeps its own licence: the vendored skills under internal/install/skills/vendor/ (see internal/install/skills/vendor/README.md and each skill's VENDORED.md) and the menu bar icons (assets/icons/LICENSES.md).