Skip to main content
Glama

orc-mcp

A local-only MCP orchestrator that coordinates multiple Claude Code sessions (one session = one repository).

The orchestrator itself is a resident program with no LLM inside. It has three jobs:

  • Ledger: stores the design decisions and task progress each session reports, in SQLite

  • git reader: reads other sessions' commits, diffs, and files directly from each repository's git

  • Signal: accepts "wait until that task is done", and when the condition is met, returns along with the changes

Requirements

  • Node.js 22.13 or later (uses the built-in node:sqlite; on 22.x it prints an experimental-feature warning)

  • git

Related MCP server: z-code-mcp

Starting

npm install
npm run build
ORC_TOKEN=$(openssl rand -hex 16) npm start

Environment variable

Default

Description

ORC_PORT

4700

Listening port (always bound to 127.0.0.1)

ORC_DB

~/.orc-mcp/orc.db

SQLite file

ORC_TOKEN

none

When set, Authorization: Bearer is required

ORC_STALE_SEC

1800

A session that has not called in for longer than this is considered stalled

ORC_TAKEOVER_SEC

120

A connection used within this many seconds is considered "live", and joining under the same name is rejected

Connecting from each repository

Copy mcp.json.example to .mcp.json in each repository. The content can be the same for every repository (session names are not written in the config file).

Joining a project

Tell each session the project name in chat.

Join the orchestrator with project name shop

The session calls join_project and can then interact only with sessions that joined under the same project name. Tasks, design decisions, and repositories of sessions in other projects are completely invisible.

  • Project name: a name shared by all participants. Alphanumerics, _, and -, up to 40 characters

  • Your name: what you are called within the project. Defaults to the repository name; can be changed with name

worktrees

This also works as-is when a repository has multiple sessions (when a worktree is created per session).

  • The unit of registration is the worktree. Two worktrees of repository a can join different projects foo and bar

  • The default name is the main repository's name (a in this example), not the worktree's directory name

  • The changes other sessions see are the commits on the branch checked out in that worktree

Example: when repositories a and b each have a session for foo and one for bar, only the a and b that joined foo see each other, and only the a and b that joined bar see each other.

Duplicate registration

The following are rejected as duplicate registrations.

Situation

Result

In the same project, a different repository tries to use the same name

Rejected (specify a different name)

A registered repository (worktree) is registered under a different name or a different project

Rejected (leave_project first)

A session that has already joined tries to join another project as well

Rejected (leave_project first)

The same name and repository are in use by another live session

Rejected (can be taken over with force: true)

Rejoining with the same project name, name, and repository is treated as a reconnection and keeps the tasks and base commit. After restarting the orchestrator, rejoin from each session.

"Live" means the connection called the orchestrator within the last ORC_TAKEOVER_SEC seconds (120 by default).

Tools

Category

Tool

Description

Join

join_project

Join by declaring a project name. HEAD at the first join becomes the base commit

leave_project

Leave. The repository is released; tasks and design decisions left behind remain visible

Report

publish_decision

Record a design decision (topic, decision, rationale, scope of impact)

update_task

Create tasks and update progress. done requires an existing commit SHA

Read

get_overview

Roles, tasks, recent decisions, and wait status of every session in the project

get_decisions

List of design decisions

get_changes

Another session's commits and changed files

get_diff

Another session's diff

read_file

Another session's committed files

Wait

wait_for

Wait for a task to complete or a decision to be published

cancel_wait

Cancel a wait

wait_for waits up to 110 seconds (50 by default); if the condition is not met it returns pending and a wait_id. Calling again with the same wait_id continues the wait. A circular wait is rejected with an error at registration time.

Hooks (enforcing waits and guiding reconnection)

Calling wait_for again is only a request to the model, so Claude Code hooks reinforce it. After npm run build, put the contents of hooks.settings.example.json into each repository's .claude/settings.json (or ~/.claude/settings.json) and rewrite the paths. Set ORC_PORT and ORC_TOKEN in the environment Claude Code is started from.

Hook

Behavior

Stop (asyncRewake)

When a turn ends with a wait still pending, it waits in the background. When the condition is met, it wakes Claude with the commits and design decisions. Uses no tokens while waiting

SessionStart

If the worktree is registered, tells Claude how to rejoin and which waits remain. If the session started in a new process, allows rejoining without force

Hooks identify the session from the working directory (worktree). If the orchestrator is not running, they do nothing.

Tests

npm test

Creates temporary repositories and worktrees, and checks end to end with clients for multiple sessions: joining, rejecting duplicate registration, isolation between projects, waits, cycle detection, completion notices, fetching diffs, takeover, leaving, joining from worktrees, and hooks.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables multiple Claude Code sessions to communicate, share state, and coordinate tasks through session management, message passing, and task scheduling, supporting a three-role collaboration workflow.
      2
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables coordinating Claude Code and Codex across separate Git worktrees with shared issue ownership, file reservations, messages, and explicit handoffs.
      213 PyPI
      3
      MIT