Multi-agent orchestration system using Claude Code's native background agents (2.0.64+) for true parallel collaboration. Enables shared context, sync barriers between phases, and coordinator oversight. Use for complex tasks benefiting from parallel execution (epics, large refactors, multi-phase features). Do NOT use for simple tasks or sequential workflows - the coordination overhead isn't justified.
Enables true parallel multi-agent orchestration using native Claude Code background agents for complex tasks like epics and large refactors. Triggers automatically for issues labeled "epic" or when manually started with `/popkit:power start` for tasks requiring multiple specialized agents working in parallel.
/plugin marketplace add jrc1883/popkit-claude/plugin install popkit-core@popkit-claudeThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Multi-agent orchestration using Claude Code's native background agents for true parallel collaboration.
Core principle: Agents work in parallel via run_in_background: true, share discoveries via file, and coordinate through sync barriers.
┌─────────────────────────────────────────────────────────────────┐
│ NATIVE ASYNC POWER MODE │
├─────────────────────────────────────────────────────────────────┤
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │
│ │background │ │background │ │background │ │
│ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘ │
│ └──────────────┼──────────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ Main Agent │ ← Coordinator (TaskOutput) │
│ │ (Polling) │ │
│ └───────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Requirements: Claude Code 2.0.64+ (no external dependencies) │
│ Setup: Zero config - just run /popkit:power start │
└─────────────────────────────────────────────────────────────────┘
| Feature | Free | Premium ($9/mo) | Pro ($29/mo) |
|---|---|---|---|
| Mode | File-based | Native Async | Native Async |
| Max Agents | 2 | 5 | 10 |
| Parallel Execution | Sequential | ✅ True parallel | ✅ True parallel |
| Sync Barriers | Basic | ✅ Phase-aware | ✅ Phase-aware |
| Insight Sharing | Basic | ✅ Full | ✅ Full |
| Redis Fallback | ❌ | ❌ | ✅ Optional |
Free tier users get file-based coordination:
.claude/popkit/insights.jsonPremium users unlock native async capabilities:
Task(run_in_background: true) APITaskOutput(block: false)Pro users get maximum capabilities:
Inspired by:
When to use:
When NOT to use:
Only if you want 10+ agent coordination:
# Configure Upstash environment variables
export UPSTASH_REDIS_REST_URL="https://your-instance.upstash.io"
export UPSTASH_REDIS_REST_TOKEN="your-token"
# Verify setup
/popkit:power init --verify
No Docker required - Upstash is cloud-based.
/popkit:power start "Build user authentication with tests and docs"
/popkit:dev work #45 -p
# Power Mode auto-enables for issues labeled "epic" or "power-mode"
/popkit:dev work #45
Power mode requires a clear objective with:
Objective:
description: "Build user authentication"
success_criteria:
- "Login endpoint works"
- "Tests pass"
- "Documentation updated"
phases: [explore, design, implement, test, document]
boundaries:
- file_patterns: ["src/auth/**", "tests/auth/**"]
- restricted_tools: []
The mode selector automatically chooses the best mode:
Native Async Mode:
Task(run_in_background: true)TaskOutput(block: false)Redis Mode (Legacy):
Each background agent:
.claude/popkit/insights.jsonAgents share discoveries via JSON file:
{
"insights": [
{
"agent": "code-explorer",
"content": "Found existing User model at src/models",
"tags": ["model", "database"],
"phase": "explore"
}
]
}
Between phases:
TaskOutput to completeWhen objective met:
.claude/popkit/power-state.jsonUses file-based communication:
| File | Purpose |
|---|---|
.claude/popkit/insights.json | Shared discoveries |
.claude/popkit/power-state.json | Session state |
Uses Redis pub/sub channels:
| Channel | Purpose |
|---|---|
pop:broadcast | Coordinator → All agents |
pop:agent:{id} | Direct messages to agent |
pop:heartbeat | Agent health check-ins |
pop:results | Completed work |
pop:insights | Shared discoveries |
pop:human | Human decision requests |
Automatic protections:
Human escalation triggers:
User: /popkit:power-mode "Build a REST API with user authentication"
[Coordinator starts, creates objective]
Phase 1: EXPLORE (parallel)
├── code-explorer → Analyzes existing codebase
├── researcher → Researches auth best practices
└── architect → Reviews project structure
[Insights shared via Redis]
explorer → "Found existing User model at src/models"
researcher → "JWT recommended for stateless auth"
architect → "Routes pattern: src/routes/{feature}/"
[SYNC BARRIER - wait for all]
Phase 2: DESIGN (coordinator routes insights)
└── code-architect → Designs auth system
(receives all Phase 1 insights automatically)
[SYNC BARRIER]
Phase 3: IMPLEMENT (parallel with check-ins)
├── rapid-prototyper → Implements endpoints
│ ├── Check-in 1: "Created login route"
│ ├── Check-in 2: "Added JWT generation"
│ └── Check-in 3: "Need: User model location"
│ ← Receives: "src/models/user.ts" from explorer
│
├── test-writer → Writes tests in parallel
│ └── Check-in: "Testing login endpoint"
│
└── docs-maintainer → Updates documentation
└── Check-in: "Documenting API endpoints"
[SYNC BARRIER]
Phase 4: REVIEW
└── code-reviewer → Reviews all changes
(receives aggregated results from all agents)
[Complete - results aggregated, patterns saved]
Edit power-mode/config.json:
{
"intervals": {
"checkin_every_n_tools": 5,
"heartbeat_seconds": 15
},
"limits": {
"max_parallel_agents": 6,
"max_runtime_minutes": 30
},
"guardrails": {
"protected_paths": [".env*", "**/secrets/**"],
"drift_detection": { "enabled": true }
}
}
# Use command (recommended)
/popkit:power stop
# Or clear state file
rm .claude/popkit/power-state.json
Claude Code version too old:
claude --versionBackground agents not spawning:
.claude/popkit/power-state.json for errorsInsights not sharing:
.claude/popkit/insights.json existsConnection failed:
python packages/popkit-core/power-mode/check_upstash.py --pingAgents not communicating:
/popkit:power statuspython packages/popkit-core/power-mode/upstash_adapter.py --testDrift alerts:
Works with:
Coordinator agent:
power-coordinator - Can be invoked as coordinatorRelated skills:
pop-subagent-dev - Single-session alternativepop-executing-plans - Parallel session alternative