Open Swarm: a local orchestrator for running many coding agents at once

The terminal-multiplexing problem Open Swarm targets

The README frames the problem in one paragraph: running agents in a terminal works fine for one task, but juggling five agents across different branches, approving tool calls in separate windows, and losing track of who is doing what falls apart fast. That is a specific complaint, not a general one. It is about supervision cost, not about model capability. Once you have more than two or three agent sessions open, the work shifts from writing prompts to remembering which window is waiting on a permission prompt and which branch a change landed on.

Open Swarm's answer is a single window with a spatial canvas. Agents become cards you can drag, pan and zoom around, and every tool-use request from every agent surfaces in one approval place. The intended user is a developer already running Claude Code or a comparable agent loop who wants parallel workstreams without parallel terminal tabs. It is not aimed at someone who runs one agent at a time, and it is not a hosted service. The README states everything runs on your machine, with no cloud relay, no telemetry and no third-party backend. Your prompts, diffs and API key stay on the laptop.

Electron shell, FastAPI backend, React canvas: how the pieces connect

The architecture diagram in the README is unusually concrete, so it is worth reading literally. An Electron shell wraps the whole thing and handles auto-updating. Inside it, a React and TypeScript frontend runs on port 3000 and a FastAPI backend runs on port 8324. The two talk over two channels: REST under /api/* and WebSockets under /ws/*. The frontend holds Redux Toolkit state and renders the spatial dashboard, the streaming chat, and the template, skill, tool, mode and view pages. The backend owns the Agent Manager, which sits on top of claude-agent-sdk, plus MCP tool discovery and JSON file storage.

That last detail matters more than it looks. Persistence is JSON files, not a database. Conversation history survives restarts, per the feature list, but there is no query layer and no migrations. For a single-user desktop tool that is a reasonable simplification. It also means you should treat the storage directory as the thing to back up, and it means concurrent access from two app instances is not something the design appears to anticipate.

Approvals flow the other way. Agents request permission before executing tools, the request is pushed to the frontend over the WebSocket, and your click or keyboard shortcut goes back down to the Agent Manager. Permissions are configurable per tool with three states: always allow, ask, deny. Streaming token output and per-session USD cost tracking ride the same socket. The project structure confirms the split: backend/apps/agents handles agent lifecycle, streaming and worktree management, while backend/apps/dashboards and backend/apps/dashboard_layout handle CRUD and card positions separately.

Git worktrees are the isolation mechanism, and they set the ceiling

Parallel agents editing one checkout would corrupt each other's work. Open Swarm's fix is git worktree isolation: each agent operates in its own worktree and branch. This is the right primitive for the job because worktrees share the object store, so spinning up a dozen of them is cheap compared with a dozen full clones. The README also mentions a diff viewer for inspecting uncommitted changes in any agent's worktree without leaving the app, which closes the loop between isolation and review.

The ceiling follows from the same choice. Worktrees are still git, so anything that is not committed in a worktree is not visible from another agent's branch. If two agents need to touch the same file, worktree isolation does not merge their intent; it just keeps the conflict out of your working directory until you merge. The README does not describe an automatic merge or rebase strategy, so the integration step stays manual. That is a limitation worth naming, because the marketing line about preventing conflicts between parallel workstreams is true at the filesystem level and silent at the semantic level.

Getting it running: run.sh, port 8324, and the API key in Settings

There are two paths. The desktop route is to download the latest macOS release from GitHub Releases. The README notes that Windows and Linux builds are planned but not yet available, so the desktop app is macOS only in practice.

For development, the prerequisites are Python 3.11+, Node.js 18+ and Git. The quick start is three commands:

git clone https://github.com/openswarm-ai/openswarm.git cd openswarm bash run.sh

That single script starts the backend on port 8324, the frontend on port 3000 and the Electron shell together. Once it is up, you set your Anthropic API key in the in-app Settings page. The README is explicit that no environment variable is needed for normal usage.

If you want the services separately, the README gives two more scripts: bash backend/run.sh serves the API at http://localhost:8324 with docs at /docs, and bash frontend/run.sh serves the app at http://localhost:3000. The /docs endpoint is a FastAPI convention, and it is the fastest way to see what the REST surface actually exposes without reading the frontend.

Advanced settings come from copying backend/.env.example to backend/.env. The documented keys are BACKEND_PORT (default 8324), GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET for the Google Workspace integration covering Gmail, Calendar and Drive, and four release-only keys: APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID and GH_TOKEN, which are for code signing, notarization and publishing your own builds. If you are not shipping a signed macOS release, you can ignore those four.

The licence badge says MIT, the repository says AGPL-3.0

This is the first thing to resolve, and it is not a small discrepancy. The README renders a shields.io badge reading license-MIT-blue, and links it to LICENSE. The repository metadata for openswarm-ai/openswarm lists AGPL-3.0. Those are very different obligations. AGPL-3.0 is a strong copyleft licence with a network-use clause: if you modify the software and let users interact with it over a network, you are generally required to offer them the corresponding source. MIT carries no such requirement.

The README also invites pull requests with a PRs-welcome badge, which is normal for either licence but changes meaning under AGPL if you intend to relicense contributions later. I cannot tell from the supplied material which licence the LICENSE file actually contains, only that the two signals disagree. Treat the metadata as the safer assumption and read LICENSE yourself before you build anything on top of this. This is not legal advice, and if your organisation has a policy against AGPL dependencies, that policy is the thing to check first.

Version numbers that say experimental, and a macOS-only release line

The most recent releases are v1.7.10-exp.11, v1.7.10-exp.10 and v1.7.10-exp.9, dated within four days of each other in September 2026. The exp suffix is the project telling you what it thinks of its own stability, and the cadence is fast. Three tagged releases in four days means the surface is moving, and it means an auto-updater in the Electron shell will hand you new builds regularly.

For a tool that holds your API key and your conversation history, that update rate is a real cost. The README does not describe a release channel selector, so the practical choice is between running the packaged app and tracking experimental tags, or cloning and running bash run.sh from a commit you picked. The second option gives you control over when the code changes under you, at the cost of managing Python 3.11+, Node 18+ and Git yourself.

Maintenance surface is otherwise modest. There is no database to migrate, since storage is JSON files. The main upgrade risks are the claude-agent-sdk dependency and the MCP tool servers you configure, both of which sit between Open Swarm and the outside world. Nothing in the README suggests a schema versioning story for those JSON files, so a future release that changes the on-disk shape is a plausible upgrade hazard. Back up the storage directory before pulling.

Where Open Swarm stops and plain Claude Code starts

The obvious alternative is running Claude Code directly in a terminal, which is what Open Swarm is built on top of rather than a replacement for. The difference in approach is supervision. Claude Code gives you one session per terminal, with its own approval prompts and its own working directory. You get the full CLI, you get it on Linux and Windows, and you get no Electron process. What you do not get is a shared approval queue across sessions, a canvas that shows which agent is blocked, or per-session cost readouts side by side.

So the comparison is not about agent quality, since both routes end at the same model and the same SDK. It is about whether the coordination layer earns its footprint. If your workflow is one agent, one task, one branch, Open Swarm adds a FastAPI server, a React app and an Electron shell around something a terminal already does. If your workflow is four agents on four branches with frequent permission prompts, the unified approval view and the worktree-per-agent model are the parts that pay for themselves, and the README's keyboard shortcuts (Shift+A to approve all pending, Shift+D to deny all, 1 through 9 to jump to an agent by position) are designed for exactly that mode of work.

A second point of comparison sits inside the app itself. The Tools Library configures MCP servers over stdio, HTTP and SSE with automatic tool discovery, and the README mentions browsing the MCP registry and Google's catalog with GitHub star counts. Star counts are a weak signal for whether a tool server is safe to point at your filesystem, so treat that browsing UI as a discovery aid rather than a vetting step.

Editorial conclusion

Adopt Open Swarm if you already run several Claude coding sessions in separate terminals and want one approval queue plus git worktree isolation, and you are on macOS. Do not adopt it if you need Windows or Linux today, or if AGPL-3.0 obligations are unresolved for your organisation. Before installing, confirm the actual licence text in LICENSE against the MIT badge in the README, check whether the release you download is one of the 1.7.10-exp builds, and read backend/.env.example to see which settings you must supply yourself.

Official sources

1. License: AGPL-3.0
2. openswarm-ai/openswarm on GitHub
3. Project website
4. README
5. Releases