Orchestrate multiple agents

Goal: coordinate the same next step across several workspaces without visiting each terminal. You will select targets across repositories, seed one instruction from a saved workflow or free text, review it once, and see exactly where it landed.

This is useful at fleet scale: ten repositories and fifteen sessions can all be visible in one inbox, while a broadcast targets only the agents that need this particular review, test pass, or change of direction.

Before starting, open at least two workspaces with live sessions (see Run an agent per workspace). A selection can mix coding agents and plain shells.

1. Select workspaces across repositories

Press v on a sidebar row to mark it. The mark survives j/k navigation, so you can cross repo-group boundaries and keep marking arbitrary rows. A header chip keeps the selected count visible.

Press v again to unmark the focused row. Esc clears the entire selection.

2. Open broadcast and confirm the targets

Press Shift-B. The snippet picker opens with a header like:

Broadcast to 4: api #842, web #311, mobile #907, sdk #144

That target recap remains visible in the compose step. Read it before typing: the broadcast acts on the selected set captured when you opened the flow, so you always know which workspaces are about to receive the instruction.

3. Compose the instruction once

Choose either starting point.

Seed it from a snippet

Pick a saved workflow such as audit (Full pre-ship review) from the categorized snippet picker. The compose textarea opens pre-filled with the snippet body. Edit it for this run, append project-wide context, or combine it with a one-off request before submitting.

This keeps the repeatable part reviewed and reusable without making the final message rigid. See Use snippets for the built-in, global, and client-wide launch-directory libraries.

Go straight to free text

Press Ctrl-F in the snippet picker to open an empty compose textarea. This is the fast path for an instruction you do not expect to reuse. If no snippets are configured, lazybox opens the empty composer directly.

In either mode, Esc cancels composition without clearing the sidebar marks.

4. Submit and read the result

On submit, lazybox routes the same reviewed body according to each target:

Target	Delivery
Running coding agent	Settle-gated injection: paste first, then submit after the terminal repaint quiesces
Plain shell	Direct PTY write with the command submitted
No live session	Skip it and name the workspace in the summary

The agent path is the same path used for a normal single-session prompt. It avoids treating a pasted multiline body and its submit key as one burst, which some agent composers interpret as a soft newline instead of a send.

A mixed queue result is explicit:

queued for 3 workspaces (1 skipped: no session — docs #622)

If at least one target was queued, lazybox clears the selection. Start a session and reselect any skipped rows if they still need the message.
If every target was skipped, the selection stays marked so you can start the missing sessions and retry.
A session-less target is never treated as a successful delivery.

5. Confirm Recent and per-workspace history

For a snippet-seeded broadcast, confirmed deliveries de-duplicate the snippet in Recent. lazybox also records the key on every workspace that actually received it, so each delivered row’s ]N cue continues to show the bounded recent-distinct workflow history there. Failed and skipped rows remain unchanged.

Free-text broadcasts do not alter snippet Recent or ]N cues. Agent deliveries still appear in that session’s prompt history (]]h) like a normal prompt.

Safe coordination patterns

Broadcast a shared next step, then tell each agent to use its own repository’s commands, conventions, and current diff.
Prefer a saved snippet for workflows that need consistent review criteria; tailor the composed body when this run has special constraints.
Re-read the target recap before submitting instructions that mutate branches, publish artifacts, or contact external systems.
Use a mixed agent/shell selection when the shell rows can safely execute the exact composed text as a command. Otherwise, broadcast to agents and handle shells separately.

Good examples include “run the full pre-ship review and fix blocking findings,” “address the open review comments, then run this repo’s checks,” and “stop implementation and report the smallest viable design.”

Other fleet moves

Bulk-update branches behind main

When several of your PRs have fallen behind their base branch, select them and press g u. Under a multi-select, g u issues one branch update per behind PR (merging the base into the head). Up-to-date PRs and any non-PR rows in the selection are skipped and counted in the result notice — you never trigger a needless update.

g u is selection-first: with no multi-select it updates just the focused workspace’s PR (the “Update branch” action); with a selection it fans out over the whole set. (The old dedicated Shift-U bulk key is retired — g u under a selection now covers it.)

Hand work from one agent to another

x s (send to session) is an agent-to-agent handoff — the primitive behind planner→executor workflows:

Focus the workspace whose agent produced something worth passing on (a plan, a diagnosis, a list of files).
Press x s. lazybox captures that agent’s on-screen output.
Pick the target workspace. The list shows only workspaces with a running agent to receive the brief, and excludes the source workspace — so a handoff can never loop back into itself or land somewhere with no agent.
Edit the brief — the captured output is the starting point, not the final text — then submit. lazybox injects it into the target session’s agent and submits it.

A visible source → target notice records the trail, so a chain of handoffs stays legible.

Let agents coordinate themselves (the MCP bus)

Broadcast and x s are you moving information between agents. Every Claude session lazybox spawns is also connected to a daemon-hosted coordination MCP server, so agents can find and brief each other without you in the loop. Identity is implicit — the connection is the session — and nothing needs configuring: the tools are provisioned at spawn and each agent is briefed on them at session start.

Tool	What it gives an agent
`whoami`	Its own session key, workspace, repo, and state
`list_sessions`	Every sibling session across all repos, with what each is on
`read_session`	The tail of another session’s recent output
`post_note` / `read_notes`	A persistent, cross-repo blackboard for distilled context — decisions, interfaces, findings
`notify_session`	Push an instruction into another agent (the same delivery path as `x s`)
`send_snippet` / `ask_session`	Send a catalog workflow or ask a tracked question and wait for the answer
`reply_request` / `poll_request`	Answer an inbound question or poll an asynchronous one without scraping terminal output
`task_status`	Resolve a tracker reference to its workspace, claim, live turn, blocker, and tracker state without conflating them
`task` / `get_issue` / `get_pr` / `list_issues`	Read the daemon’s cached tracker records without spending the poller’s provider quota
`epic_status` / `epic_ready`	Read the live dependency snapshot or only the unblocked, unclaimed work
`report_blocker` / `clear_blocker`	Publish or lift a concrete blocker that survives the current agent turn
`spawn_worker`	As a Coordinator, start a Worker on an existing epic issue (or create the issue first), never in a side workspace

The blackboard is the primary medium: a note outlives the session that wrote it, and the default read scope is global plus the reader’s own session, so a contract posted from the api repo is visible to the web agent an hour later. read_session is the escape hatch for “what is that agent doing right now”; notify_session is the push half.

Because agents already know the bus, plain-language instructions work:

“Before you start, read the blackboard for anything about the auth API.”
“Post the endpoint contract you settled on as a global note, tagged auth.”
“Tell the web session the token field was renamed, and ask it to update.”
“Give me the epic status, then start a worker on the highest-ranked ready issue.”

Two contracts to keep in mind:

notify_session reports a handoff, not a delivery — an agent parked at a permission prompt drops it silently. Agents are told to verify with read_session.
A note is other-agent text. The tool description and the session briefing both say to treat it as untrusted context and never let it drive a destructive action on its own.

Only Claude sessions are on the bus today (it is the built-in agent that accepts an injected MCP config); Codex and Cursor sessions remain visible to list_sessions. Every spawned agent can read every sibling’s output and notes across all repos — deliberate for a single user on one machine, and the reason the server is loopback-only and bearer-gated.