⚠️ DEPRECATED — This repository has been archived. All code has been migrated to the Zouroboros monorepo under packages/swarm/src/executor/. Please open issues and PRs there.

Zouroboros Swarm Executors

Turn any CLI tool into a first-class AI persona on Zo Computer. Each executor gets consistent identity, shared memory, and full swarm integration through a simple bash bridge script.

Part of the Zouroboros ecosystem — self-improving AI development tools for Zo Computer.

What This Is

This skill manages the local executors that power the zouroboros-swarm-orchestrator. Instead of routing every task through a remote API, the orchestrator can send work to CLI tools running on your machine:

• 4 Built-in Executors -- Claude Code, Hermes, Gemini, and Codex, each wrapped in a bridge script
• Shared Identity -- All executors read the same SOUL.md, IDENTITY files, and memory system as API personas
• Simple Interface -- A bridge script accepts a prompt on stdin and returns text on stdout. That's the whole contract
• Health Checks -- Doctor script validates all bridges, environment variables, and CLI tools
• Custom Executors -- Add your own CLI tool as an executor with a template bridge script and a registry entry

Available Executors

Quick Start

There are two ways to use executors: through the Zo chat window (natural language) or the terminal (direct commands).

Option 1: Natural Language via Zo Chat

You don't need to call bridge scripts directly. The swarm orchestrator routes tasks to executors automatically. Just describe what you need:

Run a security audit on my project using a swarm.
Use Claude Code for the code review and Hermes for the web research.

You can also call individual executors:

• "Ask Claude Code to review src/auth.ts for security issues"
• "Use Hermes to research the top 5 competitors to Acme Corp"
• "Have Codex generate a rate-limiting middleware for Express.js"
• "Ask Gemini to analyze this 500-page PDF"

Zo knows which bridge script to call and handles the invocation.

Option 2: Terminal (Direct Bridge Calls)

Call an executor directly

# Ask Claude Code to review a file
bash Skills/zo-swarm-executors/bridges/claude-code-bridge.sh \
  "Review src/auth.ts for security issues"

# Research with Hermes
bash Skills/zo-swarm-executors/bridges/hermes-bridge.sh \
  "Find the top 5 competitors to Acme Corp and summarize their pricing"

# Fast code generation with Codex
bash Skills/zo-swarm-executors/bridges/codex-bridge.sh \
  "Create a rate-limiting middleware for Express.js"

# Large-context analysis with Gemini
bash Skills/zo-swarm-executors/bridges/gemini-bridge.sh \
  "Summarize the key points from this 200-page document"

Check executor health

cd Skills/zo-swarm-executors
bun scripts/doctor.ts

Run integration tests

bun scripts/test-harness.ts

Using Executors with the Swarm Orchestrator

The orchestrator discovers executors through the registry file. When a task's persona matches a local executor, it routes the task to the bridge script instead of the API.

Example: Website review with mixed executors

Create a task file (tasks/site-review.json):

[
  {
    "id": "plan",
    "persona": "product-manager",
    "task": "Create a review plan for the e-commerce site at example.com"
  },
  {
    "id": "security",
    "persona": "claude-code",
    "task": "Audit the codebase for security vulnerabilities",
    "dependsOn": ["plan"]
  },
  {
    "id": "research",
    "persona": "hermes",
    "task": "Research competitor sites and compare features",
    "dependsOn": ["plan"]
  },
  {
    "id": "synthesis",
    "persona": "technical-writer",
    "task": "Combine all findings into a final report",
    "dependsOn": ["security", "research"]
  }
]

Run it:

cd Skills/zo-swarm-orchestrator/scripts
bun orchestrate-v4.ts ../tasks/site-review.json --swarm-id site-review

The product-manager and technical-writer tasks go to the API. The claude-code and hermes tasks run locally through bridge scripts. The orchestrator handles routing automatically.

Or via Zo chat:

Run the swarm task file at Skills/zo-swarm-orchestrator/tasks/site-review.json

Adding Your Own Executor

You can turn any CLI tool into a swarm executor in two steps.

Step 1: Create a bridge script

Use the template as a starting point:

cp Skills/zo-swarm-executors/bridges/template-bridge.sh \
   Skills/zo-swarm-executors/bridges/my-tool-bridge.sh
chmod +x Skills/zo-swarm-executors/bridges/my-tool-bridge.sh

Edit the script. The contract is simple: accept a prompt as $1, return text on stdout.

#!/usr/bin/env bash
set -euo pipefail

PROMPT="${1:?Usage: my-tool-bridge.sh \"prompt\" [workdir]}"
WORKDIR="${2:-/home/workspace}"
TIMEOUT="${MY_TOOL_TIMEOUT:-300}"

cd "$WORKDIR"
timeout "$TIMEOUT" my-tool --prompt "$PROMPT" 2>/dev/null

Step 2: Register in the executor registry

Add an entry to registry/executor-registry.json:

{
  "id": "my-tool",
  "name": "My Tool",
  "executor": "local",
  "bridge": "Skills/zo-swarm-executors/bridges/my-tool-bridge.sh",
  "expertise": ["my-domain"],
  "best_for": ["tasks my tool excels at"],
  "healthCheck": {
    "command": "command -v my-tool",
    "expectedPattern": "my-tool"
  }
}

Or via Zo chat:

Register a new executor called "My Tool" for the swarm.
The bridge script is at Skills/zo-swarm-executors/bridges/my-tool-bridge.sh.
It's good at my-domain tasks.

Environment Variables

Model Routing via OmniRoute

Powered by OmniRoute — a unified AI proxy/router for multi-provider LLM aggregation.

When used with the zouroboros-swarm-orchestrator (v4.7+), each bridge receives a SWARM_RESOLVED_MODEL env var that tells it which OmniRoute combo or model to use. The orchestrator picks this based on the task's complexity tier — trivial tasks get cheap models, complex tasks get powerful ones.

Fallback chain per bridge

Each bridge reads the model in this priority order:

The Gemini bridge has special handling: if the resolved model is an OmniRoute combo (contains swarm-), it skips it and falls back to the native Gemini model, since the Gemini CLI talks directly to Google's API rather than through OmniRoute.

Standalone usage

When calling bridges directly (without the orchestrator), SWARM_RESOLVED_MODEL won't be set and the bridge falls through to the executor-specific env var or CLI default. No behavior change for standalone use.

Repository Structure

zouroboros-swarm-executors/
├── SKILL.md                         # Skill manifest
├── README.md                        # This file
├── bridges/                         # Bridge scripts (the core interface)
│   ├── claude-code-bridge.sh
│   ├── hermes-bridge.sh
│   ├── gemini-bridge.sh
│   ├── codex-bridge.sh
│   └── template-bridge.sh          # Starting point for custom bridges
├── registry/
│   └── executor-registry.json      # Executor metadata (consumed by orchestrator)
├── scripts/                         # Management tools
│   ├── doctor.ts                   # Health checker for all executors
│   ├── test-harness.ts             # Integration tester
│   └── register.ts                 # Register new executors
├── types/                           # TypeScript interfaces
└── docs/
    └── BRIDGE_PROTOCOL.md          # Full protocol specification

How the Bridge Protocol Works

Every bridge script follows the same contract:

Input:  bash bridge.sh "prompt" [workdir]
Output: plain text on stdout
Errors: stderr + non-zero exit code

The bridge handles binary resolution, timeout enforcement, output cleanup, and environment setup. The orchestrator (or you) doesn't need to know how the CLI works internally. Just send a prompt, get text back.

Related Skills

• zouroboros-swarm-orchestrator -- The orchestrator that routes tasks to these executors
• zouroboros-memory-system -- Shared memory that all executors can read and write
• zouroboros-persona-creator -- Create personas that can be assigned to executors

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/my-improvement)
3. Commit your changes
4. Push to the branch (git push origin feature/my-improvement)
5. Open a Pull Request

License

MIT License -- Use freely, commercially or personally.