hermes-swarm/SKILL.md

name	description	version	author	license	platforms	metadata
hermes-swarm	Run a multi-agent discussion swarm using cheap models via Hermes CLI and Redis Pub/Sub.	1.0.0	Hermes Agent	MIT	linux macos windows	hermes tags related_skills swarm multi-agent delegation redis collaboration reasoning cheap-models subagent-driven-development writing-plans plan

hermes-swarm

Use this skill when you want several cheap models to discuss a problem and converge on a solution instead of paying for one expensive reasoning model.

When to use

• The task benefits from multiple perspectives (architect, critic, coder, tester).
• You have access to several small/cheap models via Hermes profiles.
• You want a reusable, self-hosted collaboration mechanism with no cloud orchestrator.
• You can run Redis locally or in Docker.

When NOT to use

• One strong model is cheaper than 3-4 small calls (always benchmark cost).
• The task is trivial or one-shot.
• You need real-time synchronous chat between agents — this is round-robin, not live chat.

What you get

┌─────────────────────────────────────────────┐
│           Redis Pub/Sub room                │
│        myproject:swarm:<random>               │
└──────────────┬──────────────────────────────┘
               │
   ┌───────────┼───────────┐
   ▼           ▼           ▼
swarm-      swarm-     swarm-
architect   critic     coder
   │           │           │
   └───────────┴───────────┘
               │
        [synthesizer]  →  final.md + transcript.md

Prerequisites

1. Hermes Agent installed and hermes in $PATH.
2. Redis running locally or reachable via REDIS_URL.
3. At least two Hermes profiles configured with different models/roles.

Quick start

1. Install Redis (Docker)

docker run -d --name redis-swarm \
  -p 6379:6379 \
  redis:7-alpine

Or use the included templates/docker-compose.redis.yml.

2. Create Hermes profiles

Add a block like this to ~/.hermes/config.yaml for each agent role:

profiles:
  swarm-architect:
    provider: openrouter  # or any provider you use
    model: google/gemma-3-12b-it:cheap
    system_prompt: |
      You are the architect in a multi-agent engineering discussion.
      Look at the big picture, propose structure and design trade-offs.      
  swarm-critic:
    provider: openrouter
    model: deepseek/deepseek-v3:free
    system_prompt: |
      You are the critic. Challenge assumptions, find flaws and risks.      
  swarm-coder:
    provider: openrouter
    model: qwen/qwen-2.5-coder-32b-instruct
    system_prompt: |
      You are the coder. Turn ideas into concrete, working code.      

Tip: keep these profiles cheap. The whole point is to replace one expensive call with several cheap ones.

3. Run the swarm

cd /path/to/hermes-swarm
python3 scripts/swarm_chat.py \
  --topic "Design a Python LRU cache for HTTP responses" \
  --agents swarm-architect swarm-critic swarm-coder \
  --rounds 3 \
  --room myproject:swarm:lru_cache

Output files land in ./swarm_outputs/ by default:

• <room>_final.md — synthesized answer
• <room>_transcript.md — full discussion

4. Tune environment variables

Variable	Default	Meaning
REDIS_URL	`redis://localhost:***@dataclass	SWARM_OUTPUT_DIR
HERMES_WORKDIR	current directory	Working dir passed to each Hermes agent
HERMES_CMD	hermes	Hermes CLI binary

Architecture

The dispatcher runs synchronously in rounds:

1. Seed the Redis room with the topic and agent list.
2. For each round, ask every agent to read the full history and reply.
3. After the last round, ask the first agent (synthesizer) to write the final answer.
4. Persist final answer and transcript to disk.

All messages are stored in a Redis sorted set (room:history), so agents can read the full context even if they are restarted.

Extending roles

Edit scripts/swarm_chat.py or pass custom role labels with --roles. Built-in roles:

• architect — structure and trade-offs
• critic — flaws, edge cases, risks
• coder — concrete code
• tester — tests and verification
• reviewer — clarity and completeness
• planner — actionable steps

Cost tips

• Start with --rounds 2 and 2-3 agents to measure token usage.
• Use the cheapest models that understand your domain.
• Compare cost vs. a single strong model on the same task.
• Set SWARM_OUTPUT_DIR to your project folder so outputs become project artifacts.

Files

hermes-swarm/
├── SKILL.md                      # this file
├── README.md                     # installation guide
├── scripts/
│   └── swarm_chat.py             # dispatcher
├── templates/
│   ├── docker-compose.redis.yml  # Redis setup
│   └── hermes-profiles.yaml      # example profile config
└── examples/
    ├── code-review.sh            # review a PR diff
    └── design-decision.sh        # compare two approaches