Orchestra in your agents (MCP)

orchestra enable gives every agent on your machine Orchestra’s tools: recall before re-deriving past work, remember when a decision is made, and your issues. You type nothing else. The server is the orchestra binary you installed, started by the agent as orchestra mcp. It talks to the agent over stdio, so there is no URL to configure and no separate sign-in: it uses the same backend and sign-in as the rest of the CLI.

What enable does

For each client installed on this machine, enable registers the server once, for you, in every project, and prints one line saying what it did:

MCP server: every agent on this machine can recall and remember through Orchestra (/Users/you/.orchestra/bin/orchestra mcp)
✓ Claude Code: registered for every project (user scope)
✓ Codex: registered
✓ Cursor: registered in ~/.cursor/mcp.json
✓ VS Code: registered

Client	How it is registered
Claude Code	`claude mcp add --scope user orchestra -- ~/.orchestra/bin/orchestra mcp`. User scope, so it is in every project and nothing is written into your repository.
Codex	`codex mcp add orchestra -- ~/.orchestra/bin/orchestra mcp`
Cursor	Cursor has no command for this, so enable adds an `orchestra` entry to `~/.cursor/mcp.json` and keeps everything else in the file.
VS Code	`code --add-mcp`, with the `code` command from your PATH or from the app.

A client that is not installed is skipped and says so. Running enable again changes nothing. When an older Orchestra install registered the server at a different path, enable points it at this one. When a client runs Orchestra from a build in a checkout of Orchestra’s source (node .../packages/mcp/dist/bin.js, or node .../apps/cli/dist/index.js mcp), enable names each one and asks before pointing it at this install; the answer is yes when you press Enter, pass --yes, or run enable with no terminal. When something else is registered under the name orchestra (a hosted server URL, a wrapper of your own), enable leaves it alone and tells you. The desktop app’s Orchestra Local setup does the same registration.

The tools an agent gets

Every tool definition sits in the agent’s context on every turn, whether or not it is used, so the server offers a small set by default:

Tool	What it does
`recall`	Searches your workspace’s memory and session history, with citations
`remember`	Saves a decision or fact so later sessions can recall it
`get_me`	Who the agent is acting as, and the workspace’s issue statuses
`list_people`	People and agents in the workspace, to assign or mention
`list_sessions`	Recent agent sessions
`list_issues`	Issues, filtered by status, assignee or project
`get_issue`	One issue in full
`save_issue`	Creates or updates an issue
`add_issue_comment`	Comments on an issue

These are the tools agents actually called: in 998 Orchestra tool calls across 128 recorded Claude Code sessions, these nine were each used in at least ten sessions and made 94% of the calls. In Orchestra Local, the server offers every tool Local answers on your laptop, with no setting: recall, remember, list_memories, forget, share_memory, the team tools message_teammate and ask_team, the setup tools, get_me, list_people, the issue tools list_issues, get_issue, save_issue and add_issue_comment, list_sessions, and the tools that answer why code is the way it is: sessions_for_commit, get_session, list_session_messages and fork_session. On Local, list_sessions lists your sessions and, on every plan, the sessions teammates published to the repo’s git, newest first, each with the name of the person who started it. get_session and list_session_messages read a teammate’s published session read only, on every plan. fork_session makes it a new private session of yours, on the Team plan (forking your own is free). Local also offers dispatch_session and post_session_message, so one agent session can run others on your laptop (see One session runs others). Local’s issues live on your laptop, and on the Team plan they reach your teammates through the repo’s own git remote, never through Orchestra’s servers (see Issues). An issue from Linear is not on Local: the tools say so and point to the hosted workspace.

Why was this written?

On Orchestra Local, an agent can go from a commit, a line of code or a pull request to the session that wrote it, and read it. sessions_for_commit takes exactly one of commit (a SHA or any revision), file with line (git blame names the commit that last wrote it), or pr (its commits). It reads the Orchestra-Session trailer that Orchestra’s git hook adds to each commit made in a saved session, and answers with each session, whose it is, and atEventId: the message the commit’s turn ended on. Your sessions come from your laptop; a teammate’s from what they published to the repo’s git. list_session_messages then reads it, and fork_session with atEventId continues it from that moment as a new private session of yours. A commit made without the git hook says so (run orchestra enable to add it), and a teammate’s session that was never published says whose it is, so you know who to ask. The same answer is orchestra why in a terminal.

One session runs others

On Orchestra Local, an agent in Claude Code or Codex can start other agent sessions on your laptop and hear back from them, with nobody carrying messages in between. dispatch_session starts a session from a prompt, in the harness you name (claude-code, codex and the others your laptop has). It runs in its own git worktree under ~/.orchestra/worktrees, on a new branch made from the remote’s default branch as it is now, so it never edits the folder you or the dispatching agent are working in. The answer comes back at once with the session’s id, its folder and its branch. No terminal window opens: the session runs in the background, and you can watch it with orchestra tui or in the desktop app. Orchestra Local starts sessions on this machine only. A session is named by its id or by any unique start of it, six characters or more: the eight characters every screen shows are enough. get_session, list_session_messages and post_session_message all take that short id. post_session_message reaches any session you can see: one of your own, or a teammate’s live session on their laptop over the relay, where their own rule decides whether your agent may message it. A private session of someone else’s is never listed, read or written to, and its short id reads exactly like one that does not exist. list_sessions and get_session say, for each session, its harness, repository and branch, whether it is live, idle or ended, what it did last, needsYou when its agent asked a question and is waiting, and dispatchedBy: the session that started it. A dispatched session knows who dispatched it, because its prompt says so. It is told to report with message_session when it starts, opens a pull request, is blocked or is done. Orchestra also reports by itself, so nothing depends on the agent remembering: when the worker starts, when it opens a pull request, when it asks a question and waits, and when it stops, with its last words. The pull request and question reports come from Claude Code workers today. Each report arrives in the dispatching session at its next tool call, or wakes it if it is idle, and names the worker’s session. This works when the dispatching session is a plain Claude Code session in a terminal with Orchestra enabled.

Turn on more tools

The rest come in groups. Turn a group on with the mcp.tools setting:

Group	Tools
`sessions`	`get_session`, `list_session_messages`, `dispatch_session`, `post_session_message`, `interrupt_session`, `rerun_session_request`, `fork_session`, `answer_question`
`issues`	`get_issue_template`, `draft_issue_prompt`, `assign_issues`, `prioritize_issues`
`memory`	`list_memories`, `forget`, `share_memory`. Always on in Orchestra Local
`team`	`message_teammate`, `ask_team`. Always on in Orchestra Local, where they answer: see When a teammate’s agent asks yours
`setup`	`get_setup_status`, `apply_setup`. Always on in Orchestra Local, where they answer: see Share your setup
`commits`	`sessions_for_commit`. Always on in Orchestra Local, the only place it answers: it reads your checkout
`docs`	`list_docs`, `search_docs`, `get_doc`, `save_doc`
`graph`	`get_neighbors`
`capture`	`save_session`, `save_screenshot`, `save_preview`
`files`	`list_project_files`, `search_project_files`, `read_project_file`: the files people put on a project, and the text inside them (each match names its file and page, or a notebook’s cell). A text file comes back as text. In a research workspace a notebook comes back cell by cell, its code and saved text outputs, and `recall` also names the notebook cells that answer a question, from the projects the agent’s person can see; nothing in a notebook is ever run. For a PDF or an image the agent gets its path on this computer, or a download link that lasts a few minutes on a cloud workspace, and reads it with its own tools. An agent started on an issue in a project also begins with the passages of that project’s files that bear on the issue, each naming its file and page. Those passages are part of the session from then on: if the issue later moves out of a private project, its sessions move with it, and everyone who can then see a session can read the passages it started with
`research`	`search_runs`: the Weights & Biases runs shown on a project in a research workspace, with each run’s metrics, config, commit and link, and the agent session that produced it when its commit matches one Orchestra captured. A session you cannot see is not named

In ~/.orchestra/settings.json, for every project:

{
  "mcp": { "tools": ["docs", "sessions"] }
}

Or in a repository’s .orchestra/settings.json for that project only, or in the environment: ORCHESTRA_MCP_TOOLS=docs,sessions. "all" turns on every group. The server reads the setting when an agent session starts it, so a change reaches the next session.

Check it

orchestra doctor says, for each installed client, whether the server is registered and the command that fixes it when it is not. A client whose orchestra server runs something other than this install (an older install, a build from a checkout, or someone else’s server) gets a warning that names the client, what it runs, and the fix: orchestra enable for one of Orchestra’s own. In the folder you run doctor in, it also warns about a Claude Code server registered for that folder alone (local scope, or the folder’s .mcp.json), which Claude Code uses there before the one for every project. It then starts the server the way a client would and reports the tools it answers with and which groups are on:

✓ MCP: Claude Code has the Orchestra server registered
✓ MCP: Codex has the Orchestra server registered
✓ MCP: the server answers with 9 tools, the default set (get_me, list_people, ...)
✓ MCP tool groups: none on. The mcp.tools setting turns more on (docs: Settings)

In Claude Code, claude mcp list shows orchestra: ... - ✔ Connected.

Leave a client out

To skip registration, set ORCHESTRA_MCP_CLIENTS=off when you run enable, or name only the clients you want: ORCHESTRA_MCP_CLIENTS=claude-code,codex. To remove the server from a client, use the client’s own command, for example claude mcp remove --scope user orchestra or codex mcp remove orchestra.

Start here

Teams

Using Orchestra

Integrations