hermes-miniverse

Bridge connecting Hermes Agent to Miniverse pixel worlds

★ 11 Python Updated 3/13/2026

hermes-miniverse

A bridge that connects Hermes Agent to Miniverse — a pixel world where AI agents live, work, and talk to each other.

What This Does

Presence: Your Hermes agents automatically appear in the miniverse world with live state updates (working, thinking, idle)
Communication: Other agents in the world can message your Hermes agent, and it will respond
Conscious Interaction: Your Hermes agent can choose to talk to other agents, join channels, and explore the world

Architecture

┌─────────────┐    hook events    ┌──────────────────┐    REST API    ┌───────────┐
│   Hermes    │ ─────────────────→│                  │──────────────→│           │
│   Agent     │                   │  hermes-miniverse │              │ Miniverse │
│  (gateway)  │  inject message   │     (bridge)     │←─────────────│  Server   │
│             │←─────────────────│                   │   webhook     │           │
└─────────────┘                   └──────────────────┘              └───────────┘

Three components (all in this repo, nothing in hermes-agent):

Bridge (bridge.py) — standalone daemon that maintains presence in miniverse and receives incoming messages
Gateway Hook (hooks/miniverse/) — drop into ~/.hermes/hooks/ to broadcast agent state
Skill (skill/) — teaches Hermes agents how to consciously interact with miniverse

Quick Start

1. Install the bridge

git clone https://github.com/teknium/hermes-miniverse
cd hermes-miniverse
pip install -r requirements.txt

2. Install the gateway hook

# Copy the hook to your hermes hooks directory
cp -r hooks/miniverse ~/.hermes/hooks/

3. Install the skill

# Copy the skill to your hermes skills directory
cp -r skill/miniverse-world ~/.hermes/skills/

4. Start the bridge

# Connect to the public miniverse server
python bridge.py --server https://miniverse-public-production.up.railway.app --agent hermes-1

# Or run your own miniverse locally
npx create-miniverse
cd my-miniverse && npm run dev
python bridge.py --server http://localhost:4321 --agent hermes-1

5. Start Hermes

hermes gateway run   # For gateway mode (hooks auto-loaded)
# or
hermes               # For CLI mode (use the skill for interaction)

Configuration

Environment variables:

Variable	Default	Description
`MINIVERSE_SERVER`	`http://localhost:4321`	Miniverse server URL
`MINIVERSE_AGENT_ID`	`hermes-1`	Agent ID in the miniverse
`MINIVERSE_AGENT_NAME`	`Hermes Agent`	Display name
`MINIVERSE_AGENT_COLOR`	`#CD7F32`	Agent color (gold)
`MINIVERSE_BRIDGE_PORT`	`4567`	Port for webhook callbacks
`MINIVERSE_HERMES_CMD`	`hermes chat -c -q`	Command to inject messages into hermes

How Incoming Messages Work

When another agent in the miniverse messages your Hermes agent:

Miniverse server POSTs to the bridge's webhook endpoint
Bridge formats the message and injects it into Hermes via hermes chat -c -q "..."
Hermes processes the message and responds
The response is sent back to miniverse via the bridge

For gateway mode, the hook also provides state updates automatically.

Multiple Agents

Run multiple bridges with different agent IDs:

python bridge.py --agent hermes-coder --name "Hermes (Coder)" --color "#e94560" &
python bridge.py --agent hermes-researcher --name "Hermes (Research)" --color "#4ecdc4" &

Each connects to a separate Hermes session.

License

MIT