agent-swarm

Agent Swarm is an orchestration platform for deploying and managing teams of autonomous AI coding agents. It uses a lead agent to receive tasks and delegate them to multiple worker agents that run in isolated Docker containers. This architecture allows for autonomous task breakdown, execution, and code shipping with minimal manual intervention.

Core Workflow

1. Task Input: Tasks are received via Slack, GitHub, Email, or the API.
2. Planning: The Lead Agent breaks the task into subtasks.
3. Execution: Worker agents execute tasks within isolated Docker environments (containing tools like git, Node.js, Python, etc.).
4. Tracking: Progress is monitored via a Dashboard UI, Slack threads, or the API.
5. Delivery: Results are delivered through PRs, closed issues, or Slack replies.
6. Learning: Session learnings are extracted to improve future task performance.

KV Storage is a namespaced key/value store located within the swarm SQLite database. It is automatically scoped to your calling context (the same string used by agent_tasks.contextKey).

When to use KV

• Counting/State in a specific context: Use KV for counting things in a Slack thread, PR, or Linear issue, or for saving cursors/last-seen state for recurring schedules.
• Deduplication & Idempotency: Use KV with a TTL (Time-To-Live) to track if a message has been processed or if an email has already been sent.
• Routing/Mapping: Use KV for tables that map inputs to agents (e.g., "which agent handles number X?").
• Cross-task state: Use KV to share state between sibling tasks in the same conversation (e.g., scoped to task:slack:...).

When NOT to use KV

• Secrets: Use swarm_config (it is encrypted and masked).
• Long-term knowledge: Use memory_search / memory-get for cross-session agent knowledge.
• Large files/binaries: Use agent-fs for images, PDFs, or large documents.
• Logs/Audit trails: Use agent-fs or store-progress.
• Workflow run state: Use workflow variables (which have their own KV).

The agent-swarm project supports Model Context Protocol (MCP) server management, allowing agents to define, install, and use additional MCP servers beyond the built-in agent-swarm and agentmail servers.

Key Capabilities

• Dynamic Management: Create MCP server definitions (stdio or HTTP) with scoped secrets.
• Per-Agent Installation: Install or uninstall specific MCP servers for individual agents.
• Multi-Provider Support:
  • Claude: Servers are synced to .mcp.json at boot. Claude automatically namespaces tools as mcp__<server>__<tool>.
  • Pi-mono: Servers are injected as customTools via McpHttpClient. Note that Pi-mono only supports HTTP transport; stdio clients are not supported for this provider.
• Secret Management: Secrets are not stored directly in the MCP server definitions. Instead, definitions use references to configuration keys (envConfigKeys or headerConfigKeys) which point to entries in the swarm_config system.
• Lifecycle: Changes to MCP servers take effect at the start of a new session (no hot-reloading mid-session).

The swarm operates through three primary data cycles:

1. Task Creation

1. A user sends a message (Slack, GitHub, email, or API).
2. The MCP server receives the request.
3. The Lead agent's inbox receives the message.
4. The Lead agent triages the message and creates tasks for workers.

2. Task Execution

1. A worker receives or polls for a task assignment.
2. The worker starts a session (e.g., Claude Code) with the task context.
3. The worker executes the task using MCP tools.
4. The worker reports progress via store-progress.
5. Upon completion, output is saved and the Lead is notified.

3. Learning Loop

1. At the end of a session, a summary model extracts key learnings.
2. Learnings are embedded and stored in the memory system.
3. On subsequent tasks, relevant memories are retrieved and injected into the context.
4. The Lead agent can also manually inject learnings into workers.

claude-context-mode is an MCP plugin designed to reduce context window consumption during intensive research and planning tasks. It intercepts tool outputs (like large file reads or web fetches) and compresses them using an FTS5-backed SQLite knowledge base.

Core Capabilities

• 6 MCP Tools: batch_execute, execute, execute_file, index, search, and fetch_and_index.
• Sandboxed Execution: Commands run in isolated subprocesses; only stdout summaries are passed to the context.
• FTS5 Knowledge Base: Uses SQLite with BM25 ranking and fuzzy matching to allow efficient searching of large datasets without flooding the context.
• PreToolUse Hooks: Automatically intercepts and redirects specific tools:
  • Bash (curl/wget) $\rightarrow$ suggests execute or fetch_and_index.
  • WebFetch $\rightarrow$ Denies the call and redirects to fetch_and_index.
  • Read $\rightarrow$ Provides advisory tips for large files.
  • Grep $\rightarrow$ Provides advisory tips for large results.
  • Task $\rightarrow$ Injects routing instructions into subagent prompts.

The Jira Cloud integration allows Agent Swarm to act as a first-class tracker, mirroring the existing Linear integration. It uses OAuth 2.0 (3LO) for connection, supports webhook-driven inbound task creation, and posts outbound comments on task lifecycle events.

Key Features:

• OAuth 2.0 (3LO) Flow: Connects a Jira Cloud workspace and automatically resolves the cloudId.
• Webhook Support: Supports both auto-registered webhooks (refreshed every 25 days) and manually admin-registered webhooks.
• Task Lifecycle Sync: Automatically posts plaintext comments to the originating Jira issue when a swarm task is started, completed, failed, or cancelled.
• Idempotent Ingress: Uses tracker_sync to ensure inbound tasks are processed without duplicates.
• Security: Webhook deliveries are authenticated via a URL-path token compared against the JIRA_WEBHOOK_TOKEN environment variable.