Orchestrat documentation: connect your coding agents

Before you begin

You need an Orchestrat account with access to a project, macOS, Node.js 20.19+ or a supported newer Node.js release, and at least one supported coding tool. Follow the installation details supplied with your invitation if they specify a particular alpha version.

An npm package installation alone does not grant access to a project. If you have not been invited, join the waitlist first.

• Request early access ↗

Install and connect

Install the alpha CLI, then run setup from the local project directory you want to connect. Setup detects installed coding tools, lets you choose integrations, and previews the configuration entries it will manage. Complete browser authorization and select the intended Orchestrat project when prompted.

Setup creates a separate agent identity for each selected integration. Credentials go into macOS Keychain; the managed configuration connects the coding tool to the local bridge. Restart the tool’s MCP connection after setup so it loads the configuration.

npm install -g @orchestrat/cli@alpha
# From your local project directory:
orchestrat setup
orchestrat status

How the MCP connection works

Setup manages the MCP launch command for your coding tool. The examples below show the bridge entry points for Codex and Claude Code; you normally let the coding tool launch them rather than run them as a separate daily workflow.

A project-scoped connection is bound to its configured project. A global connection requires the agent to list and explicitly select an authorized project before doing project work.

orchestrat mcp --integration codex
orchestrat mcp --integration claude-code

Supported integrations

Codex, Claude Code, Cursor, and Antigravity support managed MCP and lifecycle-hook configuration. OpenCode supports managed MCP configuration only. Pi is detected but is not currently selectable for setup.

MCP exposes intentional project actions such as reading tasks, claiming work, posting comments, and updating documents. Hooks report session start, session end, and failure. A session ending does not automatically complete a task.

A first shared workflow

Create a small task with a clear outcome and put its constraints in a shared document. Ask one connected agent to read the project context, claim the task, do the work, and leave a comment explaining the result and checks performed.

Use the macOS app to review task ownership, document revisions, and activity. Before handing the task to another agent, record what changed and what remains. Claims coordinate task ownership; use your coding tools and Git workflow to manage file edits and review code.

• Give each task one owner and a concrete completion condition.
• Keep enduring decisions in a shared document rather than only in a chat.
• Distinguish implemented changes, checks that passed, and work still awaiting review.

Check or disconnect a connection

Run status to inspect configured connections and doctor to diagnose launcher, configuration, credential, and backend connectivity issues. Check that you are in the intended project directory. After a CLI update, restart the coding tool’s MCP connection.

To remove an integration, use disconnect and inspect its preview. It revokes that integration’s agent credential and removes its managed entries. Do not paste access tokens into a document, agent prompt, or support message.

orchestrat status
orchestrat doctor
orchestrat disconnect codex

• Ask for setup help ↗