Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coretracker/agentswarm/llms.txt

Use this file to discover all available pages before exploring further.

AgentSwarm is a TypeScript monorepo whose runtime shape is a Docker Compose stack. A Fastify API server orchestrates tasks, a Next.js web app provides the browser UI, isolated agent containers execute Codex and Claude work, and Redis carries the real-time event stream that keeps the UI in sync. Understanding how these pieces fit together makes it easier to navigate the codebase, debug problems, and contribute safely.

​
Monorepo Structure

The repository is organised as an npm workspaces monorepo. The top-level layout is: 
.
├── apps/
│   ├── server/          # Fastify API, task orchestration, stores, routes, schedulers
│   └── web/             # Next.js web app
├── packages/
│   └── shared-types/    # Shared TypeScript types used by server and web
├── agent-runtime-codex/ # Automated Codex task runtime container
├── agent-runtime-claude/# Automated Claude task runtime container
├── tools/               # Supporting runtime and terminal tooling
├── docs/                # Architecture, development, product, and quality docs
├── scripts/harness/     # Canonical setup, check, test, and PR scripts
├── task-workspaces/     # Runtime task workspaces — do not commit
├── docker-compose.yml   # Local Docker stack
└── agentswarm.sh        # Main stack helper script

apps/server

The Fastify backend. Handles authentication, task lifecycle, repository management, scheduling, agent spawning, GitHub webhooks, and all API routes. Runs on port 4000 inside the Docker network.

apps/web

The Next.js frontend. Calls backend APIs and receives real-time updates over Socket.IO. Runs on port 3217 (dev) and communicates with the server through the nginx reverse proxy.

packages/shared-types

The @agentswarm/shared-types package. Defines all TypeScript types that cross the server/web boundary — tasks, runs, events, repositories, and more. Contains no business logic.

agent-runtime-codex / agent-runtime-claude

Container images launched on-demand by the server for each task run. Each image bundles the provider CLI (Codex or Claude), Git tooling, and a runner script that streams logs and diffs back to the server.

​
Runtime Shape

The Docker Compose stack wires together five long-running services plus the ephemeral agent containers:
ServiceImagePurpose
proxynginxReverse proxy. Routes /api/* requests to the server; all other traffic to the web app.
server@agentswarm/serverFastify API on port 4000. Orchestrates tasks, manages stores, handles webhooks.
web@agentswarm/webNext.js on port 3217. Serves the browser UI and connects via Socket.IO for real-time updates.
postgrespostgresDurable data store for tasks, repositories, users, settings, and all other application data.
redisredisSessions, task queues, webhook jobs, GitHub outbound queue, and real-time pub/sub event channel.
agent containersagentswarm-agent-runtime-codex:latest / agentswarm-agent-runtime-claude:latestLaunched on-demand by the server’s SpawnerService for each task run. Terminated when the run completes.
The public entry point is always nginx on PUBLIC_PORT (default 3217). The server and web services are not exposed directly outside the Docker network in production configurations.

​
Data Flow

A task run follows this path from browser click to streamed output:
1

Task creation

The user submits a task in the web UI. The web app calls POST /api/tasks (or a related import/draft route) on the server through the nginx /api/* proxy.
2

Scheduling

The SchedulerService picks up the new task from the taskQueueStore (backed by Redis) and decides when to run it based on concurrency limits and provider settings.
3

Spawning

The SpawnerService launches a new Docker container from the appropriate runtime image (CODEX_RUNTIME_IMAGE or CLAUDE_RUNTIME_IMAGE). The container is mounted with the task workspace directory so that both the server and the runtime container share the same filesystem path.
4

Execution

Inside the runtime container, the agent CLI (Codex or Claude) executes the task prompt against the cloned repository. The runner script streams structured log lines and Git diffs back to the server over the shared workspace.
5

Real-time updates

The server publishes RealtimeEvent payloads (task status changes, log lines, run updates, change proposals) to the Redis pub/sub channel. The server’s Socket.IO layer subscribes to this channel and forwards events to authenticated browser clients.
6

UI update

The web app receives Socket.IO events and updates the task detail page in real time — showing live logs, diffs, checkpoints, and final status without a page refresh.

​
Shared Types Package

@agentswarm/shared-types (packages/shared-types/) is the single source of truth for data contracts that cross the server/web boundary. Both apps/server and apps/web depend on it as an npm workspace package: 
// Both server and web import from the package root — never by filesystem path
import type { Task, TaskRun, RealtimeEvent } from "@agentswarm/shared-types";
packages/shared-types must never contain business logic or import from apps/server or apps/web. It is a pure type contract. Boundary checks enforce this automatically.

​
Server Modules

The server (apps/server/src/) is organised into focused modules:

routes/

Fastify route handlers for every API surface: auth.ts, tasks.ts, task-drafts.ts, repositories.ts, users.ts, roles.ts, settings.ts, snippets.ts, sequences.ts, imports.ts, and github-webhooks.ts.

services/

Stateful services injected into routes: task-store.ts, spawner.ts, scheduler.ts, sequence-execution-service.ts, github-import-service.ts, github-outbound-service.ts, webhook-delivery-service.ts, and the Postgres store factories.

lib/

Pure orchestration and utility logic: task start orchestration, Git operations, provider config, auth, Docker socket access, MCP config, and interactive terminal management.

config/env.ts

Typed environment configuration parsed and validated with Zod at startup. All environment variables are accessed through the env object — never via process.env directly.
The server entry point (src/index.ts) bootstraps all services in order: Fastify app → Redis clients → Postgres pool → migrations → stores → auth → routes → Socket.IO → scheduler → ready.

​
Real-Time Events

The server publishes events to a Redis pub/sub channel. The Socket.IO server subscribes to that channel and forwards events to authenticated browser clients scoped to the resources each user can access. Events are typed as the RealtimeEvent union from @agentswarm/shared-types:
Event typePayloadWhen fired
task:created / task:updatedTaskTask is created or its status/fields change.
task:deleted{ id, repoId, ownerUserId }Task is deleted.
task:log{ taskId, runId, line, timestamp }A log line arrives from a running agent container.
task:message / task:message_updatedTaskMessageAn agent message is added or updated.
task:run_updatedTaskRunA run record changes status or metadata.
task:git_operationTaskGitOperationA Git operation (push, merge, revert) completes.
task:change_proposalTaskChangeProposalThe agent proposes a change for review.
task:pushed{ taskId, repoId, branchName, … }Task branch is pushed to the remote.
task:merged{ taskId, repoId, sourceBranch, targetBranch, … }Task branch is merged.
settings:updatedSystemSettingsProvider or system settings change.
repository:created / repository:updated / repository:deletedRepositoryRepository record changes.
snippet:created / snippet:updated / snippet:deletedSnippetSnippet record is created, updated, or deleted.
sequence:created / sequence:updated / sequence:deletedSequenceSequence record is created, updated, or deleted.
sequence:run_updatedSequenceRunA prompt sequence run progresses.
The web app listens for these events via socket.io-client and updates component state without requiring a page reload.

​
Boundary Rules

Architecture boundaries are enforced mechanically by scripts/harness/boundary-check.mjs, which runs as part of both check.sh and pr-ready.sh.
Any file under apps/web importing from apps/server is a violation. Browser code cannot depend on backend internals.Fix: Move shared logic to packages/shared-types or call server APIs instead.
Any file under apps/server importing from apps/web is a violation. Backend services must not depend on UI implementation details.Fix: Move shared contracts to packages/shared-types or keep the logic in a server module.
Any file under packages/shared-types importing from apps/* is a violation. The shared contract layer must remain dependency-free.Fix: Remove app-specific logic from shared-types entirely.
Importing shared types via a filesystem path (e.g. ../../packages/shared-types/src/index) instead of the package name (@agentswarm/shared-types) is a violation.Fix: Replace the relative path import with import type { … } from "@agentswarm/shared-types".
Importing via a sub-path (e.g. @agentswarm/shared-types/some/deep/path) is a violation. Only the root package export is public.Fix: Import from @agentswarm/shared-types root only.
Run the boundary check at any time without the full suite: 
node ./scripts/harness/boundary-check.mjs
Every violation output includes what rule was broken, why it exists, and exactly how to fix it.

Build docs developers (and LLMs) love

Get started for freeTalk to us