swarmclawai/swarmclaw

1. Overall shape

SwarmClaw is a self-hosted, full-stack TypeScript control plane for autonomous agents. The same codebase serves three entrypoints: the Next.js dashboard/API, a Node CLI (swarmclaw), and an Electron desktop shell. Most behavior is implemented in shared server-side libraries so the UI, CLI, and desktop app all drive the same runtime.

2. Primary UI surface

The dashboard lives under src/app and uses Next.js App Router pages plus server route handlers. The UI is organized by domain: agents, chats, tasks, runs, schedules, memory, providers, connectors, skills, protocols, quality, missions, chatrooms, and settings. Components and feature modules mostly stay thin and call into shared query/client helpers rather than implementing business logic themselves.

3. API layer as the control plane

The src/app/api/**/route.ts tree is the main inbound API surface. It exposes CRUD and action endpoints for nearly every domain, plus special routes for health, auth, uploads/files, sharing, exports/imports, A2A discovery, OpenClaw, SwarmDock, SwarmFeed, MCP servers, and quality gates. These routes translate HTTP into domain services in src/lib/server/**.

4. Server-side domain services

The real architecture lives in src/lib/server. It is split into repositories, services, schedulers, and execution engines for each domain: agents, chats, tasks, runs, protocols, schedules, memory, connectors, gateways, skills, extensions, credentials, wallets, projects, and more. The pattern is consistent: route handlers call services, services call repositories and runtime helpers, and repositories isolate persistence details.

5. Agent/chat execution pipeline

The core runtime path is chat execution. src/lib/server/chat-execution/** and src/lib/server/agents/** handle prompt construction, tool routing, stream execution, turn finalization, continuation, compaction, and state tracking. This is where agent turns become model calls, tool events, persisted messages, follow-up actions, and connector deliveries. The chat UI is essentially a live view over this pipeline.

6. Autonomy and background work

Long-running behavior is handled by the runtime layer under src/lib/server/runtime/** and adjacent autonomy modules. This includes heartbeat loops, wake scheduling, queueing, orphan recovery, daemon control, estop/guardrails, scheduled-run preflight, and session-run management. The runtime is what turns agents from interactive chat participants into autonomous workers that can resume, retry, and recover after interruption.

7. Orchestration primitives

SwarmClaw supports structured execution beyond simple chat: tasks, runs, protocols, missions, schedules, and structured sessions. src/lib/server/protocols/** models DAG-style flows with branches, joins, loops, subflows, and swarms; tasks and runs provide durable execution records and handoff packets; schedules triggers work over time; missions wraps operational workflows with budgets and reports. This is the orchestration boundary diagrammatically: user intent enters, and one of these durable work primitives executes it.

8. Provider and gateway abstraction

Model access is abstracted through src/lib/providers/** and src/lib/server/provider*. The system supports both API providers and CLI-backed providers, plus OpenAI-compatible endpoints, local runtimes like Ollama, and OpenClaw gateways. Provider health, model discovery, diagnostics, and per-agent provider config are first-class because provider choice materially changes how execution streams, tool use, and context limits behave.

9. External integrations

Connectors are a major boundary: src/lib/server/connectors/** and the related UI/API manage Slack, Discord, Telegram, WhatsApp, Teams, Matrix, email, file queues, OpenClaw, SwarmDock, and SwarmFeed. The connector subsystem includes inbound delivery, outbound outboxes, pairing/access, policy checks, media handling, and connector-specific runtime state. It is effectively the event bridge between SwarmClaw and outside communication channels.

10. Memory, knowledge, and artifacts

Durable context is handled by the memory and knowledge subsystems plus documents/artifacts. src/lib/server/memory/** manages tiers, graph/retrieval, dreams/reflection, consolidation, and session memory scope; knowledge handles sources and hygiene; artifacts, documents, and files expose persisted outputs and shared references. This is the long-term persistence boundary for agent learning and operator recall, separate from transient chat transcripts.

11. Skills, extensions, and tool surfaces

Agent capabilities are assembled from skills, MCP servers, built-in tools, and extensions. src/lib/server/session-tools/** builds the per-session tool set, while skills, extensions, and mcp-* modules manage discovery, install/update, conformance, approvals, and managed resources. This is the capability layer that determines what an agent can actually do in a turn.

12. Persistence and local runtime model

The repo is designed around a local data directory and workspace model rather than a remote central database. Repositories under src/lib/server/*-repository.ts persist durable records for chats, agents, tasks, schedules, memory, connectors, shares, and configs, while runtime helpers create task/session workspaces and file-backed snapshots where needed. The architecture is therefore “local control plane with durable state,” not a stateless API server.

13. Desktop, CLI, and deployment wrappers

bin/, src/cli, and electron/ wrap the same application into different operating modes. The CLI exposes operational commands for setup, diagnostics, updates, schedules, tasks, runs, providers, and gateways. Electron manages the desktop shell, server lifecycle, updater, and app paths. Container and hosted deploy files (Dockerfile, docker-compose.yml, fly.toml, railway.json, render.yaml) all point to the same core runtime.

14. Observability, quality, and release safety

Quality and observability are not sidecars; they are built into the product. src/lib/server/observability, src/lib/server/quality, src/lib/server/eval, and the /quality APIs provide architecture-health checks, release-readiness scoring, eval gating, and trace export. This creates an operator feedback loop around the runtime so execution, provider health, and autonomy can be inspected and gated before release.

15. Key architectural boundary

The clearest diagram boundary is between the interactive shell layer and the durable runtime layer. UI pages, CLI commands, and Electron all converge on the same API routes and shared server libraries; those server libraries then fan out to provider adapters, connector bridges, storage repositories, and runtime workers. That shared-control-plane design is the central architectural idea of the repository.