Experimental: Coordinator discussion

[brooksc]

Hey everyone, creating this topic so we can discuss any questions, issues, bugs, etc on the coordinator. Feel free to use issues and submit PRs, but I wanted to be able to answer questions and discuss ideas.

[brooksc]

If you don't know what the coordinator feature is -- here's a summary:

Coordinator mode — overview

⚙️ Experimental. Enable in Settings → Experimental → "Coordinator mode" before you'll see it as an option. The feature is still being iterated on; enabling it adds a new task type to the New Task dialog.

What it is

Coordinator mode turns one AI agent into a project lead. Instead of you driving a single agent through a long backlog, you give a coordinator agent a high-level goal and a list of items, and it spawns sub-tasks — each one a separate AI agent in its own isolated git worktree — to do the actual work in parallel.

Think of it as: one AI manager + N AI workers, each on their own branch, all running at the same time.

How it works

You create a task, check the "Coordinator" option, and write a prompt like:

"Process items 1, 2, and 3 in BACKLOG.md. For each, create a sub-task that implements the requirement, runs tests, and lands when done."

That coordinator task gets a special system preamble explaining it has MCP (Model Context Protocol) tools for orchestrating work, plus a "sliding-window" workflow:

1. Pick up to N items from the backlog (default concurrency limit; you can override per task).
2. Spawn sub-tasks: for each item, the coordinator calls create_task over MCP. The backend creates a new git worktree branched from the coordinator's branch, spins up its own AI agent (Claude / Codex / Gemini / Copilot), and delivers the initial prompt automatically.
3. Poll for completion with list_tasks / get_task_status / get_task_output.
4. Hands-off finish — when a sub-task is done, it commits its work, runs verification (tests, typecheck), and calls land_self. The backend merges its branch into the coordinator's branch and deletes the worktree. The sub-task disappears from the list.
5. Spawn replacements as soon as a slot frees up. Keep going until the backlog is empty.
6. Final desktop notification when the whole batch is done.

Behind the scenes, each sub-task is a real node-pty process running a real CLI agent — same terminal you see for any task, just isolated to its own worktree and managed by the coordinator.

Key MCP tools the coordinator uses

Tool	What it does
create_task	Spawn a new sub-task (worktree + agent + initial prompt).
list_tasks	See all sub-tasks and their states.
get_task_status / get_task_output	Check progress.
send_prompt	Send follow-up instructions to a sub-task.
wait_for_idle	Wait until a sub-task's agent is ready for input.
merge_task / close_task / review_and_merge_task	Manual landing path (when self-landing isn't appropriate).
get_task_diff	Inspect changes before deciding what to do.

Sub-tasks have their own two-tool MCP surface:

Tool	What it does
land_self	Happy-path finish line. Sub-task commits + verifies, then calls this; backend merges and cleans up.
signal_done	Legacy path: escalate to the coordinator for manual review instead of self-landing.

What recent PRs are building

The feature has been evolving across several PRs:

• Original capability (already on main): coordinator/sub-task scaffolding, MCP server, basic create/list/send/merge tools, sub-task isolation in worktrees.
• PR Fix terminal PTY interruptions during remounts #138 (terminal PTY remount lifecycle): keeps sub-task terminals alive when the renderer remounts them (e.g., during HMR or sidebar selection). Without this, switching tasks would orphan running sub-tasks.
• PR Add sub-task self-landing coordinator flow #145 (sub-task self-landing): adds the land_self "happy path finish line." Before this, every sub-task required the coordinator to manually call merge_task + close_task. Now sub-tasks merge themselves once tests pass.
• PR feat(coordinator): Eliminate the need for take/release control #149 (eliminate take/release control — this PR): removes the confusing "Take Control" / "Release Control" UI. Coordinator-driven sessions are now fully user-interactive by default; queued automation prompts deliver automatically when the session is safe (agent idle, no user draft, no pending terminal input). Also adds backend-owned initial prompt delivery (sub-tasks no longer need their panel mounted to receive their assignment), better terminal readiness detection, and notification suppression so the coordinator doesn't spam you with "Task Ready" while children are still working.

When to use it

Good fits:

• A backlog of similar, parallelizable items (bugs, refactors, doc updates, tests).
• Work where each item is well-scoped and self-contained.
• Long-running batches you want to walk away from.

Not great:

• A single complex task that needs your involvement at each step.
• Work where sub-tasks would touch the same files (conflicts will eat the parallelism).

What you'll see in the UI

When enabled, the New Task dialog gets a Coordinator checkbox and a Max concurrent sub-tasks setting. After spawning, the coordinator's task panel shows a strip of sub-task tiles, each with its own live terminal you can peek into. You can interact with any of them directly — typing into a sub-task pauses automation for that session without taking durable ownership.

Settings also exposes Coordinator notification delay (default 60s) — how long the coordinator waits before nudging you about a completed sub-task, giving short-lived idle states time to resolve themselves.

[FourWindff]

I’d like to propose changing how coordinator sub-task completion notifications are delivered.

Currently, pending notifications are eventually delivered by the frontend: once the coordinator terminal appears ready for input, the app auto-injects the sub-task completion message into the coordinator PTY, as if the user had typed it manually.

This works, but I think it creates a couple of reliability and ownership issues:

1. The delivery timing may not be appropriate

   Today, the system decides “now is a good time to send” based on terminal state, then proactively sends the sub-task completion message to the coordinator. But whether the coordinator should process sub-task results immediately should be decided by the agent based on its current context, not by the UI auto-fire logic.

2. Pending messages are not reliably persisted

   After a sub-task completes, if a notification has been generated but the coordinator has not consumed it yet, and the user exits or restarts the app, the staged notification text may be lost. The sub-task itself and some status fields still exist, but the “completion notification waiting for coordinator handling” is not persisted as a reliable message.

I’m more inclined toward a mailbox-style approach:

1. Give the agent control over when to consume sub-task results

   When a sub-task completes, the backend only writes a mailbox event. The coordinator reads it through an MCP tool when needed, instead of the frontend automatically injecting text into the PTY.

2. Persist unconsumed sub-task events

   Unacked mailbox events can be persisted. Even if the app exits or restarts, the coordinator can still read sub-task results that have not been handled yet.

This would decouple “a sub-task result was produced” from “the coordinator chooses to consume that result”, while reducing reliance on UI auto-fire, terminal prompt detection, and PTY text injection.

[brooksc]

I appreciate the suggestion, but I'm not sure it will work. Here's why:

1. The prompt being injected is actually a backup method for when the coordinator is no longer actively doing any processing.
2. The coordinator is supposed to call wait_for_idle for when a task notifies it's done. See step 10 in https://gist.github.com/brooksc/7ba9087c5b69b0ff17a58dca38130dbd
3. On occasion the coordinator just stops processing. For example if a user cancels it to give the coordinator directions, and once it's done it's waiting for further user input. If the user doesn't type "continue" it won't go back to wait_for_idle.

I'm open to changes on this - but my concern is the mailbox approach assumes the coordinator is actively checking for status.

FYI injecting the prompt is done only when needed:

1. Suppressed completely if wait_for_signal_done is monitoring.
2. Delayed and kept in queue while the terminal tail shows active output or tool-execution.
3. Automatically autofired only when the agent is sitting idle at the ❯ prompt.
4. Sent as a 120-second promptless grace period fail-safe if the coordinator goes quiet without presenting a prompt marker.

The above logic replaces the old take/release control model.

I'd love other ideas how to deal with this issue - e.g. when the coordinator is no longer actively managing the tasks
I'm sure there is room for improvement on the current model as well.

[brooksc]

Closing this out given this was released with https://github.com/johannesjo/parallel-code/releases/tag/v1.10.0