🎼 Kilo Code Orchestrator Mode

The architecture

When you give Kilo a task with orchestrator mode on, three sub-agents activate in sequence (with feedback loops):

1. Planner reads the task + relevant repo context. Outputs a step-by-step plan with explicit success criteria. Default model: a strong reasoning model (Opus 4.7 or GPT-5.5).
2. Coder implements each plan step. Edits files, runs commands, creates new files. Default model: Sonnet 4.6 (fast, accurate, cheap-ish).
3. Debugger runs tests, lints, type checks. If something fails, it patches and re-iterates with the coder. Default model: Haiku 4.5 (fast, cheap, plenty for verification).

Each sub-agent's output becomes context for the next. The whole loop is visible in the trace pane.

When the orchestrator fires (and when it doesn't)

Kilo decides automatically based on task complexity heuristics:

• Fires for: multi-file changes, tasks containing 'refactor', 'add feature', 'fix bug + verify', explicit multi-step prompts ("first do X, then Y, then Z")
• Skips for: single-file edits under ~50 lines, pure chat questions, code-review requests (no editing), commands that contain 'just', 'quick', 'simple'

You can force orchestrator on/off per task: prefix with /orchestrate or /single.

Real run example: adding pagination

Prompt: "Add cursor pagination to the /api/users endpoint. Update the schema, the handler, and the OpenAPI spec. Make sure existing tests pass."

Planner output (Opus 4.7, ~$0.18): Decomposes into 4 steps — schema migration, handler update, OpenAPI spec edit, test verification. Identifies risk: backward compat for clients without cursor.

Coder execution (Sonnet 4.6, ~$0.42): Edits 3 files. Adds a default-cursor fallback for backward compat per the planner's flag.

Debugger run (Haiku 4.5, ~$0.04): Runs pytest — 2 failures. Patches the assertion in test_users.py to accept the new shape. Re-runs — green.

Total: $0.64, 4 minutes wall-clock. Same task with single-agent Sonnet: $0.31, 6 minutes, 1 missed edge case caught later in code review. Net win for orchestrator.

Real run example: when orchestrator hurts

Prompt: "Rename the variable userCount to activeUserCount across the project."

Orchestrator overhead here: planner spends $0.05 confirming what's obvious. Coder finishes the work. Debugger finds nothing to verify. Total cost: 1.4× a single-agent run, no quality benefit. Use /single for trivial tasks.

Reading the trace

Open the orchestrator trace pane (default keybind: Ctrl+Shift+O). Three columns show planner / coder / debugger streams in real time. Click any step to see the model used, tokens consumed, and the full prompt+response. Most useful for debugging unexpected outputs — usually you'll find the planner made a wrong assumption that propagated downstream.

Configuration

# ~/.kilo/config.toml
[orchestrator]
enabled = true
auto_decompose_threshold = 50  # lines edited
max_iterations = 4              # debugger ↔ coder loop cap
budget_usd = 2.50              # hard stop per task

[orchestrator.models]
planner = "anthropic/claude-opus-4-7"
coder    = "anthropic/claude-sonnet-4-6"
debugger = "anthropic/claude-haiku-4-5"

When to disable orchestrator

• You're paying close to the per-task budget cap and want predictable cost
• The task is genuinely simple (rename, single-line fix, add a docstring)
• Latency matters more than quality — orchestrator adds 30–90 seconds vs single-agent
• You're chatting/exploring rather than executing — orchestrator burns tokens it doesn't need to

Next

• Kilo vs Claude Code — orchestrator is the biggest architectural divergence
• Security — orchestrator runs sub-agents with the same permissions as parent; review before connecting to prod