How it works
The orchestrator, Task Documents, and the plan-confirm-fan-out flow
How it works
Every Foxl Code account has one orchestrator - a per-user agent that turns a conversation into shipped pull requests. It decides whether to just reply, file a GitHub Issue, or plan and spawn coding agents, and it keeps an eye on the agents it spawns.
The orchestrator
The orchestrator is a single reasoning agent per user (not a fixed pipeline). When you chat - whether at code.foxl.ai or inside the Foxl app - it routes your message to one of a few actions:
- Reply - answer a question, no work needed.
- Clarify - ask you for a missing detail before planning.
- Plan - write a Task Document for multi-step work.
- Spawn - launch one or more coding agents to do the work.
It runs on a model you choose for replies (separate from the model your coding agents use), so you can keep orchestration cheap and let the heavy model do the coding.
Task Documents
A Task Document is the orchestrator's plan, written in markdown. Each top-level checkbox is one unit of work that maps to one pull request:
- The plan carries a title, the checkbox list, an execution status, and an estimated budget.
- Each checkbox can open a GitHub Issue and is tracked as a subtask.
- As agents land PRs, the orchestrator ticks the matching checkboxes.
A Task Document moves through draft -> awaiting_confirmation -> confirmed -> in_progress -> completed.
Confirm once, then fan out
Multi-PR work follows a deliberate gate so agents never spin up without your say-so:
- You describe the work.
- The orchestrator publishes the Task Document and an estimated budget, then waits.
- You confirm once.
- The orchestrator spawns a coding agent for every checkbox in a single step - they run concurrently, each on its own VM.
Single-PR requests skip the full plan - the orchestrator uses a lightweight confirmation and spawns one agent. The Task Document machinery is for work that fans out across multiple PRs or repos.
Watching the agents
Once agents are running, the orchestrator can inspect and steer them:
- Read an agent's screen - see exactly what its terminal is showing right now.
- Send input - type into a running agent's terminal.
- Resize - adjust the terminal dimensions.
- Poll active agents - list which agents are still running.
This is what lets one orchestrator coordinate several agents at once - checking on each and unblocking it as needed. To have it do this on a schedule without you in the chat, see the autonomous loop.