# Docs

- Documentation: Guides, concepts, and reference for agent-swarm.dev
  - [Introduction](/docs): Agent Swarm docs for deploying and orchestrating autonomous AI coding agent teams — lead delegation, Docker workers, persistent memory, Slack, GitHub, Linear, MCP tools, and x402 payments.
  - [Getting Started](/docs/getting-started): Install Agent Swarm, configure your first lead and worker agents, and run your first multi-agent task in minutes
  - Architecture: undefined
    - [Architecture Overview](/docs/architecture/overview): Hub-and-spoke architecture for multi-agent AI orchestration — central MCP API server coordinates Docker-isolated worker agents with persistent SQLite state, vector memory, and Claude Code harness integration.
    - [Agent Identity & Configuration](/docs/architecture/agents): AI agent identity architecture — SOUL.md, IDENTITY.md, CLAUDE.md, and TOOLS.md combine to give each agent a persistent role, expertise, and self-evolving memory across Claude Code sessions.
    - [Memory System](/docs/architecture/memory): Persistent AI agent memory — vector embeddings, semantic search, TTL expiry, and reranking with recency and access signals so agents accumulate knowledge across Claude Code sessions instead of starting fresh.
    - [Hook System](/docs/architecture/hooks): Six lifecycle hooks — SessionStart, PreCompact, PreToolUse, PostToolUse, UserPromptSubmit, and Stop — provide safety guardrails, context persistence, and automatic identity sync across every Claude Code agent session.
  - Concepts: undefined
    - [Task Lifecycle](/docs/concepts/task-lifecycle): The complete task lifecycle in Agent Swarm — from unassigned through offered, pending, in_progress, paused, and finally completed or failed. Learn heartbeat detection, checkpoint recovery, retry strategies, and how task dependencies orchestrate multi-agent workflows.
    - [Service Discovery](/docs/concepts/services): Register, discover, and health-check HTTP services that agents expose for inter-agent communication
    - [Scheduled Tasks](/docs/concepts/scheduling): Schedule recurring or one-time AI agent tasks with cron expressions and delayed execution — automate daily reports, polling, and time-driven workflows across the swarm.
    - [Workflows](/docs/concepts/workflows): Run multi-step AI agent pipelines automatically — trigger workflows from webhooks, schedule them with cron, route tasks conditionally, and recover from crashes. Orchestrate your agent swarm with DAG-based automation.
  - UI: Dashboard reference
    - [Overview](/docs/ui): The Agent Swarm dashboard — what it is, the hosted instance at app.agent-swarm.dev, and how to self-host it
    - [Configuration](/docs/ui/configuration): Manage operator-facing swarm settings from the dashboard — feature flags, thresholds, and defaults grouped by subsystem
  - Playbooks: undefined
    - [Playbooks](/docs/playbooks): Ten production playbooks for running an agent swarm — feature development, prospecting, content, UX audits, customer support, code health, code-health reports, DORA metrics, cross-source reports, and self-documenting releases. Real flows, real schedules, real agents.
    - [Feature Development](/docs/playbooks/feature-development): Take feature requests from Slack or a Linear ticket and turn them into pull requests, end to end — with research, planning, implementation, review, and merge handled by specialized agents that hand context off via agent-fs.
    - [Lead Prospecting](/docs/playbooks/lead-prospecting): Plug your prospecting stack into the swarm — daily discovery, drafting, and scheduling — with a human-in-the-loop gate before anything sends. Tracks "already contacted" so re-runs don't double-touch.
    - [Content Generation](/docs/playbooks/content-generation): Topic mining, blog posts, social posts, memes, comparison and how-to pages, and release notes — at the cadence you want, with LLM-as-judge quality gates and human craft on top before anything ships.
    - [UX Command Center](/docs/playbooks/ux-command-center): A standing UX agent that keeps your product usable — weekly audits against your design system, agentic browser session recording, and proactive UX-improvement proposals from user telemetry. Creates a Linear umbrella with one sub-issue per finding.
    - [Proactive Customer Support](/docs/playbooks/proactive-customer-support): Standing agents per top account — persistent working directories, scheduled value-showcase reports, automatic post-meeting ingestion, and "what changed since last touchpoint?" briefings on demand.
    - [Observability Alert Management](/docs/playbooks/code-health-alert-management): Plug your alerting tools (Datadog, New Relic, Sentry, SigNoz) into the swarm. Real signals kick off fixes or proposals; noise gets filtered. Daily/weekly health audits catch slow rot before it ships.
    - [Code Health](/docs/playbooks/code-health-reports): Run recurring Code Maat + D3.js code-health reports for any Git repository. The swarm installs the runner, refreshes the report weekly by default, and updates one stable Page URL in place.
    - [DORA Metrics](/docs/playbooks/dora-metrics): Run recurring DORA metrics reports for any Git repository. The swarm computes exact deployment frequency and lead time from release tags, labels CFR and recovery time as proxy estimates, and updates one stable Page URL in place.
    - [Reports from Multiple Sources](/docs/playbooks/reports-multiple-sources): Integrate your data warehouse, product analytics, billing, search analytics, and observability into one swarm — then ask it the questions your team would have asked a BI tool. Charts render as auto-hosted Pages.
    - [Self-Documenting & Release Reports](/docs/playbooks/self-documenting-release-reports): Keep your docs fresh automatically, generate release notes from real commits, and produce release videos with Remotion + browser-automation captures. No-op silently on quiet days.
    - **Hot patterns**

    - Hot patterns: undefined
      - [Hot Patterns](/docs/playbooks/patterns): Five patterns that recur across every playbook — litmus tests, drain loops, HITL gates, per-customer working directories, and no-op workflows. These are the recipes that compound, regardless of which use case you're building.
      - [Pattern: Litmus Tests (LLM-as-Judge Quality Gates)](/docs/playbooks/patterns/litmus-tests): A quality gate where one agent hard-rejects another agent's output against an explicit rubric — using a different model family so the judgment is genuinely independent and not rubber-stamping in disguise.
      - [Pattern: Drain Loops (Stacked PRs + Merge Loop)](/docs/playbooks/patterns/drain-loops): Turn one big parent issue into a chain of small, individually-reviewable stacked PRs, then review-and-merge them bottom-up with a merge loop that halts on the first failure.
      - [Pattern: HITL Gates (Human-in-the-Loop Approval)](/docs/playbooks/patterns/hitl-gates): Pause a workflow mid-flight until a human approves in Slack. The agent does the work; the human owns the irreversible decision (sending, merging, deleting, posting publicly).
      - [Pattern: Per-Customer Working Directories](/docs/playbooks/patterns/per-customer-working-directories): Give each top account a persistent folder in agent-fs where agents accumulate context across months. A 6-month-old note like "they care about EU data residency" is what makes the next report feel personal.
      - [Pattern: No-op When Nothing Changed](/docs/playbooks/patterns/no-op-workflows): A scheduled workflow that first asks "did anything actually happen?" and skips silently if not — so it never produces empty reports, noise commits, or training-data-style "nothing to report" messages.
  - Guides: undefined
    - [Deployment Guide](/docs/guides/deployment): Deploy Agent Swarm to production with Docker Compose — volumes, networking, secrets, and persistent storage
    - [Published Artifacts](/docs/guides/published-artifacts): Everything an Agent Swarm release publishes — Docker images and tags (full vs slim), E2B templates, the npm package, and the Helm chart
    - [Asset Namespaces](/docs/guides/asset-namespaces): Group tasks, workflows, schedules, pages, and provider-backed files under canonical shared or personal namespace keys
    - [agent-fs Co-deployment](/docs/guides/agent-fs-co-deployment): Run agent-fs alongside Agent Swarm for persistent shared files, task attachments, previews, and semantic search
    - [Self-Hosted SSO](/docs/guides/self-hosted-sso): Protect your self-hosted Agent Swarm deployment with Single Sign-On — oauth2-proxy quickstart and trusted-header forwarding mode.
    - [E2B Provider Smoke Tests](/docs/guides/e2b-provider-smoke-tests): Run real provider smoke tests from Dockerless environments by launching ephemeral E2B workers against a live swarm API
    - [Evals Harness](/docs/guides/evals-harness): Run scenario × harness-config evaluation matrices against real Agent Swarm stacks in E2B, with deterministic checks, judge models, and persisted artifacts.
    - [Personalization & Status](/docs/guides/personalization): Brand the swarm with org name + logo + brand color, surface setup readiness via /status, and build cloud-aware UX with the SWARM_* identity envs.
    - [Secrets Encryption](/docs/guides/secrets-encryption): How swarm_config secrets are encrypted at rest, how the encryption key is resolved, and what to back up
    - [Harness Configuration](/docs/guides/harness-configuration): Configure the AI provider (Claude Code, Codex, opencode, pi-mono, Devin, or Claude Managed Agents) that powers your agents
    - [Adding a Harness Provider](/docs/guides/harness-providers): Implement a harness provider — the adapter contract, reference implementations, live steering capabilities, and wiring checklist
    - [Steer a Running Task](/docs/guides/task-steering): Add context to a running agent, request an interrupt, and understand degradation and delivery states
    - [Observability with OpenTelemetry](/docs/guides/observability-opentelemetry): Send Agent Swarm traces and OTLP metrics to SigNoz or any compatible backend, filter local runs, and inspect API, worker, MCP, and tool execution telemetry.
    - [Performance & Resource Sizing](/docs/guides/performance-resource-sizing): Size Agent Swarm containers by role, understand harness reliability profiles, and avoid common CPU and memory metric traps.
    - [Cost & context computation](/docs/guides/cost-and-context-computation): How cost and context-window numbers are computed across harness providers, and how to read the costSource / contextFormula badges in the UI.
    - [Scripts runtime](/docs/guides/scripts-runtime): What the swarm-scripts runtime exposes to user code, what it does NOT expose, and how the typecheck stays aligned.
    - [Scripts-only mode (code-mode)](/docs/guides/scripts-only-mode): Trim the swarm MCP surface to the 8 script tools and run all coordination through the scripts SDK — when to use it, how to enable it, and what changes.
    - [Script connections](/docs/guides/script-connections): Register OpenAPI, GraphQL, and MCP APIs once — with optional OAuth or config-backed credentials — and call them from any swarm script via typed ctx.api / ctx.mcp clients.
    - [OAuth callback migration](/docs/guides/oauth-callback-migration): The connections redesign moves generic OAuth apps to a single static callback URL. Add it to your provider app registration so re-authorization keeps working.
    - [Scripts as external APIs](/docs/guides/scripts-external-apis): Expose a saved swarm script as a public, JSON-in/JSON-out HTTP endpoint — POST /api/x/script/<id> — with optional bearer auth, typed input validation, and per-endpoint usage tracking.
    - [Scripts credential broker](/docs/guides/scripts-credential-broker): How scripts authenticate to external APIs without raw secrets in source, args, or logs.
    - [One-off Script Workflow Runs](/docs/guides/script-workflow-runs): Launch, inspect, and operate durable one-off TypeScript workflow runs without registering a reusable DAG.
    - [Claude Bridge](/docs/guides/claude-bridge-experimental): Opt-in `claude -p` bridge that keeps Claude harness runs on the Max/Pro subscription credit pool
    - [Worker Credential Recovery](/docs/guides/worker-credential-recovery): Workers wait for harness credentials at runtime instead of crash-looping the container — how the boot loop, dispatcher gating, and dashboard surface fit together
    - Provider Auth: undefined
      - [Codex OAuth](/docs/guides/provider-auth/codex-oauth): Set up ChatGPT OAuth for Codex workers in local and remote Agent Swarm deployments
    - [Slack Integration](/docs/guides/slack-integration): Connect Agent Swarm to Slack — @mention agents to create tasks, use swarm# syntax to target specific workers, and manage multi-agent workflows via direct messages, channels, and the Slack Assistant sidebar.
    - [GitHub App Integration](/docs/guides/github-integration): Connect your GitHub repos to Agent Swarm — AI agents auto-trigger on @mentions, issue assignments, and labels via webhooks. Full setup guide with permissions, event handling, and bi-directional sync.
    - [GitLab Integration](/docs/guides/gitlab-integration): Set up GitLab webhooks for automated task creation from merge requests, issues, and comments
    - [AgentMail Integration](/docs/guides/agentmail-integration): Set up AgentMail to give each agent its own email inbox for receiving newsletters, notifications, and external messages
    - [Sentry Integration](/docs/guides/sentry-integration): Set up Sentry error monitoring for AI agents — workers include sentry-cli pre-installed for automatic issue investigation, stacktrace analysis, breadcrumb review, and one-command resolve or mute directly from the agent loop.
    - [Jira Integration](/docs/guides/jira-integration): Connect Agent Swarm to Atlassian Jira Cloud for bidirectional issue tracking via OAuth 3LO and dynamic webhooks
    - [x402 Payments](/docs/guides/x402-payments): Configure AI agents to autonomously pay for x402-gated APIs using USDC on Base — gasless HTTP 402 micropayments with automatic retry and spending limits.
  - Integrations: undefined
    - [Integrations](/docs/integrations): External tools the swarm can talk to — issue trackers, chat platforms, error monitoring, email, and more.
    - [Linear](/docs/integrations/linear): Inbound webhook → swarm tasks. Workflow-state gate, swarm-ready label override, AgentSession activity stream, and how to push outbound updates.
    - [Kapso (WhatsApp)](/docs/integrations/kapso): Inbound WhatsApp messages become swarm tasks via Kapso; agents reply in-thread. Native webhook handler, KV-backed number routing, outbound send/reply MCP tools, and the kapso-whatsapp skill for everything beyond plain text.
    - [Composio](/docs/integrations/composio): Tool Router sessions, connected accounts, Connect Links, and the Agent Swarm x route for third-party app tools.
    - [Salesforce](/docs/integrations/salesforce): Connect Salesforce as an MCP server over OAuth so agents can use any of Salesforce's hosted MCP endpoints.
  - Reference: undefined
    - [MCP Tools Reference](/docs/reference/mcp-tools): Complete reference for Agent Swarm MCP tools — core and deferred tiers, annotations, Tool Search discovery, and capability-based organization
    - [Environment Variables](/docs/reference/environment-variables): Complete reference for all Agent Swarm environment variables — server configuration, API keys, MCP base URL, Slack tokens, GitHub credentials, and integration settings for self-hosted deployments
    - [CLI Reference](/docs/reference/cli): Complete CLI reference for managing agents, tasks, and swarm configuration from the terminal — install via bunx or npx, manage worktrees, run agent commands, and configure your swarm without the dashboard UI
    - [The `x` command](/docs/reference/x-command): External command routes for Agent Swarm, starting with Composio Tool Router.
    - [Telemetry](/docs/reference/telemetry): What telemetry Agent Swarm collects, how it's anonymized, and how to opt out — lifecycle, session-cost, workflow, schedule, and compaction event tracking without PII collection
  - Releases: undefined
    - [Release Notes](/docs/releases): Weekly release notes for Agent Swarm — new features, improvements, and fixes
    - [Release Notes — Week of July 27 to August 3, 2026](/docs/releases/2026-08-03): Mid-run task steering across all providers, a single OpenRouter gateway, an operator configuration page, honest MCP tool results, and 61 commits across 4 themes.
    - [Release Notes — Week of July 20-27, 2026](/docs/releases/2026-07-27): A redesigned Connections experience, workspace personalization, and stronger controls for self-hosted deployments.
    - [Release Notes — Week of July 13-20, 2026](/docs/releases/2026-07-20): A lighter scripts-only MCP deployment mode, plus reliability and observability improvements across agent-fs, evals, and self-hosted docs.
    - [Release Notes — Week of July 6-12, 2026](/docs/releases/2026-07-13): Script Connections MVP, asset namespaces, RBAC rollout, memory usefulness, model tiers and UI refinements land this week.
    - [Release Notes — Week of June 22-29, 2026](/docs/releases/2026-06-29): Secure script integrations land this week, plus hybrid memory search and platform reliability upgrades.
    - [Release Notes — Week of May 25-June 1, 2026](/docs/releases/2026-06-01): Self-serve E2B swarm operations, better follow-up continuity, broader messaging reach, and a round of reliability hardening.
    - [Release Notes — Week of May 19-25, 2026](/docs/releases/2026-05-25): Five releases ship end-to-end OpenTelemetry tracing, pointer-based task attachments, a reusable scripts runtime, and promote humans to first-class users.
    - [Week of April 7, 2026](/docs/releases/2026-04-07): Agent Swarm release notes for the week of April 7, 2026
  - [Contributing](/docs/contributing): How to contribute to Agent Swarm — development setup, coding standards, PR workflow, and project architecture
- Receipts: Shareable, copy-pasteable workflow recipes any swarm operator can drop into their deployment
  - [Receipts](/docs/receipts): Pre-built, battle-tested Agent Swarm workflow recipes — copy-paste configurations for iterative agent loops, scheduled tasks, error recovery, and human-in-the-loop approval. Drop into your deployment with minimal adaptation.
  - Workflows: Workflow recipes — copy-pasteable workflow JSONs for common patterns
    - [Ralph Loop](/docs/receipts/workflows/ralph-loop): A reusable iterative agent-loop workflow that pairs a worker with an analyst, with persistent scratch space in agent-fs and a max-iteration safety cap.
- API Reference v1.129.0: REST API reference for agent-swarm.dev
  - [API Reference](/docs/api-reference): Complete REST API reference for agent-swarm.dev — 171 endpoints across tasks, agents, workflows, memory, webhooks, and more. Build multi-agent orchestration with HTTP APIs and real-time event streaming.
  - [API Keys](/docs/api-reference/api-keys): Manage API keys for authenticating requests to the agent-swarm.dev API
  - [Active Sessions](/docs/api-reference/active-sessions): Monitor and control active agent sessions running in the swarm
  - [Agents](/docs/api-reference/agents): CRUD operations for agent profiles — create, configure, update, and manage swarm agents
  - [ApprovalRequests](/docs/api-reference/approvalrequests): Human-in-the-loop approval requests — review and respond to agent-escalated decisions
  - [Apps](/docs/api-reference/apps): Apps API endpoints
  - [Assets](/docs/api-reference/assets): Assets API endpoints
  - [Budgets](/docs/api-reference/budgets): Configure per-agent and global daily cost budgets to control AI agent spend
  - [Config](/docs/api-reference/config): Read and write swarm configuration values — global, agent-scoped, and repo-scoped settings
  - [Debug](/docs/api-reference/debug): Debug utilities for inspecting swarm state and diagnosing agent issues
  - [Ecosystem](/docs/api-reference/ecosystem): Query registered community and official agent integrations in the swarm ecosystem
  - [Events](/docs/api-reference/events): Stream and query swarm lifecycle events — task transitions, agent state changes, and audit log
  - [External APIs](/docs/api-reference/external-apis): External APIs API endpoints
  - [FS](/docs/api-reference/fs): FS API endpoints
  - [Favorites](/docs/api-reference/favorites): Favorites API endpoints
  - [Heartbeat](/docs/api-reference/heartbeat): Health check endpoint — verify the agent-swarm.dev API is running and reachable
  - [Inbox State](/docs/api-reference/inbox-state): Manage per-user inbox item state — dismiss, snooze, and mark-done flags for swarm notifications and approval items
  - [Integrations](/docs/api-reference/integrations): Configure third-party integrations — Slack, GitHub, GitLab, Linear, Jira, Sentry, and more
  - [KV](/docs/api-reference/kv): Namespaced key-value store API — read, write, delete, list, and atomically increment KV entries for cross-task agent state
  - [MCP OAuth](/docs/api-reference/mcp-oauth): OAuth flows for MCP client authorization — register and manage OAuth connections
  - [MCP Servers](/docs/api-reference/mcp-servers): Register and manage MCP tool servers available to swarm agents
  - [Memory](/docs/api-reference/memory): Search, retrieve, and manage persistent agent memories across sessions
  - [Metrics](/docs/api-reference/metrics): Metrics API endpoints
  - [OAuth](/docs/api-reference/oauth): OAuth API endpoints
  - [Pages](/docs/api-reference/pages): Create, version, launch, and render DB-backed pages — build interactive dashboards and static artifacts served by the swarm
  - [Poll](/docs/api-reference/poll): Long-poll endpoints for real-time task and message notifications without WebSockets
  - [Pricing](/docs/api-reference/pricing): Retrieve model pricing data used for cost tracking and budget enforcement across agents
  - [PromptTemplates](/docs/api-reference/prompttemplates): Store and retrieve reusable prompt templates for consistent agent instructions
  - [Repos](/docs/api-reference/repos): Register code repositories and configure VCS integration for automated task triggers
  - [Schedules](/docs/api-reference/schedules): Create and manage scheduled tasks — run agents on cron expressions or one-time delays
  - [Script Connections](/docs/api-reference/script-connections): Script Connections API endpoints
  - [Script Runs](/docs/api-reference/script-runs): Inspect durable script workflow runs, review journal entries, and monitor swarm-script, raw-LLM, and agent-task execution status through the Script Runs API
  - [Scripts](/docs/api-reference/scripts): Author, search, and run reusable TypeScript scripts — a shared automation catalog callable across swarm agents and workflows
  - [Session Data](/docs/api-reference/session-data): Access session-level data including token counts, costs, and context window metrics
  - [Sessions](/docs/api-reference/sessions): Inspect task sessions — list recent root tasks and retrieve the full descendant task chain for a session
  - [Skills](/docs/api-reference/skills): Install, publish, and manage skills — reusable agent behaviors and tool sets
  - [Stats](/docs/api-reference/stats): Aggregate statistics for swarm activity — task counts, agent utilization, and cost summaries
  - [Status](/docs/api-reference/status): Swarm dashboard status endpoint — identity, setup readiness, live activity, and harness provider credential testing
  - [Task Templates](/docs/api-reference/task-templates): List reusable task templates — pre-defined task definitions agents pick up to start common swarm workflows
  - [Tasks](/docs/api-reference/tasks): Core task API — create, assign, update, and monitor tasks across the swarm
  - [Trackers](/docs/api-reference/trackers): Integrate with Linear and Jira ticket trackers — sync issues to swarm tasks bidirectionally
  - [Users](/docs/api-reference/users): Manage the user registry — create users, link cross-platform identities, mint tokens, merge duplicates, and triage unmapped senders
  - [Webhooks](/docs/api-reference/webhooks): Register and manage webhooks for real-time swarm event delivery to external systems
  - [WorkflowEvents](/docs/api-reference/workflowevents): Subscribe to and manage workflow lifecycle events — run status, step completions, failures, and convergence gates for DAG orchestration
  - [Workflows](/docs/api-reference/workflows): Define and execute DAG-based multi-step workflows with branching, triggers, and agent task nodes