openswarm-ai/openswarm

1. Overall shape

- Open Swarm is a local desktop orchestrator, not a traditional web app.

- The runtime is split into three main boundaries: Electron shell for packaging and native integration, React/TypeScript frontend for all user interaction, and a FastAPI/Python backend for orchestration, persistence, and agent execution.

2. Electron as the desktop host

- electron/main.js is the top-level desktop entry point.

- It owns app startup, auto-updates, packaging, and the bundled Python environment.

- The frontend and backend are launched together under Electron during development and in packaged builds, so the desktop app is the actual deployment unit.

3. Frontend responsibilities

- The frontend/ app is the primary UI layer: dashboard canvas, agent chat, skills/tools/modes/settings, and output editors.

- It is state-heavy and uses Redux slices under frontend/src/shared/state to model agents, dashboards, models, tools, modes, skills, sessions, streaming state, and updates.

- A dedicated WebSocket manager and shared hooks connect UI state to live backend events.

4. Backend responsibilities

- backend/main.py starts a FastAPI service on the local machine.

- The backend exposes REST endpoints for CRUD/configuration and WebSocket endpoints for streaming agent activity and approvals.

- It also owns persistent local storage, session lifecycle, tool discovery, registry proxies, and file-system coordination.

5. Agent orchestration is the core subsystem

- backend/apps/agents/ is the orchestration layer for launching, managing, and monitoring agents.

- It handles agent lifecycle, streaming output, approval gating, retries, metrics, history, and specialized browser/invoke workflows.

- The design is centered on parallel sessions: each agent can run independently while the UI aggregates their status into one workspace.

6. Conversation and tool-call streaming

- The live chat experience is driven by backend-to-frontend streaming over WebSockets.

- Streaming includes token deltas, tool calls, approvals, cost updates, and session events.

- The frontend renders this as chat bubbles, tool bubbles, approval bars, and branch navigation, while the backend remains the source of truth for execution state.

7. Git worktree isolation is a key architectural boundary

- The backend’s session and workspace code manages isolated git worktrees per agent.

- This lets multiple agents work in parallel without overwriting each other’s branch state.

- The UI exposes that isolation through the dashboard, diff viewer, and session navigation, but the actual filesystem/branch mechanics live in the backend.

8. Dashboard and spatial workspace

- backend/apps/dashboards, dashboard_layout, and the frontend dashboard pages together implement the “spatial canvas” model.

- Dashboard state is persisted separately from agent sessions so users can arrange cards, open browser/view/agent cards, and resume layouts.

- The dashboard is the main coordination surface, while chat is the detailed interaction surface.

9. Tools, MCP, and external integrations

- backend/apps/tools_lib, mcp_registry, discord_mcp_shim, and google_workspace_mcp_shim cover tool discovery and integration.

- The system supports MCP servers over stdio, HTTP, and SSE, with OAuth support where needed.

- Tool policy, discovery, and registry browsing are first-class, because agent capabilities depend on which tools are connected and allowed.

10. Modes, skills, and prompt composition

- backend/apps/modes, skills, and the prompt manager under backend/apps/agents/manager/prompt define how agents are instructed.

- Modes constrain system prompts and tool access; skills are synced and surfaced for reuse; prompt templates/attachments shape individual runs.

- This is a control-plane layer for agent behavior, separate from the execution/runtime layer.

11. Views and outputs form a second runtime surface

- backend/apps/outputs generates and runs interactive artifacts, including HTML/JS/CSS views and backend-backed runtime processes.

- The frontend has dedicated editors, previews, run dialogs, and code panels for this subsystem.

- This is distinct from agent chat: it is for produced artifacts and live preview, not just conversation.

12. Local persistence and configuration

- Most app state is local and file-based rather than database-backed.

- backend/config and backend/apps/settings manage install IDs, JSON stores, credentials, redaction, and app settings.

- The frontend settings pages map directly onto these backend stores, so config changes are persisted locally and reloaded across restarts.

13. Optional cloud/external dependencies

- The product is “100% local” in the sense that the orchestration stack runs on the user machine, but it still depends on external services when enabled.

- Key outside integrations include Anthropic/Claude APIs for model access, GitHub Releases for updates, Google OAuth for Workspace tools, and package/proxy registries for MCP and skills discovery.

14. Support systems and release pipeline

- openswarm-edge/ is a separate edge/sandbox service used for hosted or published output scenarios, not the main desktop runtime.

- linter/, scripts/, e2e/, and the large backend test suite show that architecture is guarded by repo-level checks, smoke tests, and release verification.

- This repo is built like a desktop platform: core runtime, integration shims, artifact publishing, and strong CI/release gating.