Arnav NavalandCursor
64dfd50d12
Each removal verified by checking actual production callers (frontend,
electron, internal HTTP, MCP-server subprocesses) — not just test
references. Symbols whose only callers were tests are removed along
with those tests.
Production removals (~390 LOC):
- backend/main.py
- websocket_session: drop `agent:edit_message` WS branch. Frontend
only ever uses HTTP `POST /api/agents/sessions/{id}/edit_message`
(frontend/src/shared/state/agentsSlice.ts); nothing on the wire
sends a WS message of this type.
- backend/apps/agents/agent_manager.py
- AgentManager._build_connected_tools_context (~80 LOC): zero call
sites in production; the connected-tools system-prompt context is
built inline in _compose_system_prompt now.
- AgentManager._approx_tokens / _summarize_message_block: pure
helpers whose only callers were tests. The compaction path uses
LLM-driven _maybe_compact instead.
- backend/apps/agents/browser_agent.py
- clear_browser_history: only used by tests. _browser_history is
pruned via the size cap inline.
- MODEL_MAP constant: never read.
- backend/apps/agents/mcp_preflight.py
- DISCOVERY_SCAFFOLDING (~25-line system-prompt block): defined but
never appended anywhere. The header comment described an intended
use that the codebase no longer has.
- backend/apps/agents/providers/registry.py
- thinking_params_for, _is_9router_available, OPENROUTER_BASE_URL,
get_context_window: zero callers in production. Thinking-params
routing is done by the provider classes directly; 9Router presence
is detected at request time; context-window numbers are stamped
onto sessions from BUILTIN_MODELS at launch.
- backend/apps/agents/tools/{base,web}.py
- BaseTool.get_schema (abstract) + WebSearchTool/WebFetchTool
overrides: production code in backend/apps/web/web.py instantiates
these tools and only calls .execute(); the JSON-schema lives in
the HTTP wrapper, not on the tool class.
- backend/apps/outputs/outputs.py
- _resolve_model + MODEL_MAP: tests-only.
- load_output: docstring claimed it was a public helper for "other
modules" but no module imported it.
- backend/apps/service/client.py
- set_user_id, the _user_id module global, and the dead cache short-
circuit in _get_user_id: setter was tests-only. _get_user_id now
reads user_email directly from settings on every call.
- backend/apps/settings/credentials.py
- get_provider_credentials: zero callers. The sibling get_agent_sdk_env
is kept (it has the explicit "Legacy helpers" keep-comment).
Test updates:
- test_agent_manager_unit.py: drop _approx_tokens / _summarize_message_block
cases (5 tests), update module docstring index.
- test_browser_agent_unit.py: drop clear_browser_history cases (2 tests)
and the unused _Boom helper class in the repr-fallback test.
- test_outputs_unit.py: drop _resolve_model / load_output cases
(4 tests), update docstring + import list.
- test_v2_invariants.py: drop get_context_window tests + get_schema
assertions on web tools (kept name + BaseTool inheritance checks).
- test_service.py: rewrite the 4 set_user_id-driven tests to drive
user_id through settings.user_email instead, so _get_user_id's live
envelope-stamping path stays covered.
Verification:
- ruff --select F401,F811,F841 backend/ → clean.
- pytest backend/tests/ → 1167 passed, 1 deselected (pre-existing
sandbox git test, unrelated). No tests dropped silently — every
deletion is paired with the corresponding test removal/rewrite.
- Dead-code scan re-run: dead WS events 1→0, Tier-2 high-confidence
14→11 (residue is SDK-callback `context` params + Pydantic `cls`
validators — both false positives vulture can't see through),
vulture total 165→145.
Total diff: -565 / +34 LOC across 15 files.
Co-authored-by: Cursor <cursoragent@cursor.com>
Open Swarm
An Army of AI Agents at Your Fingertips
A locally-running orchestrator for managing multiple agents in parallel.
Launch, monitor, and coordinate entire swarms of coding agents from a single interface.
Why Open Swarm?
Running agents in a terminal works fine for one task. But when you're juggling five agents across different branches, approving tool calls in separate windows, and losing track of who's doing what — it falls apart fast.
- Parallel agents, one screen — Launch as many agents as you need, arranged on a spatial canvas you can pan and zoom freely
- Unified approval workflow — Every tool-use request from every agent surfaces in one place. Approve or deny with a click or a keyboard shortcut.
- Full conversation control — Edit prior messages to fork conversations, navigate between branches, resume closed sessions
- 100% local — Everything runs on your machine. No cloud relay, no telemetry, no third-party backend.
Features
Spatial Dashboard — Infinite canvas with drag-and-drop agent cards, view cards, and embedded browser cards. Create multiple dashboards for different workspaces.
Agent Chat — Full streaming chat interface powered by WebSockets. Real-time token output, cost tracking per session, and persistent history that survives restarts.
Human-in-the-Loop Approvals — Agents request permission before executing tools. Approve or deny individually, or batch-approve from the dashboard. Configurable per-tool permissions (always allow, ask, deny).
Message Branching — Edit any prior message to fork the conversation. Navigate freely between branches without losing context.
Prompt Templates — Build reusable templates with structured input fields. Invoke them inline via / slash commands.
Skills Library — Manage skills that sync directly to ~/.claude/skills/. Browse and install from the official Anthropic skills marketplace.
Tools Library — Configure MCP tool servers (stdio, HTTP, SSE) with automatic tool discovery. Browse the MCP registry and Google's catalog with GitHub star counts. Includes Google Workspace OAuth integration.
Agent Modes — Five built-in modes (Agent, Ask, Plan, View Builder, Skill Builder) plus custom user-defined modes with configurable system prompts and tool restrictions.
Views & Outputs — Create interactive HTML/JS/CSS artifacts rendered in iframes. Supports vibe coding (LLM-generates the view), backend Python execution, auto-run with LLM-generated data, and agent-driven data gathering.
Git Worktree Isolation — Each agent operates in its own git worktree and branch, preventing conflicts between parallel workstreams.
Diff Viewer — Inspect uncommitted changes in any agent's worktree without leaving the app.
Cost Tracking — Real-time USD spend tracking per agent session.
Dark & Light Themes — Full theme support with design tokens.
Keyboard Shortcuts — Navigate between agents, approve/deny requests, and switch pages without touching a mouse.
Quick Start
Desktop App
Download the latest release for macOS from GitHub Releases.
Windows and Linux builds are planned but not yet available.
Development Setup
Prerequisites: Python 3.11+, Node.js 18+, Git
git clone https://github.com/openswarm-ai/openswarm.git
cd openswarm
bash run.sh
This starts the backend (port 8324), frontend (port 3000), and Electron shell together. Once running, set your Anthropic API key in the in-app Settings page.
To run services individually:
bash backend/run.sh # API at http://localhost:8324 — docs at /docs
bash frontend/run.sh # App at http://localhost:3000
Architecture
Electron Shell (desktop wrapper, auto-updater)
├─────────────────────────────────────────────────────────────────────┐
│ │
│ Frontend (React/TypeScript :3000) Backend (FastAPI :8324) │
│ ┌───────────────────────────────┐ ┌───────────────────────┐ │
│ │ Spatial Dashboard Canvas │◄────►│ REST API (/api/*) │ │
│ │ Agent Chat (streaming) │ │ WebSocket (/ws/*) │ │
│ │ Templates / Skills / Tools │ WS │ Agent Manager │ │
│ │ Modes / Views / Commands │◄────►│ └─ claude-agent-sdk│ │
│ │ Settings │ │ MCP Tool Discovery │ │
│ │ Redux Toolkit (state) │ │ JSON File Storage │ │
│ └───────────────────────────────┘ └───────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
Configuration
The Anthropic API key is configured in-app via the Settings page — no environment variable needed for normal usage.
For advanced configuration, copy backend/.env.example to backend/.env:
| Variable | Purpose |
|---|---|
BACKEND_PORT |
Backend server port (default: 8324) |
GOOGLE_OAUTH_CLIENT_ID |
Google Workspace integration (Gmail, Calendar, Drive) |
GOOGLE_OAUTH_CLIENT_SECRET |
Google Workspace integration |
APPLE_ID |
macOS code signing & notarization (release builds only) |
APPLE_APP_SPECIFIC_PASSWORD |
macOS notarization (release builds only) |
APPLE_TEAM_ID |
macOS code signing (release builds only) |
GH_TOKEN |
GitHub Releases publishing (release builds only) |
Keyboard Shortcuts
| Key | Action |
|---|---|
D |
Go to Dashboard |
T |
Go to Templates |
1 – 9 |
Open agent by position |
Shift+A |
Approve all pending requests |
Shift+D |
Deny all pending requests |
? |
Show shortcuts help |
Type / in the chat input to invoke prompt templates and skills as slash commands.
Project Structure
backend/
apps/
agents/ Agent lifecycle, streaming, worktree management
dashboards/ Dashboard CRUD and layout persistence
templates/ Prompt template CRUD
skills/ Skills CRUD (synced to ~/.claude/skills/)
tools_lib/ MCP tool configuration and discovery
modes/ Agent mode definitions
outputs/ Views/outputs, vibe coding, Python executor
settings/ App settings and file browser
health/ Health check endpoint
mcp_registry/ MCP server registry proxy
skill_registry/ Anthropic skills marketplace proxy
config/ FastAPI app configuration
data/ Persistent JSON file storage
frontend/
src/
app/
components/ AppShell, Layout, shared UI
pages/
Dashboard/ Spatial canvas with agent/view/browser cards
AgentChat/ Streaming chat, HITL approvals, branching, diff viewer
Templates/ Template library with structured input fields
Skills/ Skills library, skill builder, registry browser
Tools/ Tool config, MCP discovery, OAuth, registry browser
Modes/ Mode definitions with system prompts
Views/ Output artifacts, code editor, vibe coding
Commands/ Keyboard shortcuts reference
Settings/ App configuration
shared/
state/ Redux slices (agents, dashboards, templates, skills, tools, modes, etc.)
ws/ WebSocket manager
hooks/ Custom hooks
styles/ Theme tokens, global styles
electron/
main.js Electron main process, auto-updater, Python env management
scripts/ Build and notarization scripts
scripts/
build-app.sh Desktop app packaging (electron-builder)
build-python-env.sh Standalone Python 3.13 environment bundler
Tech Stack
Frontend — React 18, TypeScript, Redux Toolkit, Material UI v7, CodeMirror 6, Framer Motion, React Router v7, Webpack 5
Backend — FastAPI, Python 3.11+, Pydantic v2, claude-agent-sdk, Anthropic SDK, WebSockets, httpx
Desktop — Electron 33, electron-builder, electron-updater (auto-updates via GitHub Releases)
Bundled Runtime — Standalone Python 3.13 (via python-build-standalone) so end users don't need Python installed
Contributing
Contributions are welcome. To get started:
- Fork the repository
- Create a feature branch (
git checkout -b feature/your-feature) - Make your changes
- Submit a pull request
Please open an issue first for larger changes so we can discuss the approach.
License
MIT — see LICENSE for details.