{"id":"0a702407-49d9-45b4-8171-f1ed0b380be2","slug":"alexandertar-agent-swarm","kind":"mcp","name":"agent-swarm","summary":"Plan and deliver software with a team of AI coding agents you supervise from your Mac. Local daemon, web board and menu bar app orchestrating Claude Code, Codex, Cursor, Antigravity, Grok and Muse ove","owner":"AlexanderTar","repoUrl":"https://github.com/AlexanderTar/agent-swarm","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-08-28T09:55:29.000Z","addedAt":"2026-10-21T06:42:02.647Z","logoUrl":"https://avatars.githubusercontent.com/u/4199898?u=00ca3426c25962c4b44f8848eddc1b8110f07bb0&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","memory-knowledge"],"tags":["agent-orchestration","ai-agents","claude-code","codex","coding-agents","cursor","developer-tools","go"],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T06:43:17.820Z","sample":false,"url":"https://conduits.dev/tools/alexandertar-agent-swarm","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Agent Swarm\n\nPlan and deliver software with a team of coding agents you supervise from your Mac.\n\nAgent Swarm is a local tool with three parts:\n\n- **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.\n- **A web board** at http://127.0.0.1:7777 with hierarchy, kanban and dependency-graph views.\n- **A menu bar app** (Swarm.app) showing running agents, requests that need you, usage per agent, and notifications.\n\nSupported 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.\n\n## How work flows\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n5. **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.\n6. **Supervise.** Open any agent's terminal from the menu bar or board, pause one agent or everything, and read checkpoints instead of transcripts.\n\nSpecs 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.\n\n## Requirements\n\n- macOS 14 or later, logged in to the GUI session\n- [Homebrew](https://brew.sh)\n- 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)\n- [Ghostty](https://ghostty.org) 1.3+\n- [Ollama](https://ollama.com) with `qwen3-embedding:0.6b` (knowledge base search)\n- At least one agent CLI, signed in: `claude`, `codex`, `agy`, `cursor-agent`\n- Nothing to install for [superpowers](https://github.com/obra/superpowers): `swarm install` installs the superpowers plugins for every agent it finds (Cursor must be signed in first)\n- graphify 0.9.71 ([Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify)), installed by swarm install through uv\n- Git commit signing enabled (`commit.gpgsign=true`) in repositories agents work in\n\n```bash\nbrew install go tmux pnpm uv\nbrew install --cask ghostty ollama\nollama pull qwen3-embedding:0.6b\n```\n\n## Install\n\n```bash\ngit clone https://github.com/AlexanderTar/agent-swarm.git\ncd agent-swarm\nmake install        # builds swarm into ~/.swarm/bin and Swarm.app into /Applications\nswarm install       # launchd service, tmux config, agent MCP/hooks/skill, first-run checks\nswarm doctor        # verify everything\nopen /Applications/Swarm.app\n```\n\n`swarm install` does the following:\n\n- writes `~/Library/LaunchAgents/dev.swarm.daemon.plist` and starts the daemon on 127.0.0.1:7777\n- writes `~/.swarm/tmux.conf` (agents run on a private tmux socket, `tmux -L swarm`)\n- 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)\n- installs graphify 0.9.71 with uv and gives every agent the graphify skill\n- scans your home folder for git repositories (hidden folders, `~/Library`, `~/Music`, `~/Pictures`, `~/Movies`, and `~/Downloads` are skipped by default; change exclusions in Settings)\n- removes hooks and config left by Agent Swarm 1.x\n- links `swarm` into `~/.local/bin`\n\nThe 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.\n\n### Code signing and macOS permissions\n\nLocal 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.\n\nTo keep permissions trusted permanently across rebuilds and redeploys, create a persistent local self-signed code-signing certificate named `Swarm Dev`:\n\n```bash\n# 1. Create a certificate configuration\ncat << 'EOF' > /tmp/swarm-cert.conf\n[ req ]\ndefault_bits        = 2048\ndistinguished_name  = req_dn\nprompt              = no\nx509_extensions     = v3_code_sign\n\n[ req_dn ]\nCN = Swarm Dev\n\n[ v3_code_sign ]\nkeyUsage = critical, digitalSignature\nextendedKeyUsage = critical, codeSigning\nbasicConstraints = critical, CA:FALSE\nEOF\n\n# 2. Generate private key and certificate\nopenssl req -new -x509 -days 3650 -config /tmp/swarm-cert.conf -nodes -keyout /tmp/swarm-key.pem -out /tmp/swarm-cert.pem\nopenssl pkcs12 -export -legacy -inkey /tmp/swarm-key.pem -in /tmp/swarm-cert.pem -out /tmp/swarm-cert.p12 -passout pass:swarmdev -name \"Swarm Dev\"\n\n# 3. Import and trust in your login keychain\nsecurity import /tmp/swarm-cert.p12 -k ~/Library/Keychains/login.keychain-db -P swarmdev -T /usr/bin/codesign\nsecurity add-trusted-cert -p codeSign -k ~/Library/Keychains/login.keychain-db /tmp/swarm-cert.pem\nrm -f /tmp/swarm-cert.conf /tmp/swarm-key.pem /tmp/swarm-cert.pem /tmp/swarm-cert.p12\n```\n\nThe `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>\"`.\n\n### Keychain access (per-agent usage numbers)\n\nTo 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:\n\n| Agent | Keychain item | Prompts? |\n|---|---|---|\n| Claude | `Claude Code-credentials` (account: your macOS username) | No |\n| Cursor | `cursor-access-token` (account: `cursor-user`) | No |\n| Codex | — reads its own CLI locally, no keychain | — |\n| agy | — reads `~/.gemini/antigravity-cli/antigravity-oauth-token` directly, no keychain | — |\n| Muse | — no keychain at all, see below | — |\n| 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 | — |\n\nClaude'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.\n\nMuse'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.\n\n### Upgrading from Agent Swarm 1.x\n\n```bash\nswarm migrate --dry-run   # shows what will be imported and archived\nswarm migrate\n```\n\nThe old database is kept as `~/.swarm/swarm-v1.db`. The knowledge base is re-embedded in the background (`swarm kb status`).\n\n## Menu bar app\n\n- The menu bar shows active agents and each enabled agent's 5-hour usage (Cursor shows monthly usage, marked M).\n- **Needs you**: answer questions and open approvals.\n- **Agents**: orchestrators with their sub-agents; open a terminal or pause any row, or Pause all.\n- **Usage**: pick an agent to see all its limits (for example Claude 5h, weekly, and per-model weekly).\n- **Notifications**: everything that happened; Read all clears them.\n- **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.\n\n## Board\n\nOpen http://127.0.0.1:7777 (or Open board in the menu bar).\n\n- **Hierarchy**: epics, bugs and spikes with their children.\n- **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.\n- **Dependencies**: the dependency graph for an item's tree or its neighbourhood.\n- **Needs you**: the same requests as the menu bar, with full spec sections for review.\n- **Start orchestrator**: on any epic, bug or spike, with agent/model defaults you can override.\n\n## CLI\n\n```text\nswarm 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)\nswarm doctor [--legacy]            check prerequisites, agents, auth, superpowers, skills, Ollama, signing (--legacy: report Agent Swarm 1.x state still on this Mac)\nswarm status                       daemon, active agents, open requests\nswarm new --name N --intent feature|debug|chore [--repo PATH...] [--agent A --model M --effort E] [--request TEXT]\nswarm start KEY [--agent A --model M --effort E] [--repo PATH...]\nswarm agents [--all]               list agents as a tree\nswarm attach NAME                  attach to an agent's tmux session here\nswarm pause NAME|--all [--group]   pause an agent, its group, or everything\nswarm resume NAME\nswarm cancel NAME\nswarm retry NAME [--note TEXT]     new attempt for a failed, crashed or interrupted agent\nswarm ack NAME                     move a failed, crashed or interrupted agent to history\nswarm requests                     list open requests\nswarm answer REQ TEXT\nswarm approve REQ\nswarm confirm-repos REQ PATH... [--comment TEXT]\nswarm request-changes REQ COMMENT\nswarm items [--type T] [--status S] [-q TEXT]\nswarm open [KEY]                   open the board\nswarm kb search QUERY | kb status\nswarm repos [--rescan] | repos add PATH\nswarm usage [--refresh]\nswarm migrate [--dry-run | --resume | --rollback] [--live]\nswarm uninstall                    remove launchd job and agent integrations (keeps data)\n```\n\n## Advisor\n\nEvery 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.\n\n## How agents talk to Swarm\n\nEach 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.\n\n## Files\n\n| Path | What |\n|---|---|\n| `~/.swarm/swarm.db` | board, agents, sessions, checkpoints, messages |\n| `~/.swarm/kb/` | knowledge base (markdown) |\n| `~/.swarm/run/daemon.token` | API token for the board and menu bar |\n| `~/.swarm/logs/` | daemon logs |\n| `~/.swarm/tmux.conf` | tmux config for agent sessions |\n| `~/.swarm/specs`, `~/.swarm/plans` | specs and plans written by spikes |\n\n## Troubleshooting\n\n- **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.\n- **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.\n- **Hooks fail with `node: command not found`**: the daemon's PATH comes from the launchd plist; rerun `swarm install` after installing Node.\n- **Terminal button does nothing**: allow Swarm to control Ghostty in System Settings → Privacy & Security → Automation.\n- **Usage shows `--` or a dimmed value**: the source was unreachable or the agent's login expired; open the agent once to refresh its login.\n- **Search unavailable**: `ollama pull qwen3-embedding:0.6b`.\n- **Doctor reports graphify as missing or too old**: run `swarm install` (install `uv` first with `brew install uv` if it is missing).\n- **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.\n- **See agent sessions directly**: `tmux -L swarm ls`.\n\n## Development\n\n```bash\nmake test      # go test ./... + web tests + swift test\nmake e2e       # end-to-end run with the fake agent (no model calls)\nmake dev       # daemon on :17777 with a scratch ~/.swarm-dev\n```\n\n## Contributing\n\nBug reports and pull requests are welcome. Read [CONTRIBUTING.md](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](CODE_OF_CONDUCT.md).\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).\n\nThird-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`).\n"}