Agent = Model + Harness. The model writes; the harness gives it tools, memory, loops, sandboxes, and controls so it can actually work. Swarmdo is the harness — the execution layer around Claude Code and Codex that adds 100+ specialized agents, coordinated swarms, self-learning memory, federated comms across machines, and enterprise security guardrails. So agents don't just run, they collaborate.

One npx swarmdo init gives Claude Code a nervous system: agents self-organize into swarms, learn from every task, remember across sessions, and — with federation — securely talk to agents on other machines without leaking data. You keep writing code. Swarmdo handles the coordination.

Self-Learning / Self-Optimizing Agent Architecture

User --> Swarmdo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Providers
                          ^                           |
                          +---- Learning Loop <-------+

New to Swarmdo? You don't need to learn 314 MCP tools or 26 CLI commands. After init, just use Claude Code normally — the hooks system automatically routes tasks, learns from successful patterns, and coordinates agents in the background.

Quick Start

There are two different install paths with very different surface areas. Pick based on what you need (#1744):

Path A — Claude Code Plugins (lite, slash commands only)

# Add the marketplace
/plugin marketplace add upstream/swarmdo

# Install core + any plugins you need
/plugin install swarmdo-core@swarmdo
/plugin install swarmdo-swarm@swarmdo
/plugin install swarmdo-rag-memory@swarmdo
/plugin install swarmdo-neural-trader@swarmdo

This adds slash commands and agent definitions only. The Swarmdo MCP server is NOT registered, so memory_store, swarm_init, agent_spawn, etc. won't be callable from Claude. For the full loop, use Path B below.

CLI Install

macOS / Linux / WSL / Git-Bash:

# One-line install (POSIX shells only — see Windows note below)
curl -fsSL https://cdn.jsdelivr.net/gh/upstream/swarmdo@main/scripts/install.sh | bash

All platforms (including native Windows PowerShell / cmd):

# Interactive setup wizard — runs identically on every platform
npx swarmdo@latest init wizard

# Compress a memory file to save tokens (caveman mode — e2e-verified 33% smaller, backup kept)
npx swarmdo compress CLAUDE.md
npx swarmdo compress notes.md --check   # token-free: just report compressibility

# Quick non-interactive init
# npx swarmdo@latest init

# Or install globally
npm install -g swarmdo@latest

💡 Windows users: the curl ... | bash form needs a POSIX shell (Git-Bash, WSL, MSYS). The npx swarmdo@latest init wizard line works natively in PowerShell and cmd. If you hit an 'bash' is not recognized error, use the npx line instead — both end up running the same init flow.

MCP Server

# Add Swarmdo as an MCP server in Claude Code (canonical form, matches USERGUIDE.md)
claude mcp add swarmdo -- npx swarmdo@latest mcp start

One Namespace: /sDo

Since v1.4.0 every slash surface swarmdo installs is namespaced, so the whole toolkit groups together in Claude Code's / menu instead of scattering between built-ins — type /sDo and it all surfaces:

/sDo:swarmdo-help        /sDo:swarm:swarm-init     /sDo:sparc:architect
/sdo-caveman-compress    /sdo-ponytail             /sdo-agentdb-vector-search

Commands use the sDo: namespace (.claude/commands/sDo/…); skills use the sdo- prefix (skill names must be lowercase). Upgrades migrate automatically — swarmdo init and swarmdo efficiency on remove pre-1.4.0 unprefixed copies so no duplicate menu entries linger.

Efficiency: Caveman & Ponytail, Built In

Two of the most-loved Claude Code skills ship inside swarmdo as first-class features — vendored MIT forks with attribution in NOTICE, integrated across the CLI, the agents, and the init wizard.

🪨 Caveman compression

Memory files (CLAUDE.md, notes, todos) get re-read every session — and they're written for humans, not token budgets. Caveman rewrites them in few-token caveman-speak with substance, code, and URLs preserved and the original backed up. E2E-verified: 33% smaller with every technical fact intact.

# Inside Claude Code
/sdo-caveman-compress CLAUDE.md

# From any terminal — no Claude Code session needed
swarmdo compress CLAUDE.md
swarmdo compress notes.md --check     # token-free dry run: reports type + compressibility

💤 Ponytail mode

The laziest senior dev in the room, on demand: YAGNI, standard library before dependencies, one line before fifty, no speculative abstraction. Three intensities plus audit/review/debt lenses.

# Inside Claude Code
/sdo-ponytail            # lite | full | ultra

# For spawned agents — per call:
#   agent_run / agent_execute with ponytail: true
# or globally:
export SWARMDO_PONYTAIL=1            # explicit ponytail:false always wins

Toggling

Everything is opt-in and reversible — skills are user-invoked, so "on" means available, never automatic.

Credits: caveman by Julius Brussee · ponytail by Dietrich Gebert (both MIT).

What You Get

🧰 The Operational Toolkit (v1.3 → v1.4)

The recent release train added a full day-to-day operations layer around the swarm — spend, safety, releases, and memory portability:

swarmdo usage blocks                   # 5h windows, live burn on the active one
swarmdo usage guard --block-usd 5 --daily-usd 20 --strict
swarmdo changelog --version v1.4.4 --out NOTES.md
swarmdo hooks recipe notify-done --apply
swarmdo memory export -o ./vault -f obsidian && open ./vault

Swarmdo's web UI is a multi-model AI chat with built-in Model Context Protocol (MCP) tool calling. Talk to Qwen, Claude, Gemini, or OpenAI while Swarmdo invokes the same MCP tools the CLI uses — agent orchestration, persistent memory, swarm coordination, code review, GitHub ops — directly from chat. No install, no API key needed to try it.

Agent Federation — Slack for Agents

Your Agent --> [ Remove secrets ] --> [ Sign message ] --> [ Encrypted channel ]
                 Emails, SSNs,        Proves it came       No one reads it
                 keys stripped         from you              in transit
                                                                |
                                                                v
Their Agent <-- [ Block attacks ] <-- [ Check identity ] <------+
                 Stops prompt          Rejects forgeries
                 injection

                          Audit trail on both sides.
                  Trust builds over time. Bad behavior = instant downgrade.

Slack gave teams channels. Federation gives agents the same thing — shared workspaces across trust boundaries, where agents on different machines, orgs, or cloud regions can discover each other, prove who they are, and collaborate on tasks.

The difference: some channels are trusted, some aren't. [@swarmdo/plugin-agent-federation](the upstream project (see NOTICE)) handles that automatically. Your agents join a federation, get verified via mTLS + ed25519, and start exchanging work — with PII stripped before anything leaves your node and every message auditable. Untrusted agents can still participate at lower privilege: they see discovery info, not your memory. As they prove reliable, trust upgrades. If they misbehave, they get downgraded instantly — no human in the loop required.

You don't configure handshakes or manage certificates. You federation init, federation join, and your agents start talking. The protocol handles identity, the PII pipeline handles data safety, and the audit trail handles compliance.

📘 Full user guide: docs/federation/ — setup, MCP tools, trust levels, circuit breaker, and the (opt-in) WireGuard mesh layer that ties packet-layer reachability to federation trust. ADR-111 deep-dive at docs/federation/phase7-mesh-bringup.md.

# Team A: initialize federation and generate keypair
npx swarmdo@latest federation init

# Team A: join Team B's federation endpoint
npx swarmdo@latest federation join wss://team-b.example.com:8443

# Team A: send a task — PII is stripped automatically before it leaves
npx swarmdo@latest federation send --to team-b --type task-request \
  --message "Analyze transaction patterns for account anomalies"

# Team A: check peer trust levels and session health
npx swarmdo@latest federation status

See [issue #1669](the upstream project (see NOTICE)) for the complete architecture, trust model, and implementation roadmap.

# Claude Code plugin
/plugin install swarmdo-federation@swarmdo

# Or via CLI
npx swarmdo@latest plugins install @swarmdo/plugin-agent-federation

User --> Claude Code / CLI
          |
          v
    Orchestration Layer
    (MCP Server, Router, 27 Hooks)
          |
          v
    Swarm Coordination
    (Queen, Topology, Consensus)
          |
          v
    100+ Specialized Agents
    (coder, tester, reviewer, architect, security...)
          |
          v
    Memory & Learning
    (AgentDB, HNSW, SONA, ReasoningBank)
          |
          v
    LLM Providers
    (Claude, GPT, Gemini, Cohere, Ollama)

Documentation

Four docs for four audiences:

Benchmark internals (for reproduction): [sota-workload-spec.md](the upstream project (see NOTICE)) · [SOTA-PROGRESS.md](the upstream project (see NOTICE)) · [raw matrix JSON: darwin](the upstream project (see NOTICE)) · [linux](the upstream project (see NOTICE))

User Guide section index:

Support

License

MIT - [the upstream author](https://the upstream project (see NOTICE))