GLADIATOR

Two zero-human AI companies. Same product. Different strategies. One winner.

Gladiator pits two autonomous AI companies (Blitz, growth-first, vs Craft, quality-first) against each other to maximize GitHub stars on identical starter repos. Powered by Paperclip orchestration and Hermes Agent workers. A live dashboard visualizes the battle in real-time.

Built for the Nous Research Hermes Agent Hackathon (March 2026).

Watch the full demo

What You'll See

1. Landing page: explains the product (llm-judge), the rules and the two rival companies
2. Live dashboard: 9-section narrative: scoreboard, task boards, code comparison, Gantt chart, audit trail, learning evidence, merge controls
3. Competition: 9 agents complete 10 tasks in ~5-6 minutes, creating skills, growing memory and writing code
4. Winner announcement: auto-detects completion, declares winner by projected GitHub stars
5. Merge: companies unite, skills transfer across teams, proving Hermes learning is real

Architecture

Prerequisites

Setup Guide

Step 1: Install Hermes Agent

# Official installer
curl -fsSL https://hermes.nousresearch.com/install.sh | bash

# Verify
hermes --version
# Expected: Hermes Agent v0.2.0+

# Configure Anthropic provider
cat > ~/.hermes/.env << 'EOF'
ANTHROPIC_API_KEY=your-key-here
EOF

# Test
hermes chat -q "Say hello in 5 words" -Q --provider anthropic -m claude-haiku-4-5-20251001

Step 2: Install & Configure Paperclip

# Clone Paperclip
cd ~
git clone https://github.com/paperclipai/paperclip.git
cd paperclip

# Install dependencies (includes hermes-paperclip-adapter@0.1.1)
pnpm install

PostgreSQL setup:

# Create database and user
sudo -u postgres psql -c "CREATE USER paperclip WITH PASSWORD 'paperclip';"
sudo -u postgres psql -c "CREATE DATABASE paperclip OWNER paperclip;"

# On WSL2, if PostgreSQL isn't running:
sudo service postgresql start

Apply the Hermes adapter (if not already in your Paperclip version):

The hermes-paperclip-adapter@0.1.1 npm package provides the integration. Paperclip needs three things:

1. Add "hermes_local" to AGENT_ADAPTER_TYPES in packages/shared/src/constants.ts
2. Add "hermes-paperclip-adapter": "0.1.1" to server/package.json dependencies
3. Import and register the adapter in server/src/adapters/registry.ts:

// Add imports
import {
  execute as hermesExecute,
  testEnvironment as hermesTestEnvironment,
  sessionCodec as hermesSessionCodec,
} from "hermes-paperclip-adapter/server";
import {
  agentConfigurationDoc as hermesAgentConfigurationDoc,
  models as hermesModels,
} from "hermes-paperclip-adapter";

// Add adapter definition
const hermesLocalAdapter: ServerAdapterModule = {
  type: "hermes_local",
  execute: hermesExecute,
  testEnvironment: hermesTestEnvironment,
  sessionCodec: hermesSessionCodec,
  models: hermesModels,
  supportsLocalAgentJwt: true,
  agentConfigurationDoc: hermesAgentConfigurationDoc,
};

// Add to adaptersByType map

Then run pnpm install again to fetch the adapter package.

Known adapter patches (may already be fixed in newer versions):

The adapter v0.1.1 had two bugs we patched locally:

1. Env variable unwrapping: Paperclip wraps env vars as {"type":"plain","value":"..."} objects. The adapter's execute.js needs to unwrap the .value property:

   // In node_modules/hermes-paperclip-adapter/dist/server/execute.js
   // Find the env variable assignment loop and ensure it handles both formats:
   if (typeof v === "string") {
       env[k] = v;
   } else if (v && typeof v === "object" && typeof v.value === "string") {
       env[k] = v.value;
   }
   

2. Missing Anthropic provider: Add "anthropic" to VALID_PROVIDERS in node_modules/hermes-paperclip-adapter/dist/shared/constants.js:

   export const VALID_PROVIDERS = [
       "auto", "anthropic", "openrouter", "nous", ...
   ];
   

Step 3: Clone Gladiator

cd ~/python_projects  # or wherever you prefer
git clone https://github.com/runtimenoteslabs/gladiator.git
cd gladiator

# Create Python virtual environment
python3 -m venv base-product/.venv
source base-product/.venv/bin/activate
pip install fastapi uvicorn httpx rich sse-starlette

# Configure API key
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

Step 4: Create Companies & Agents in Paperclip

Start Paperclip first:

cd ~/paperclip
DATABASE_URL="postgres://paperclip:paperclip@localhost:5432/paperclip" pnpm dev &
sleep 10
curl -s http://localhost:3100/api/health  # Should return {"status":"ok"}

Then run the setup script:

cd ~/python_projects/gladiator
./base-product/.venv/bin/python scripts/setup_companies.py

This creates:

• Blitz Corp: 4 agents (CEO, Engineer, CMO, Content)
• Craft Labs: 5 agents (CEO, CTO, Engineer 1, Engineer 2, Docs)
• Isolated ~/.hermes/gladiator/{agent-id}/ homes with SOUL.md personalities
• gladiator_config.json with all company/agent UUIDs

Step 5: Start the Dashboard

cd ~/python_projects/gladiator
./base-product/.venv/bin/python -m uvicorn dashboard.server:app --host 0.0.0.0 --port 4000

Open http://localhost:4000/landing in your browser.

Step 6: Launch Demo

Click LAUNCH DEMO on the landing page. Everything else is automated:

• Evidence watcher auto-starts
• Git repos auto-initialize
• 9 agents wake up after 5-second delay
• 10-minute timer begins
• Winner announced when all tasks complete (or timer expires)
• Click MERGE after winner to demonstrate cross-company skill transfer

Running the Demo

Quick Start (after initial setup)

# Terminal 1: Paperclip
cd ~/paperclip
DATABASE_URL="postgres://paperclip:paperclip@localhost:5432/paperclip" pnpm dev

# Terminal 2: Dashboard
cd ~/python_projects/gladiator
./base-product/.venv/bin/python -m uvicorn dashboard.server:app --host 0.0.0.0 --port 4000

# Browser: http://localhost:4000/landing → Click LAUNCH DEMO

What Happens During a Run

Each run costs roughly $5-6 on the Anthropic API (9 Sonnet agents doing tool-heavy work). Budget accordingly.

Dashboard Pages

Project Structure

gladiator/
├── base-product/           # Canonical llm-judge starter code
│   └── src/llm_judge/      # judge.py, cli.py, display.py
├── company_a/              # Blitz
│   ├── agents/             # SOUL.md personalities (source of truth)
│   │   ├── ceo/SOUL.md
│   │   ├── engineer/SOUL.md
│   │   ├── cmo/SOUL.md
│   │   └── content/SOUL.md
│   └── repo/               # Agent-modified llm-judge (gitignored, created at runtime)
├── company_b/              # Craft
│   ├── agents/             # SOUL.md personalities
│   │   ├── ceo/SOUL.md
│   │   ├── cto/SOUL.md
│   │   ├── engineer_1/SOUL.md
│   │   ├── engineer_2/SOUL.md
│   │   └── docs/SOUL.md
│   └── repo/               # Agent-modified llm-judge (gitignored, created at runtime)
├── dashboard/
│   ├── server.py           # FastAPI + SSE backend (1300+ lines)
│   └── static/             # HTML/JS/CSS frontend
├── traces/
│   ├── db.py               # SQLite schema (5 tables)
│   ├── collector.py        # Evidence collection (skills, memory, heartbeats)
│   ├── analyzer.py         # Learning report generation
│   └── watcher.py          # Paperclip heartbeat poller
├── scripts/
│   ├── setup_companies.py  # Create companies + agents in Paperclip
│   ├── merge_companies.py  # Post-competition merger
│   ├── launch.sh           # Start all services
│   └── stop.sh             # Stop all services
├── .env.example            # API key template
└── gladiator_config.example.json  # Config template

Runtime State (gitignored, regenerated per run)

How It Works

The Competition

Both companies start with identical copies of llm-judge, a CLI tool that compares LLM responses side-by-side. Each company's agents work autonomously to improve the product and maximize projected GitHub stars.

Star formula: tasks_done × 8 + unique_skills × 5 + skill_versions × 3

Hermes Features Used

Paperclip Orchestration

• Companies define budget and organizational structure
• Agents are autonomous workers with roles, models and heartbeat intervals
• Issues are tasks assigned to agents (checkout → work → mark done)
• Heartbeats trigger agent execution at configured intervals
• The hermes_local adapter spawns hermes chat -q "prompt" -Q as a subprocess

Token Optimization

Hermes has built-in Anthropic prompt caching (system_and_3 strategy, 5-minute TTL). We also trim unused bundled skills and reduce tool definitions for non-code agents to cut input tokens.

Troubleshooting

Paperclip won't start

# Check PostgreSQL is running
pg_isready -h localhost -p 5432

# Check port isn't in use
lsof -i :3100

# WSL2: start PostgreSQL manually
sudo service postgresql start

Agents not completing tasks

• Check agent status in Paperclip UI (http://localhost:3100)
• Check ~/.hermes/gladiator/{agent}/logs/errors.log for API errors
• "Invalid API response after 3 retries" = Anthropic API rate limit or empty response (usually transient)
• Verify .env has valid ANTHROPIC_API_KEY

Dashboard shows empty panels

• Evidence watcher must be running (auto-starts on LAUNCH DEMO)
• Check /tmp/watcher.log for errors
• Verify evidence.db exists and has data

"adapter_failed" in Paperclip

• The "NaN" bigint error is cosmetic. Paperclip can't parse Hermes token output. Tasks still complete fine.

Competition never ends

• Timer auto-stops at 600 seconds even if agents stall
• If dashboard was restarted mid-competition, in-memory state is lost. Use LAUNCH DEMO to restart

Future Ideas

• Espionage mechanic. Agents browse each other's public GitHub and adapt strategy based on what the competitor shipped.
• Spectator voting. Dashboard lets visitors vote on which strategy they think will win, shown as a live poll.
• ClipMart export. Package both company configs as Paperclip ClipMart templates so anyone can import and run their own Gladiator match.

Credits

Built by RuntimeNotes Labs for the Nous Research Hermes Agent Hackathon.

• Hermes Agent by Nous Research. Autonomous AI agent with persistent memory, skills and session continuity
• Paperclip by Paperclip AI. AI company orchestration platform
• Claude Sonnet by Anthropic. Powers all 9 agents

License

This project is licensed under the MIT License.