⚠️ DEPRECATED: Fully migrated to hermes agent.

<div align="center"> <img src="docs/images/swarm_logo.png" alt="Swarm Logo" width="200"/>

Swarm Orchestrator v3.4

Turn your IDE into an Autonomous Engineering Team

</div>

---

What is Swarm?

Swarm Orchestrator is a Model Context Protocol (MCP) server that extends AI coding assistants like Antigravity, Cursor, and Claude Desktop with deterministic, algorithmic capabilities. Instead of relying purely on LLM reasoning, Vexorbis Swarm uses specialized workers—code analysis, fault localization, formal verification, and autonomous Git management—to deliver faster, more reliable results.

---

Demo

https://vimeo.com/1158005784

✨ The Three Pillars

<table> <tr> <td width="33%" valign="top">

🧠 Algorithmic Core

Go beyond text search.

• HippoRAG: AST-based knowledge graphs with Personalized PageRank for deep code understanding.
• Ochiai SBFL: Find bugs statistically, not by guessing.
• Z3 Verifier: Formal verification for critical logic.

</td> <td width="33%" valign="top">

🤖 Autonomous Workforce

Let the agents handle the grunt work.

• Git Agent Roles: Specialized workers (Architect, Engineer, Auditor) that plan, commit, and create PRs.
• Dynamic Toolsmith: Vexorbis Swarm can design and register new tools at runtime.
• Markdown-Driven: Control the workforce from a PLAN.md file.

</td> <td width="33%" valign="top">

🛡️ Active Governance

Stay in control.

• Telemetry Memory: SQLite-backed persistence for session context and failure analysis.
• Self-Healing: Detects repeated failures and alerts agents to change strategy.
• Permission-First: Autonomous actions (like tool creation) require user approval.

</td> </tr> </table>

---

🚀 Quick Start

Docker (Recommended)

git clone https://github.com/AgentAgony/swarm.git
cd swarm
docker compose up -d --build

Configure Your IDE

Add the MCP server to your IDE's configuration (e.g., ~/.gemini/antigravity/mcp_config.json on Windows):

{
  "mcpServers": {
    "swarm-orchestrator": {
      "command": "docker",
      "args": ["exec", "-i", "swarm-mcp-server", "python", "server.py"]
    }
  }
}

---

🔍 Tool Selection Guide

flowchart LR
    Start([My Goal]) --> Q1{Type?}

    Q1 -->|Find symbol by name| A["search_codebase(keyword_only=true)<br/>~1ms"]
    Q1 -->|Find code by concept| B["search_codebase()<br/>~240ms"]
    Q1 -->|Understand architecture| C["retrieve_context()<br/>~1-2s"]
    Q1 -->|Debug failing tests| D["debug command<br/>Ochiai SBFL"]

    style A fill:#2ecc71,color:#fff
    style B fill:#3498db,color:#fff
    style C fill:#9b59b6,color:#fff
    style D fill:#e74c3c,color:#fff

---

🔄 Antigravity Sync

Vexorbis Swarm synchronizes with a human-readable PLAN.md file, enabling a true co-pilot workflow.

From Your Markdown:

## Todo
- [ ] Refactor auth module @architect
  - Context: auth.py
- [ ] Add login tests @engineer

Vexorbis Swarm interprets:

• [ ] → Task is PENDING. Agent picks it up.
• @architect → Assigns to the Architect worker.
• Context: → Pre-loads auth.py into the agent's window.

On completion:

• Agent marks the task [x] in your PLAN.md automatically.

---

📖 Documentation

Getting Started	Concepts	Guides	Reference
Introduction	Architecture	PLAN.md Syntax	Tools
Installation	Decision Logic	Git Workflows	Configuration
Quick Start	Three Pillars	Debugging	API Reference
		Custom Tools	Troubleshooting

---

📊 Implementation Status

Component	Status
HippoRAG (Multi-language AST)	✅ Stable
Hybrid Search Engine	✅ Stable
Ochiai SBFL	✅ Stable
Telemetry & Memory	✅ Stable
Git Agent Roles	🚧 Experimental
Z3 Verifier	⚠️ Partial
Structured Deliberation	🚧 Stub

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md.

Development Mode:

# Enable debug features
export SWARM_DEBUG=true
export SWARM_VERBOSE_TELEMETRY=true

---

📜 License

MIT License - See LICENSE for details.