PowerSpawn - Universal Multi-Agent MCP Server

Version 1.4.2

Spawn Claude, Codex, AND Copilot from one coordinator. Your agents leave a paper trail.

A lightweight MCP server for cross-model AI agent orchestration. Works with Claude Code, GitHub Copilot, and any MCP-compatible client. Supports GPT, Claude, and Gemini models through multiple CLI providers.

Why PowerSpawn?

1. Uses Your Existing CLI Subscriptions

PowerSpawn spawns real CLI agents (Claude Code, GitHub Copilot, Codex) that you already have installed. No API keys to manage separately - just use your existing subscriptions.

2. Deterministic, Not Hopeful

The MCP server wraps sub-agents and handles all logging deterministically. We don't rely on agents "following instructions" to update files - the orchestrator captures inputs/outputs automatically.

3. Distribute Load Across Subscriptions

Hit Claude's rate limit? Spawn a Codex agent instead. PowerSpawn lets you balance work across multiple AI subscriptions, maximizing your throughput.

4. Full Oversight for User and Coordinator

CONTEXT.md - See which agents are currently running
IAC.md - Complete audit trail of all inputs and outputs (newest first, last 15 entries)

5. Persistent Memory Across Sessions

File-based state means sessions can resume even after:

Coordinator agent runs out of context window
Process restarts or crashes
Hours or days between work sessions

6. Parallel Work in the Same Project

Multiple agents can work on different tasks simultaneously. The file-based architecture prevents conflicts and provides clear separation.

7. Extend Your Context Window

Sub-agents do the heavy lifting — reading files, searching code, running tests — and return concise summaries instead of raw data. Your coordinator's context stays lean, enabling:

Longer sessions before hitting context limits
More complex tasks within model constraints
Better focus on orchestration, not file contents

Comparison with Other Frameworks

Feature	PowerSpawn	AutoGen	CrewAI	LangGraph
Cross-model spawning	Yes (Claude + Codex + Copilot)	No	No	No
Model diversity	GPT, Claude, Gemini	Limited	Limited	Limited
Uses existing CLI subscriptions	Yes	No	No	No
Deterministic logging	Yes	No	No	No
File-based persistence	Yes (IAC.md)	No	No	No
Context window optimization	Yes (summaries)	No	No	No
Zero infrastructure	Yes	Partial	Partial	No
MCP protocol native	Yes	No	No	No

The IAC.md Pattern (Novel)

Traditional multi-agent systems use in-memory message passing or databases. PowerSpawn uses markdown files as the communication channel:

┌─────────────────────────────────────────────────────────────────┐
│                    COORDINATOR (Claude/Copilot)                 │
│                    Reads IAC.md, writes tasks                   │
└───────────────────────────┬─────────────────────────────────────┘
                            │
                            ▼
              ┌─────────────────────────────┐
              │         IAC.md              │
              │  • Task assignments         │
              │  • Agent results            │
              │  • Human-readable log       │
              │  • Git-trackable            │
              └─────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        ▼                   ▼                   ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CODEX SUB-AGENT │ │ CLAUDE SUB-AGENT│ │COPILOT SUB-AGENT│
│ • GPT-5.1       │ │ • Claude models │ │ • GPT/Claude/   │
│ • Reads AGENTS  │ │ • Reads CLAUDE  │ │   Gemini models │
│ • Writes IAC.md │ │ • Writes IAC.md │ │ • Reads AGENTS  │
└─────────────────┘ └─────────────────┘ └─────────────────┘

Why this matters:

Auditable: Every agent interaction is logged in plain markdown
Debuggable: Read IAC.md to see exactly what happened
Persistent: Survives process restarts, session timeouts
Version-controllable: Git tracks your agent history

Novelty Research (December 2025)

We analyzed 900+ MCP repositories and major frameworks. Findings:

Claim	Verified	Evidence
IAC.md pattern is novel	Yes	No equivalent found in existing repos
Cross-model orchestration is rare	Yes	Only 19 repos mention Claude + Codex together
MCP for agent spawning is uncommon	Yes	Most MCP servers are for external tools

Closest competitor: claude-flow (1k stars) - but Claude-only, no cross-model support.

Installation

PowerSpawn is distributed as a git submodule - no package managers needed.

Add to your project

# Add as submodule
git submodule add https://github.com/CynaCons/PowerSpawn.git powerspawn

# Install Python dependencies
pip install mcp

Windows: Install PowerShell Core (required for Copilot shell commands)

Copilot CLI uses PowerShell Core (pwsh) for shell commands on Windows. Without it, file operations (Create, Edit, Read) work, but shell commands fail.

# Install via winget
winget install Microsoft.PowerShell

# Verify installation
pwsh --version  # Should show PowerShell 7.x

Note: After installation, restart your terminal for PATH changes to take effect.

Configure your MCP client

Claude Code (.mcp.json in project root):

{
  "mcpServers": {
    "agents": {
      "command": "python",
      "args": ["powerspawn/mcp_server.py"]
    }
  }
}

GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "powerspawn": {
      "command": "python",
      "args": ["powerspawn/mcp_server.py"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Update to latest version

git submodule update --remote powerspawn

Quick Start

With Claude Code

Once configured, these MCP tools are available:

mcp__agents__spawn_claude   - Spawn Claude sub-agent (haiku/sonnet/opus)
mcp__agents__spawn_codex    - Spawn Codex sub-agent (GPT-5.1)
mcp__agents__spawn_copilot  - Spawn Copilot sub-agent (GPT/Claude/Gemini)
mcp__agents__list           - List running/completed agents
mcp__agents__result         - Get agent result by ID
mcp__agents__wait_for_agents - Wait for all agents to complete

Example prompt:

"Can you powerspawn a Codex to run the test suite while you review the code?"

Standalone Python

from spawner import spawn_claude, spawn_codex, spawn_copilot

# Spawn Claude for code review
result = spawn_claude("Review src/App.tsx for security issues")

# Spawn Codex for testing (preserves Claude rate limit)
result = spawn_codex("Run npm test and report failures")

# Spawn Copilot with any model (GPT, Claude, or Gemini)
result = spawn_copilot("Analyze this codebase structure", model="gpt-5.1")
result = spawn_copilot("Write documentation", model="gemini")

Architecture

powerspawn/
├── mcp_server.py      # MCP server entry point (~500 lines)
├── spawner.py         # Core spawn logic for Claude/Codex
├── logger.py          # IAC.md logging with file locking
├── context_loader.py  # Example: future role-based context (not currently used)
├── parser.py          # Response parsing (JSON, JSONL)
├── __init__.py        # Package exports
├── requirements.txt   # Python dependencies (just 'mcp')
├── schemas/           # JSON output schemas
├── examples/          # Usage examples
├── site/              # Landing page (powerspawn.com)
├── README.md          # This file
├── MCP_DESIGN.md      # Detailed architecture docs
└── DESIGN.md          # Original design document

Auto-generated files (gitignored):

IAC.md - Inter-Agent Communication log
CONTEXT.md - Active agent status

Key Files

Context Files (Auto-loaded by CLIs)

PowerSpawn relies on the CLI tools' built-in context loading:

Agent	CLI	Auto-loads
Claude	`claude`	`CLAUDE.md` from project root
Codex	`codex`	`AGENTS.md` from project root
Copilot	`copilot`	`AGENTS.md` from project root

These files should contain:

Project structure overview
Key file locations
Current sprint/iteration goals
Role guidelines (do's and don'ts)

IAC.md - Inter-Agent Communication

The coordinator writes task assignments here. Agents read instructions and append results. Format:

## Task: Run Production Tests
**Assigned to:** Codex
**Status:** In Progress
**Timestamp:** 2025-12-01T20:30:00

### Instructions
Run `npm run test:production` and report any failures...

### Result
[Agent appends result here when complete]

AGENTS.md - Codex Agent Instructions

Auto-loaded by Codex CLI. Defines:

Available tools and restrictions
Output format expectations
Project conventions
Do's and don'ts

CONTEXT.md - Active Agents Status

Auto-generated by PowerSpawn. Shows currently running agents (resets on server restart).

MCP Tools Reference

spawn_claude

{
  "prompt": "Your task description",
  "model": "sonnet",        // haiku | sonnet | opus
  "timeout": 600            // seconds (default: 600)
}

spawn_codex

{
  "prompt": "Your task description"
}

spawn_copilot

{
  "prompt": "Your task description",
  "model": "gpt-5.1"  // gpt-5.1 | gpt-5 | gpt-5.1-codex | gpt-5-mini |
                       // claude-sonnet | claude-haiku | claude-opus | gemini
}

Available models:

Model	Provider	Description
`gpt-5.1`	OpenAI	GPT-5.1 (default)
`gpt-5`	OpenAI	GPT-5
`gpt-5.1-codex`	OpenAI	Optimized for code
`gpt-5-mini`	OpenAI	Fast, lightweight
`claude-sonnet`	Anthropic	Claude Sonnet 4.5
`claude-haiku`	Anthropic	Claude Haiku 4.5
`claude-opus`	Anthropic	Claude Opus 4.5
`gemini`	Google	Gemini 3 Pro Preview

list

Returns running and completed agent IDs.

result

{
  "agent_id": "abc123"
}

Returns the agent's output, cost, and status.

wait_for_agents

Blocks until all running agents complete. Returns all results.

Use Cases

1. Parallel Test + Review

Coordinator: "Spawn Codex to run tests while I review the PR"
→ Codex runs tests (doesn't consume Claude rate limit)
→ Claude reviews code
→ Both results collected

2. Research Task

Coordinator: "Powerspawn an Opus agent to research multi-agent patterns"
→ Opus agent does deep research with web search
→ Results written to IAC.md
→ Coordinator summarizes findings

3. Large Refactoring

Coordinator: "Spawn 4 agents to migrate different test file groups"
→ Agent 1: tests/editor/01-10
→ Agent 2: tests/editor/11-20
→ Agent 3: tests/editor/21-30
→ Agent 4: tests/editor/31-40
→ All run in parallel, results collected

Configuration

Environment variables:

ANTHROPIC_API_KEY - For Claude agents
OPENAI_API_KEY - For Codex agents

Agent defaults are in the MCP server. Override via tool parameters.

Deep Dive: Design Philosophy

For a comprehensive understanding of PowerSpawn's architecture and the reasoning behind our design decisions, read DESIGN.md.

Key highlights:

Why deterministic logging? Agents are 95% unreliable at self-reporting (Section 6.1)
Layered supervision model - User → Coordinator → Python → Sub-agents (Section 2.3)
The Determinism Principle - Everything that CAN be done deterministically SHOULD be (Section 2.1)
Agent capability matrix - When to use Claude vs Codex (Section 11)

Roadmap

Landing page at powerspawn.com
GitHub Copilot integration (spawn_copilot)
Support for Gemini models (via Copilot CLI)
MCP Registry submission
Unit and integration test suite

License

MIT - Use it, fork it, improve it.

Built with AI, for AI orchestration.

Part of the PowerTimeline project.

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
examples		examples
schemas		schemas
site		site
tests		tests
.gitignore		.gitignore
DESIGN.md		DESIGN.md
LICENSE		LICENSE
MCP_DESIGN.md		MCP_DESIGN.md
README.md		README.md
__init__.py		__init__.py
context_loader.py		context_loader.py
logger.py		logger.py
mcp_server.py		mcp_server.py
parser.py		parser.py
requirements.txt		requirements.txt
spawner.py		spawner.py

License

CynaCons/PowerSpawn

Folders and files

Latest commit

History

Repository files navigation

PowerSpawn - Universal Multi-Agent MCP Server

Why PowerSpawn?

1. Uses Your Existing CLI Subscriptions

2. Deterministic, Not Hopeful

3. Distribute Load Across Subscriptions

4. Full Oversight for User and Coordinator

5. Persistent Memory Across Sessions

6. Parallel Work in the Same Project

7. Extend Your Context Window

Comparison with Other Frameworks

The IAC.md Pattern (Novel)

Novelty Research (December 2025)

Installation

Add to your project

Windows: Install PowerShell Core (required for Copilot shell commands)

Configure your MCP client

Update to latest version

Quick Start

With Claude Code

Standalone Python

Architecture

Key Files

Context Files (Auto-loaded by CLIs)

IAC.md - Inter-Agent Communication

AGENTS.md - Codex Agent Instructions

CONTEXT.md - Active Agents Status

MCP Tools Reference

spawn_claude

spawn_codex

spawn_copilot

list

result

wait_for_agents

Use Cases

1. Parallel Test + Review

2. Research Task

3. Large Refactoring

Configuration

Deep Dive: Design Philosophy

Roadmap

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages