vamseeachanta Orchestrator Routing — Main Session as Lightweight Router
The main Codex session should stay responsive to the user. When a task is large or parallelisable, delegate to subagents rather than consuming the main context window. This skill documents the routing pattern.
Core Pattern
User message → Orchestrator (main session)
↓ (route)
Subagent A | Subagent B | Subagent C
↓ (results via TaskOutput / SendMessage)
Orchestrator summarises → User
The orchestrator:
- Classifies the task (size, parallelism, domain)
- Selects the right agent type(s)
- Spawns with
run_in_background=Truefor long tasks - Stays available for next user message
- Collects results and presents summary
When to Delegate
Delegate when ANY of these apply:
- Task will take > 5 minutes of sequential tool calls
- Task is clearly partitioned into 2-3 independent streams
- Task requires a read-only research phase that would pollute main context
- User sends a new message while task is still running (re-route remainder)
Keep in main session when:
- Task is < 5 files, < 10 min
- Task requires tight back-and-forth with user
- Task is a single WRK item with no parallelism
Routing Decision by Task Type
| User request | Route to | Agent type |
|---|---|---|
| "Search the codebase for X" | Explore agent | Explore |
| "Plan WRK-NNN implementation" | Plan agent | Plan |
| "Run tests / execute scripts" | Bash agent | Bash |
| "Build WRK-205 knowledge graph" | 2-3 agents via team | general-purpose + Bash |
| "Write a skill / WRK item" | Main session | — |
| "Ecosystem health check" | Background Bash agent | Bash |
| "Sync all repos" | Main session (sequential) | — |
Spawning a Background Agent
result = Task(
subagent_type="Bash",
description="Run ecosystem health checks",
prompt="""
Run the ecosystem health check suite per the /ecosystem-health skill:
1. Check git config core.hooksPath == .Codex/hooks
2. Check uv is available
3. Run .Codex/hooks/check-encoding.sh
4. Check work queue index generates
Report results as a markdown table.
""",
run_in_background=True
)
# result contains output_file path — check later with Read tool
After spawning, continue handling user messages. Check progress:
Read(file_path=result["output_file"])
# or
Bash(command=f"tail -20 {result['output_file']}")
Staying Responsive
When a background agent is running and the user sends a new message:
- Do not wait for the background agent to finish
- Handle the new message immediately
- Tell the user: "Background agent is working on X. Here's its progress so far: [summary]"
User: "While that's running, can you check WRK-205?"
Orchestrator: "Sure — background agent is still scanning 115 files.
Meanwhile, let me check WRK-205..."
[reads WRK-205, answers question]
[later] "Background agent finished: [results]"
Resuming Agents
Agents return an agent ID. Use it to resume rather than spawn fresh:
# First call — spawns fresh
result = Task(subagent_type="general-purpose", description="Research X", prompt="...", run_in_background=True)
agent_id = result["agent_id"]
# Resume later with more context
Task(subagent_type="general-purpose", description="Continue research", prompt="...", resume=agent_id)
Resume when: agent needs clarification, new information arrived, task was interrupted. Spawn fresh when: task is genuinely new, different domain, context is irrelevant.
Context Window Management
Long tasks consume context. Route to subagents to protect main context:
- Research tasks: Always delegate to Explore agent — search results pollute context
- Bulk file operations: Delegate to Bash agent — verbose output pollutes context
- Keep main session for: User dialogue, synthesis, routing decisions, WRK authoring
When main context is getting long:
- Delegate any remaining bulk work to background agents
- Use /reflect or /insights to compress learnings
- Summarise subagent results rather than including raw output
WRK Queue Integration
When user asks about pending work:
User: "What's pending? Pick the next thing to work on."
Orchestrator:
1. Read .Codex/work-queue/pending/ (fast, keep in main session)
2. Identify Route A items (user-approved, no cross-review needed)
3. If item needs research → spawn Explore agent, stay available
4. If item is small skill authoring → do in main session
5. If item is large (WRK-205 class) → propose team, await user approval
Related
/agent-teams— full team lifecycle (TeamCreate, TaskCreate, etc.)/ecosystem-health— example background agent pattern- AGENTS.md —
MAX_TEAMMATES=3constraint