hermes-swarm/SKILL.md

---
name: hermes-swarm
description: "Run a multi-agent discussion swarm using cheap models via Hermes CLI and Redis Pub/Sub."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [swarm, multi-agent, delegation, redis, collaboration, reasoning, cheap-models]
    related_skills: [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)

```bash
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:

```yaml
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

```bash
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` | `./swarm_outputs` | Where transcripts/final answers are saved |
| `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
```