List the agent profiles a session can be launched with (name, role, model, effort).

Return a profile's full system prompt and settings.

Start a new session: one full Claude Code process in its own tmux window.

Blocks until Claude shows its input box (up to ~90 s) so a failed start is reported here rather than discovered later. working_directory must be a Linux path (/mnt/c/... for a Windows folder). model overrides the profile's model (opus / sonnet). initial_message is delivered as the first task once the session is ready. provider is accepted for compatibility; only claude_code exists.

use_worktree runs the session in its own git worktree (under MAESTRO_HOME) on a new branch mx/<terminal_id> made from the repo's HEAD, so parallel workers on one repository never trample each other; the result's worktree gives its path and branch. The worker is told to commit there. Merge it yourself with plain git afterwards (git -C <repo> merge mx/<terminal_id>). Deleting the terminal removes the checkout after committing anything left uncommitted on the branch; the branch is kept when it has commits the repo's HEAD lacks.

Queue a message for a terminal; it is pasted as soon as the terminal is idle.

Live status of one terminal: idle, processing, completed, waiting_user_answer, error.

Read a terminal's output. last = Claude's final answer; full = the rendered scrollback.

Read output by terminal id, or by session name when the session has one terminal.

max_chars keeps only the tail of the output.

All running sessions with their terminal counts.

A session and every terminal in it, with live statuses (oldest terminal first).

Every live terminal that runs in its own git worktree: what there is to merge.

Each entry has terminal_id, status, repo, path and branch. Merge a finished one with git -C <repo> merge <branch>; deleting the terminal commits any leftovers on the branch, removes the checkout and keeps the branch when it has commits the repo's HEAD lacks. orphaned lists checkouts whose terminal died with an earlier server; they are never removed on their own — merge what you want, then remove_worktree.

Remove an orphaned checkout listed by list_worktrees (leftovers are committed first; the branch stays if unmerged).

Close every terminal of a session and the session itself.

Answer the question a terminal is blocked on. Only valid while its status is waiting_user_answer.

answer is a key (Enter, Escape, Up, Down, Tab, Space), a single digit (in an option dialog it selects and submits that option: "2" = the second one), or one line of text, typed and followed by Enter — only where a text field has focus (an option list treats letters as hotkeys). Escape cancels the question and ends the turn with no answer.

Stop a terminal's current turn (Escape), e.g. when a worker is going in circles.

Only while its status is processing or waiting_user_answer (an idle prompt has nothing to interrupt and is refused). Returns the status observed ~2 s later (normally idle or completed); queued messages are then delivered as usual.

Replace a terminal's Claude with a fresh one: same id, profile, model, directory and inbox.

Use when its status is error (Claude exited) or it stays unresponsive after interrupt. The conversation is lost. Blocks until the new Claude is ready (up to ~90 s).

The whole fleet in one call: every session, every terminal, and who needs you.

Prefer this over list_sessions plus a get_session_info per session: it is one call and one block of context instead of one per session. Each terminal carries status, progress, stuck, model, profile, working directory, worktree and pending_messages. needs_attention is the part to act on -- terminals that are waiting on an answer, stuck, or failed. totals counts them by status.

Block until a terminal finishes, asks something or dies -- instead of polling.

This holds your conversation until it returns. From Claude Code, prefer a background watch on GET /events (see the maestro skill) so the user can keep talking to you; use this for scripts, or with a short timeout.

Returns as soon as one watched terminal reaches one of states (default: completed, waiting_user_answer, error -- stuck is also available), or when timeout_seconds runs out (max 900). With require_all it waits for every watched terminal instead of the first. terminal_ids defaults to the whole fleet. A terminal with a message still queued counts as busy, not finished.

This is the loop to use while a fleet runs: wait, act on what came back (read its output, answer its question, restart it), wait again. Polling get_terminal_status in a loop costs a call and a turn every few seconds and tells you nothing in between.

Launch several sessions at once, in parallel. One call for a whole fleet.

Each entry takes the same fields as launch_session: agent_profile, session_name, working_directory, model, initial_message, use_worktree. Every launch still blocks until its Claude is ready, so a failure is reported against its own entry and the rest still start; max_parallel (1-8) caps how many start at the same time.

Ten sessions launched one by one cost ten calls and several minutes of waiting; this is one call and about as long as the slowest one.

Queue one message for many terminals at once (the whole fleet when none is named).

For the things you say to everyone: a change of plan, "commit what you have and report", a constraint you forgot. Each terminal receives it when it is next idle, exactly as send_session_message does.

How much of the Claude subscription is left: the 5-hour and weekly windows.

Worth a look before opening a large fleet, and when deciding whether to run the stronger model everywhere. Percentages are utilisation, so 100 means spent; resets_at says when the window rolls over. Unavailable (no local credentials, or the endpoint refused) comes back as ok: false rather than a made-up number.