--- title: Orchestration description: Have one agent fan work out into several sessions, review its work with a second model, and pass messages between parent and child sessions. sidebar: order: 3 --- Orchestration is one agent starting other sessions with `dray`. You ask the agent in one session to "work through these four issues", and it starts four sessions, one per issue, each with its own worktree, branch and sidebar row. You watch them beside the conversation that started them. Use it for work that is truly separate: separate branches, separate pull requests. Steps of one task belong in one session. ## Before you start Install `dray` and its skill. See [Install](/docs/cli#install). The skill tells Claude Code, Codex and pi when and how to use `dray`, so you can ask in plain words. You do not type the commands yourself. ## Fan work out Ask in the conversation, for example: > Start a session for each of DRA-51, DRA-52 and DRA-53. The agent runs `dray session new` once per piece of work. Each new session: - gets its own worktree, starting at `origin/` - inherits the caller's agent, model, effort, fast mode and permission mode, unless the agent passes flags - starts working at once, on the prompt the agent wrote for it The new session has none of the calling conversation. A good prompt carries the issue text, the steps to reproduce and the constraints. See [Sessions](/docs/cli/sessions#start-a-session) for every flag. ## Where spawned sessions show **In the sidebar**, each new row appears under the session that started it. The app does not switch to it, so you stay in the conversation you were in. A session started by a spawned one nests a level deeper. **In the crew**, beside the conversation. The crew is a column next to the transcript with one row per session this conversation started. Click a row to open its live transcript in place. Permission and question cards from those sessions show in their rows, so you can answer them without leaving. ⌘-click a row to open that session in full view. ⌘⇧C shows or hides the crew. There is no button for it. In a window too narrow for it, the crew starts hidden, and ⌘⇧C shows it between the transcript and the composer. You can change the shortcut in Settings → Shortcuts. {/* screenshot: a conversation with the crew column beside it, three child sessions, one with a permission card open */} ### Hidden sessions A session started with `--hidden` shows in the crew only, not the sidebar. The skill has agents hide review sessions by default. To move one into the sidebar, right-click its crew row and choose **Show in sidebar**. ## Review with a second model `--base` starts a session's worktree from existing work. Point it at a session id and the new session gets its own checkout of that session's branch: ```bash dray session new --hidden --harness codex --base \ "Review the work on this branch. Send your findings back to with dray session send." ``` Ask for this in plain words: "have Codex review this". The reviewer reads the same commits in its own worktree, so it collides with nobody. - **Committed work only.** Changes not yet committed are not in the reviewer's tree. Commit first, or the review misses them. - **A new branch.** The reviewer works on its own `worktree-` branch. It never checks out yours, so it cannot commit onto your work. - `dray` prints what the id resolved to: `Started "…" in worktree calm-owl, based on worktree-brisk-jade`. `--base` also takes a branch, tag or commit. ## Messages between sessions ```bash dray session send "Review done: two findings, both fixed on worktree-calm-owl." ``` Any session can message any other. A child reports back to its parent, or a parent hands a child more context. The message starts a turn in the receiving session, or waits for the current turn to end. The receiver is told which session sent it and its id, so it can reply. Each message costs the receiver a whole turn, so agents should send one when the other session needs it, not to say "done". ## Check on sessions ```bash dray session ls ``` Lists the project's sessions with their status. Nothing reports back on its own. If you want to know when sessions finish, watch the sidebar and the crew, or ask the children to send a summary when they are done. ## Permission prompts A spawned session inherits the permission mode of the session that started it, and `dray session new` has no flag to change it. If the calling session asks before it edits files or runs commands, so does every session it starts. Each one stops at its first permission card and waits for you. Answer those cards in the crew, or open the session. To have children run without stopping, change the permission mode of the parent before it fans out. `dray` itself never raises a permission card in a Claude Code session. ## Limits - **Two levels deep.** A spawned session may start sessions; those may not. Start the next batch from a top-level session. - **No reading transcripts.** A session can create, list and message others, but cannot read what another session wrote. Ask it to send a summary. - **No shared checkout.** Every spawned session gets its own worktree. Two sessions cannot run in one directory. - **No permission flag.** Children always take the parent's permission mode. - **The crew lists direct children.** A grandchild shows in its own parent's crew, not the top one.