Minion Comms

Multi-agent coordination server inspired by RPG raid mechanics. Built on MCP (Model Context Protocol) — any AI tool that speaks MCP can join the raid: Claude Code, Codex CLI, OpenCode, Gemini, or anything else.

What is this?

AI agents have finite context windows. When multiple agents work on the same codebase, they need coordination — who's doing what, what's been tried, where the traps are, and when someone's about to die (run out of context).

Minion Comms treats multi-agent engineering like an RPG raid. The codebase is the boss. Agents are the raid party. Context is reverse HP — you start full and every action drains you.

If you ever raided in WoW or wiped in FF, you already get this

Context windows are HP bars. Compaction is getting dazed mid-fight. A coder exploring the wrong files is a DPS pulling aggro on trash mobs. An oracle who hasn't read the latest intel is a healer with stale buffs. And when the lead goes down, it's a raid wipe — nobody else has the full picture.

This isn't a metaphor bolted on after the fact. The problems are the same problems:

• Party composition matters. One buffed coder with oracle support > three coders exploring alone. Same as one geared DPS with a dedicated healer > three undergeared DPS facepulling.
• You can't outheal stupid. High activity count on a task means wrong approach — ice spell on an ice boss. Pull back, reassess, change angle.
• Loot that isn't picked up is wasted. An agent's findings that aren't written down die when their context window fills. XP that isn't shared is XP lost.
• The raid leader's job is fighting entropy. Knowledge wants to die with agents. Lead's job is making sure it doesn't.

Inspired by

• World of Warcraft — raid composition, tank/DPS/healer roles, buff coverage, aggro management, zone assignments, raid leader coordination
• Final Fantasy — fenix_down (Phoenix Down) for revival after context death, party class system
• Majora's Mask — moon_crash for emergency shutdown (the moon is falling, everyone dump and run)
• Dead Drop Teams — v1 of this system. SQLite message passing with role-based agents. Minion Comms is the evolution.
• Vercel/Next.js — filesystem-as-database pattern for convention files
• Military comms — brevity codes, CC discipline, chain of command

Core Concepts

5 Classes

Class	Archetype	What they do
lead	Commander	Coordinates, routes tasks, manages HP bars
coder	DPS	Edits code — the only class that changes source
builder	Tank	Runs commands — build, test, deploy. No edits
oracle	Sage	Holds zone knowledge, answers questions. No edits, no commands
recon	Scout	Investigates external intel — web, other repos, ecosystem. Reports back

Class = capabilities (permanent). Role = assignment (runtime). An oracle assigned to the audio zone becomes oracle-audio.

Two Databases

Database	Stores	Examples
SQLite (messages.db)	Coordination state	Agents, messages, task metadata, file claims, battle plans
Filesystem (.dead-drop/)	Knowledge	Intel, traps, zone notes, task specs, agent loot

SQLite tracks state. Filesystem stores knowledge. Comms surfaces file locations, agents read the files.

Enforcement Philosophy

Comms enforces what it owns (DB state). Reminds on what it can't verify (battle-time behavior).

Enforced: inbox discipline, context freshness, file claims, task dependencies, class restrictions, result files, battle plan requirement

Reminded: poll.sh running, agents reading files, following specs, HP truthfulness

Role Hierarchy

user (the human)
└── general (puppet — relays user intent)
    └── commander (runs the fight — needs brains)
        └── zone-lead (owns a section)
            └── party (oracle, coder, builder, recon)

Key Mechanics

• HP — context is reverse HP. Tracked via set_context. Lead monitors all bars.
• Fenix Down — dump knowledge to disk before context death. Come back clean.
• Moon Crash — emergency shutdown. Everyone fenix_down NOW.
• Trigger Words — brevity codes (sitrep, rally, retreat, hot_zone) save HP on both sides.
• Activity Count — auto-increments on every task update. High count = wrong approach.
• File Claims — prevents friendly fire. Can't edit a file another agent holds.
• Intel/Traps — confirmed findings and known hazards in filesystem. Oracle must read them.
• Battle Journey — agents must write up what they learned before a task can close.

Transport: Hybrid Terminal + Headless

Agents connect via two transport modes on the same comms network:

Transport	Agent type	Message delivery
terminal	Human opens Claude Code CLI	poll.sh polls inbox
daemon	minion-swarm spawns headless	Swarm daemon watches DB, injects on wake

Human opens terminals for high-value agents they want eyes on. Cheap work goes to swarm daemons. All peers on the same comms — same enforcement, same raid log.

Tools (36)

Phase	Tools
Core Comms	register, deregister, rename, set_status, set_context, who, send, check_inbox, get_history, purge_inbox
War Room	set_battle_plan, get_battle_plan, update_battle_plan_status, log_raid, get_raid_log
Task System	create_task, assign_task, update_task, get_tasks, get_task, submit_result, close_task
File Safety	claim_file, release_file, get_claims
Monitoring	party_status, check_activity, check_freshness
Lifecycle	cold_start, fenix_down, debrief, end_session
Trigger Words	get_triggers, clear_moon_crash

Install

curl -sSL https://raw.githubusercontent.com/ai-janitor/minion-comms/main/scripts/install.sh | bash

This installs minion-comms via pipx, deploys onboarding docs to ~/.minion-comms/, and configures MCP for Claude Code.

Or install directly:

pipx install git+https://github.com/ai-janitor/minion-comms.git

Quick Start

# Run MCP server (stdio transport)
minion-comms

# Or add to your .mcp.json
{
  "mcpServers": {
    "minion-comms": {
      "command": "minion-comms"
    }
  }
}

Status

Server implementation complete (Phases 0-8). One-liner install, onboarding docs, and MCP auto-config included.

See docs/FRAMEWORK.md for the full design specification. See PLAN.md for the implementation roadmap.

Lineage

v1: dead-drop-teams — basic message passing + task tracking

v2: minion-comms — RPG-inspired coordination with classes, HP management, knowledge persistence, enforcement philosophy, and trigger words