orchestra Session messaging
Exchange requests and replies between existing sessions in the same project.
On this page
An inbox between agentsSend a requestRead and replyExecute a request from the appWait, read, or cancelTeach agents the CLIAvailability and permissionsAn inbox between agents
A Pi session can ask Codex for a review, or Claude Code can send another session a question. The sender and recipient keep their existing terminals and agent conversations.
Right-click a session and select Messages… to view its request history or send a message. Unread requests show a count in the sidebar, and the status bar’s Inbox button shows messages that need attention. Opening this dialog does not claim a request on the agent’s behalf.
By default, receiving a message does not wake an agent or submit a terminal prompt. The recipient reads its inbox through the CLI, or you explicitly choose Execute Request. If you turn on Settings → Agents → Deliver Inbox Requests Automatically, Orchestra submits queued requests once the recipient finishes its turn, oldest first, and waits while you type in its terminal.
Send a request
Run the bundled orchestra command from a session inside the app. List the project’s sessions, then address the recipient by its Orchestra session ID. You can also obtain that ID with Copy Session ID in the context menu.
orchestra session list
orchestra session request <recipient-session-id> --text "Review the current diff"Read and reply
Ask the receiving agent to read its inbox and explicitly reply using the request ID. Reading the inbox claims the oldest pending request. Repeated reads return that request until it is replied to or cancelled. An empty inbox returns JSON null.
orchestra session inbox
orchestra run reply <request-id> --text "Here is my review"
# For a longer reply, use a UTF-8 file:
orchestra run reply <request-id> --file review.txtExecute a request from the app
Click Execute Request on an unread incoming request. Orchestra claims it, submits the request and reply instructions to the existing terminal, presses Enter, and opens the receiving session.
- Clear any existing draft in the terminal first.
- The session must already be running and must not report working.
- Resolve any previously claimed request awaiting a reply.
The agent still needs to call orchestra run reply to record its response. Terminal output and a green activity dot do not count as a reply.
Wait, read, or cancel
Wait for an exact request or read its current state. A timeout ends the wait, not the request. Cancelling a request does not terminate either agent session.
orchestra run wait <request-id> --timeout 120s
orchestra run read <request-id>
orchestra run cancel <request-id>
orchestra session read <session-id>Teach agents the CLI
Agents do not know about the orchestra CLI on their own. Run orchestra guide to print a guide written for agents, with the commands, common flows and rules; it matches the installed version of Orchestra.
To have agents find it themselves, install the Orchestra skill. In Settings → Agents → Agent Skill, choose the agents and click Install or Update, or click Copy Command and run it in a terminal. Installing uses the skills CLI and requires Node.js (npx). The skill only tells the agent to run orchestra guide when a task involves another session or the Scratchpad. Orchestra never installs it on its own and never edits agent settings.
orchestra guide
# Install the skill manually:
npx skills add https://github.com/theorchestradev/orchestra --skill orchestra -gAvailability and permissions
The app must remain open, and both sessions must belong to the same project. Plain terminals cannot send or receive messages. The CLI runs through a local socket and needs the session environment supplied by Orchestra. Sessions started before messaging was enabled need to be reopened.
An agent’s sandbox must allow the bundled CLI and local socket. Messages do not override agent permissions or user instructions. Unread requests survive an app restart; claimed requests become interrupted and are not automatically sent again.