psmux Agent Orchestrator

Orchestrate multiple sub-agents on Windows using psmux (tmux-compatible terminal multiplexer). Launch design, research, ML, eval, preview, and hooks-master agents in parallel psmux sessions/panes.

Windows only. On Linux/macOS, use native tmux instead.

Install

npm install -g psmux-agent-orchestrator

The postinstall script auto-detects installed agent harnesses and installs the skill. Or install manually:

# Install for specific harness
psmux-install --claude    # Claude Code
psmux-install --codex     # Codex
psmux-install --omp       # OhMyPi
psmux-install --omc       # OhMyClaude
psmux-install --agy       # agy CLI
psmux-install --cursor    # Cursor
psmux-install --all       # All detected

Pi agent package

pi install npm:psmux-agent-orchestrator

Quick Start

# List available sub-agents
psmux-orchestrator list-agents

# Show an agent spec
psmux-orchestrator show orchestrator
psmux-orchestrator show design

# Dispatch a task to a sub-agent in a psmux session
psmux-orchestrator dispatch "Build auth UI" --agent design

# Decompose and orchestrate across multiple agents
psmux-orchestrator orchestrate "Build a full-stack app with auth and dashboard"

Sub-Agent Roster

| Agent | File | Specialty | |-------|------|-----------| | orchestrator | agents/orchestrator.md | Decompose work, dispatch to psmux sessions, monitor, merge results | | design | agents/design.md | UI/UX design, DESIGN.md generation from brand references | | research | agents/research.md | Multi-source research across Reddit, X, YouTube, HN, GitHub | | ml-engineer | agents/ml-engineer.md | ML training, datasets, Hugging Face ecosystem, papers | | evaluator | agents/evaluator.md | LLM-as-a-judge scoring, heuristic/statistical evals | | preview | agents/preview.md | Native WebView preview windows via Glimpse | | hooks-master | agents/hooks-master.md | Claude Code hooks lifecycle, security validators, TTS |

Orchestration Flow

1. Orchestrator receives a complex request and decomposes it into sub-tasks
2. Each sub-task is dispatched to a specialized agent in its own psmux session/pane
3. The orchestrator monitors progress via psmux capture-pane and polls for completion
4. Results are collected, merged, and cleaned up

Parallel fanout

psmux new-session -d -s agent-a -- codex exec "Task A"
psmux new-session -d -s agent-b -- codex exec "Task B"
psmux new-session -d -s agent-c -- codex exec "Task C"

# Wait for all
while ($true) {
    $s = psmux list-sessions
    if (-not ($s -match "agent-")) { break }
    Start-Sleep -Seconds 5
}

# Collect results
$resultA = psmux capture-pane -p -S -200 -t agent-a
$resultB = psmux capture-pane -p -S -200 -t agent-b
$resultC = psmux capture-pane -p -S -200 -t agent-c

# Cleanup
psmux kill-session -t agent-a; psmux kill-session -t agent-b; psmux kill-session -t agent-c

Pipeline with handoff

# Stage 1: Research
psmux new-session -d -s stage-research -- codex exec "Research topic X"
sleep 30
$research = psmux capture-pane -p -S -200 -t stage-research
psmux kill-session -t stage-research

# Stage 2: Design (receives research)
psmux new-session -d -s stage-design -- codex exec "Design solution based on: $research"
sleep 20
$design = psmux capture-pane -p -S -200 -t stage-design
psmux kill-session -t stage-design

# Stage 3: Implement (receives design)
psmux new-session -d -s stage-implement -- codex exec "Implement: $design"
sleep 60
$result = psmux capture-pane -p -S -200 -t stage-implement
psmux kill-session -t stage-implement

Harness-Specific Differences

| Harness | Skill Dir | Agents Dir | Special Handling | |---------|-----------|------------|------------------| | Claude Code | .claude/skills/psmux-agent-orchestrator | agents/ | Writes .claude/agents/psmux-orchestrator.md for sub-agent routing | | Codex | .codex/skills/psmux-agent-orchestrator | agents/ | Reads agents/openai.yaml for UI metadata | | OhMyPi | .omp/skills/psmux-agent-orchestrator | agents/ | Uses pi.skills config in package.json | | OhMyClaude | .omc/skills/psmux-agent-orchestrator | agents/ | Writes OMC agent config for agent routing | | agy CLI | .agy/skills/psmux-agent-orchestrator | agents/ | Writes individual agent defs to .agy/agents/ | | Cursor | .cursor/skills/psmux-agent-orchestrator | agents/ | Writes .cursorrules reference |

Prerequisites

• Windows (psmux is Windows-only)
• psmux installed (winget install psmux or from github.com/psmux/psmux)
• Node.js >= 18 for the CLI tools
• One or more agent harnesses (Claude Code, Codex, etc.)

References

• psmux — tmux-compatible terminal multiplexer for Windows
• agency-agents — agent personality patterns
• awesome-design-md — DESIGN.md brand references
• last30days-skill — multi-source research engine
• ml-intern — autonomous ML agent
• autoevals — LLM evaluation library
• glimpse — native WebView for agents
• claude-code-hooks-mastery — hooks lifecycle

License

MIT