TheAchiever6823
fe0c3af0f2
Brings the branch current with dev (was 18 behind) so the PR squash-merges into dev with zero conflicts. Resolved 6 conflicts: - backend/main.py: keep both workflows and telegram_bot SubApps - backend/auth.py: keep the Spotify OAuth callback path exemptions - backend/apps/agents/agent_manager.py: take the deletions of _build_connected_tools_context, _approx_tokens, and _summarize_message_block (confirmed dead, zero callers on dev) - backend/apps/tools_lib/tools_lib.py: keep both dev's google_oauth_token_proxy and the MCP credential endpoints - electron/main.js: keep both the Instagram MCP CLI helpers and dev's one-line waitForBackend comment - frontend/src/app/pages/Tools/Tools.tsx: keep the credential dialogs Also widens the Tools.tsx snackbar severity union to include 'warning', a value its own code already passes (a pre-existing type error surfaced once dev was merged and tsc was run). Verified: 832 backend tests pass, webpack build succeeds, tsc clean except one pre-existing allowpopups error in dev's BrowserCard.tsx.
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
dashboard_layout/ Card positions and spatial canvas state
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.