Documentation

Hermes / OpenClaw MCP Bridge

How a Hermes- or OpenClaw-style coordinator integrates with Gajae Code. Use Coordinator MCP for recommended multi-session automation and durable workflow state, the SDK for direct control of one session, and ACP when an editor is the client.

Pick an integration path

Coordinator MCP — Recommended for automation use gjc mcp-serve coordinator to supervise sessions, submit bounded turns, resolve structured questions, and collect durable reports. Use Coordinator MCP →
SDK — use the authenticated WebSocket SDK for direct, per-session control from an application, dashboard, or companion client. Use the SDK →
ACP — use the Agent Client Protocol when a compatible editor is the client. ACP is the editor protocol, not a coordinator control plane. Use ACP →

Core contract and adapters

Coordinator MCP is the recommended automation surface for Hermes, OpenClaw, and other external coordinators. It is a transport adapter over a durable coordination contract, not a screen-control integration. Hermes and OpenClaw are compatibility presets, not privileged product modes.

packages/coding-agent/src/coordinator/contract.ts owns transport-neutral server metadata and tool names.
gjc mcp-serve coordinator is the outward MCP adapter for automation clients.
gjc coordinator is the read-only CLI/debug adapter for inspecting the same contract.
gjc setup hermes renders coordinator configuration and operator guidance.

gjc mcp-serve hermes remains a compatibility alias for the coordinator bridge.

Path 1 · Coordinator MCP Recommended for automation

Use Coordinator MCP for machine automation that must supervise more than one session or preserve progress across restarts. It lists sessions, starts or registers sessions, submits bounded turns, handles structured questions, exposes durable status and artifacts, and writes coordination reports. The durable turn, question, artifact, and report records are the authority for automation.

Standard setup

Use gjc setup hermes to render or install a portable MCP setup package for a controller that accepts Hermes-compatible MCP configuration. The default mode is render-only and writes no files.

gjc setup hermes --root /path/to/repo --profile my-bot --repo gajae-code

To install into a Hermes profile, opt in to the needed mutation classes and pass an install target:

gjc setup hermes \
  --root /path/to/repo \
  --profile my-bot \
  --repo gajae-code \
  --mutation sessions,questions,reports \
  --profile-dir /path/to/hermes/profile \
  --install

The generated setup is model-agnostic and worktree-isolated. By default it renders GJC_COORDINATOR_MCP_SESSION_COMMAND as gjc --worktree, so spawned sessions use a GJC-managed sibling worktree while retaining the original repository as the project identity. Run a non-mutating smoke check with gjc setup hermes --root /path/to/repo --smoke.

Safety model

The bridge is read-only and fail-closed by default.

export GJC_COORDINATOR_MCP_WORKDIR_ROOTS="/path/to/repo:/path/to/worktrees"

Mutating tools require both startup opt-in and per-call consent:

export GJC_COORDINATOR_MCP_MUTATIONS="sessions,questions,reports"

Every mutating MCP call must also include allow_mutation: true. Missing startup opt-in or per-call consent returns an error.
Workdir roots, repository identity, and safe session tokens are validated before state writes.
Artifact reads are canonicalized, symlink escapes are rejected, and returned content is byte-capped by GJC_COORDINATOR_MCP_ARTIFACT_BYTE_CAP.
Optional namespace variables GJC_COORDINATOR_MCP_PROFILE and GJC_COORDINATOR_MCP_REPO prevent cross-profile and cross-repository enumeration; a missing namespace never widens into global enumeration.

gjc setup hermes renders GJC_COORDINATOR_MCP_WORKDIR_ROOTS with the host platform path delimiter (: on POSIX, ; on Windows).

Common Coordinator MCP tools

This is a non-exhaustive common subset. Run gjc coordinator check --json for the authoritative machine-readable tool inventory.

Read tools: gjc_coordinator_list_sessions, gjc_coordinator_read_status, gjc_coordinator_list_questions, gjc_coordinator_list_artifacts, gjc_coordinator_read_artifact, gjc_coordinator_read_coordination_status, gjc_coordinator_read_turn, gjc_coordinator_await_turn, gjc_coordinator_watch_events.

Mutating tools: gjc_coordinator_start_session, gjc_coordinator_register_session, gjc_coordinator_send_prompt, gjc_coordinator_submit_question_answer, gjc_coordinator_report_status, gjc_delegate_plan, gjc_delegate_execute, gjc_delegate_team.

The gjc_delegate_* tools delegate a complete workflow; use the lower-level session and turn tools only when the coordinator needs fine-grained control.

Coordinator turn model

Treat durable turns as the unit of work. The bridge stores turn, question, and report state and exposes bounded polling snapshots.

Call gjc_coordinator_start_session with allow_mutation: true.
Call gjc_coordinator_send_prompt with allow_mutation: true.
Store the returned turn_id.
Poll gjc_coordinator_read_turn, or call bounded gjc_coordinator_await_turn, until the turn completes.
If gjc_coordinator_list_questions shows a question for that turn, answer with gjc_coordinator_submit_question_answer.
Use gjc_coordinator_report_status with session_id and turn_id to write explicit completion or failure evidence.

A session has one active turn by default. A second turn is rejected with active_turn_exists unless the caller passes queue: true or force: true. Queued turns are durable and promote when the active turn completes; force supersedes and audits the previous active turn.

Event watch surface

gjc_coordinator_watch_events is a bounded long-poll event journal, not an unbounded stream. Inputs are after_seq (default 0), optional session_id and event_types, timeout_ms capped at 30000, and limit capped at 100. The response includes events, latest_seq, timed_out, and transport: { "mcp": "long_poll", "push_subscriptions": false }. Persist latest_seq and resume safely after restart. A timeout with no events is not failure.

Controller config example

{
  "mcp_servers": {
    "gjc_coordinator": {
      "command": "gjc",
      "args": ["mcp-serve", "coordinator"],
      "env": {
        "GJC_COORDINATOR_MCP_WORKDIR_ROOTS": "/path/to/repo",
        "GJC_COORDINATOR_MCP_PROFILE": "team-a",
        "GJC_COORDINATOR_MCP_REPO": "project",
        "GJC_COORDINATOR_MCP_SESSION_COMMAND": "gjc --worktree"
      },
      "enabled": true
    }
  }
}

Smoke-check the contract with gjc mcp-serve coordinator --check --json. Expect ok: true, server name gjc-coordinator-mcp, and the GJC-named tool list.

Delegating workflows

The generated gajae-code plugin exposes the coordinator MCP server and tools for complete GJC workflows. Each delegate tool starts or reuses a session, submits one workflow-tagged turn, and returns durable turn status plus artifacts.

Tool	Workflow	Purpose
`gjc_delegate_plan`	Plan	Delegate consensus planning to a pending-approval plan.
`gjc_delegate_execute`	Execute	Delegate execution to completion with verification.
`gjc_delegate_team`	Team	Delegate parallel team execution with durable coordination state.

Pass cwd and task; set allow_mutation: true only when the sessions mutation class is enabled and the user has approved changes. Poll the returned turn_id with gjc_coordinator_await_turn or gjc_coordinator_watch_events.

Operator core loop

For a Hermes- or OpenClaw-style coordinator:

Find an existing session with gjc_coordinator_list_sessions, or start one when a new session is required and mutation is enabled.
Submit one bounded task with gjc_coordinator_send_prompt and store its turn_id.
Use gjc_coordinator_watch_events with the stored latest_seq, or gjc_coordinator_read_turn/gjc_coordinator_await_turn, until the turn completes. Queue a later task with queue: true.
List and answer structured questions with gjc_coordinator_list_questions and gjc_coordinator_submit_question_answer.
Write coordinator-visible status and final reports with gjc_coordinator_report_status.

Report completion only after durable turn state records completion.

Path 2 · SDK for direct session control

Use the SDK when one application controls one Gajae Code session directly. The authenticated WebSocket contract provides session-specific actions, replies, turn updates, and typed control and read operations without turning a coordinator into a screen relay. Applications can use @gajae-code/bridge-client and SdkClient, or any WebSocket client that implements the documented JSON frames.

For session discovery, lifecycle, frame types, and direct control examples, see Building on the SDK. Use Coordinator MCP instead when an automation client needs to coordinate multiple worktree-scoped sessions.

Path 3 · ACP for editor integration

ACP is the editor protocol. Use it when a compatible editor is the client and should own the editor-facing session interaction and presentation. It is separate from Coordinator MCP automation and from the SDK's direct per-session application control.

Verification checklist

gjc mcp-serve coordinator --check --json returns ok: true with the GJC-named tool list.
A read-only Coordinator MCP call, such as gjc_coordinator_list_sessions, succeeds before any mutation class is enabled.
A mutating Coordinator MCP call without startup opt-in or allow_mutation: true fails closed.
A delegated workflow returns a durable turn_id; its completed turn state and report confirm completion.
An SDK client authenticates to one discovered session and receives the documented lifecycle or action frames for that session.
A compatible editor uses ACP as its editor protocol; it does not replace Coordinator MCP for automation.