Container-isolated workspaces for parallel agent execution. Each agent gets its own Docker container with a full git clone on its own branch. No conflicts, independent tests, clean PRs.
Architecture (6 Layers)
- Work Source — Tasks from GitHub Issues (
gh api) or local SQLite queue - Orchestrator — Supervisor loop: discover -> claim -> route -> provision -> run -> verify -> land
- Router — Pure function: Task x Policy -> RunSpec (5-dimension complexity scoring)
- Identity Broker — Resolves named credentials to volume mounts + env overlays
- Workspace Manager — Per-task
git clone --reference, branch checkout, cleanup - Worker Runtime — Docker container create/start/stop/logs lifecycle
Task Lifecycle
DISCOVERED -> CLAIMED -> ROUTED -> PROVISIONED -> RUNNING -> VERIFYING -> LANDED
| |
v v
FAILED --> BLOCKED
|
v
CLAIMED (retry)
Prerequisites
- Docker or OrbStack installed and running
- At least one agent CLI available (Claude, Codex, or Kimi)
- CLI subscriptions configured (not API keys)
Check:
command -v docker &>/dev/null || command -v orbctl &>/dev/null
Configuration
All config lives in ~/.polyphony/:
| File | Purpose |
|---|---|
config.yaml |
Workspace root, poll interval, max concurrency |
identities.yaml |
Named credential bundles with volume paths |
agents.yaml |
Agent profiles (CLI commands, strengths) |
routing.yaml |
Routing rules and fallback chains |
Initialize with: polyphony init
Routing Rules
Rules are evaluated top-down; first match wins. Each rule has a match predicate and an agent target.
rules:
- match: { task_type: docs, risk: low }
agent: kimi
- match: { task_type: bugfix }
agent: codex
- match: { risk: high }
agent: claude
default:
agent: claude
fallback: [codex, kimi]
Complexity Scoring (5 Dimensions)
Each dimension scores 0-2. Total 0-10.
| Dimension | Source |
|---|---|
| Cyclomatic depth | LOC + scope size |
| Fan-out | Number of callers |
| Security boundary | Auth/PII keywords |
| Concurrency | Lock/transaction keywords |
| Domain invariants | Risk level + task type |
Routing thresholds:
- 0-3: Delegate to Kimi solo
- 4-6: Kimi + Codex review
- 7-10: Claude direct
Container Isolation
Each task gets:
- Its own Docker container from
polyphony-worker:latest - A full git clone at
/workspace(not a worktree) - Auth volumes mounted read-only (e.g.,
~/.claude:/home/worker/.claude:ro) - Independent test execution
- Its own branch for PRs
CLI Commands
polyphony init # Create ~/.polyphony/ with config templates
polyphony spawn "Fix auth bug" # Create and route a task
polyphony status # Show task states
polyphony cleanup # Remove completed workspaces
Integration with Existing Skills
- cross-agent-delegation: Uses Polyphony's complexity scoring for routing decisions
- agent-teams: Uses Polyphony's workspace isolation instead of shared directories
- spawn-team: Uses Polyphony's container provisioning for feature agents