Orchestrator

The orchestrator is the central coordination layer that decides what work to run and when. It uses a DAG-based scheduler to maximize parallelism while respecting task dependencies, and it routes ready tasks to the right agent type.

What the Orchestrator Does

• Watches the kanban board for tasks that are ready to run
• Resolves task dependencies and picks the optimal next set of tasks
• Spins up a task agent just-in-time for each ready task and assigns it the work
• Manages git worktrees for parallel agent execution
• Enforces quality gates between agent handoffs (e.g. QA must pass before Done)
• Self-heals: detects stuck or orphaned tasks and recovers automatically

Controlling the Orchestrator

The orchestrator runs inside the daemon. You don’t start it manually — you control it through the desktop app’s runner toggles:

• Per-project runner — In the Tasks view header, toggle the runner on or off for the active project
• Per-subproject runner — In the kanban chip row, toggle individual subprojects independently

When a runner is on, the orchestrator schedules ready tasks for that scope. When it’s off, no new agent work starts; anything in flight finishes cleanly.

You can leave one project’s runner on while pausing another.

To interrupt work that’s already running, use the Stop control in the Tasks view header. Stop aborts in-flight tasks and resets them back to Todo, so you can halt a run cleanly and re-trigger from a known state.

DAG-Based Task Management

The orchestrator uses a Directed Acyclic Graph (DAG) of task dependencies to:

• Determine execution order — Tasks run in dependency order
• Maximize parallelism — Independent tasks run simultaneously
• Handle complex chains — Multi-level dependencies are resolved automatically
• Prevent cycles — Invalid dependency configurations are rejected

The Graph mode of the Tasks view gives you a visual view of the dependency graph with live status as agents pick up nodes.

Managing Dependencies

You can manage dependencies through chat:

Add a dependency so task 3 must complete before task 7.

Make the login task depend on the database setup.

Remove the dependency between tasks 2 and 5.

Show me which tasks are ready to start.

Or edit them directly from the task detail dialog in the Tasks view.

Parallel Execution

Configure parallelism per project:

[orchestrator]
max_parallel_agents = 4   # Number of agents that can run simultaneously

Each parallel agent can work in its own isolated environment:

• Git worktrees — Separate working directories for each branch (recommended for any parallel work)
• Container sandboxes — Optional Podman containers for additional isolation

Generating Tasks

The simplest way to populate your board is to describe what you want in chat:

Build a REST API for user management with CRUD operations.

Break down user authentication into tasks and add them to the board.

The Product Manager agent analyzes the request, breaks it into tasks with sensible dependencies, and lands them in the Todo lane.

Watching Agent Activity

Open the Agent Workbench panel for a live view of what each agent is doing — which task it’s on, where it is in its behavior tree, and any output streaming back.

Execution History

Every task keeps a history of executions. Open a task from the Tasks view and switch to the Executions tab to see:

• When each execution started and finished
• Which agent ran it
• Tool calls made during the run
• Final outcome (passed, bounced, blocked)

Quality Gates & Bounces

The orchestrator enforces gates between agent handoffs:

1. Engineer → QA — When an engineer marks a task as ready for review, QA picks it up
2. QA → Done — If QA passes, the task moves to Done; if it fails, the task bounces back to In Progress for another engineering pass
3. Bounce limit — After repeated QA failures, the task escalates to Blocked for human review

This loop is what keeps the system honest — you don’t get half-finished work marked Done.

When you’ve addressed whatever caused a task to escalate, use the Reset retries / clear QA bounces affordance on the Blocked card to clear its bounce count and requeue it for another pass.

Self-Healing

The orchestrator includes built-in recovery mechanisms:

• Orphaned task detection — Identifies and recovers tasks left behind by crashed agents
• Stale execution cleanup — Removes hung executions
• Race condition prevention — Keeps task state consistent under parallel execution
• Crash recovery — Resumes from interruptions

You don’t need to configure self-healing — it runs automatically.

Configuration

Orchestrator settings in your config file:

[orchestrator]
max_parallel_agents = 1               # Number of parallel agents
use_worktrees = false                 # Enable git worktrees
worktrees_dir = ".worktrees"          # Worktrees directory
cleanup_worktrees_on_complete = false # Auto-cleanup completed worktrees

See Configuration for all options.