Claude–Copilot Supervisor

English | 简体中文

A local approval bridge: Claude Code → MCP → acpx/runtime → GitHub Copilot CLI.

Claude can delegate tasks, continue the discussion in the same Copilot session, inspect Copilot's tool requests, approve once or deny, and let the executor continue. This does not disguise Copilot as a Claude model and requires neither a public service nor a background daemon.

Experimental tool, not a security sandbox. Current verification covers native file changes, command approvals, and multi-turn context with a restricted tool set. General-purpose ask_user / elicitation, cross-process recovery of pending approvals, and genuine mid-turn steering are not implemented. See the security boundaries and verification notes.

Architecture

Claude Code
   │ stdio MCP: start / status / decide / cancel / close
   ▼
Local supervisor process
   ├─ Persistent sessions and short-wait status queries
   ├─ Suspended permission callbacks, exact allow_once selection
   ├─ Timeouts, cancellation, shutdown, and resource limits
   ▼
acpx/runtime (createAcpRuntime)
   │ ACP stdio
   ▼
GitHub Copilot CLI

ACP and MCP are different protocols; this repository bridges them. It does not listen on TCP/HTTP ports. It is not an official GitHub, Anthropic, or OpenClaw plugin.

Dependency credit

The embedded ACP runtime is provided by acpx, maintained by OpenClaw. This project is a new supervisor/MCP bridge built on that dependency, not an acpx fork or a rewrite of its underlying runtime. Dependency licenses remain with their respective projects.

Related MCP server: pokeclaw

Installation

Prerequisites:

• Node.js 22.13+ and npm.

• For real use: copilot and claude on PATH in the same execution environment, each already authenticated.

• A global acpx installation is not required; the project's local dependency supplies the pinned version.

From this repository:

npm ci --ignore-scripts --no-fund --no-audit
npm run check

npm run check performs syntax checks and tests that do not call models. Tests exercise the mechanisms using an included ACP fixture and fault injection; they do not read personal projects or require model accounts. Temporary files use Node's system temporary-directory resolution, including support for TMPDIR / TMP / TEMP.

If Copilot is not installed, follow the official installation instructions, then authenticate in your own terminal:

npm install -g @github/copilot
copilot login --device-code

Do not put passwords, tokens, or device codes in this repository, MCP JSON, or prompts. If a credential store is unavailable, the CLI may fall back to storing tokens in plaintext; review the official CLI's storage behavior against your own security requirements before logging in.

Connect to Claude Code

First create a test project without secrets or production data. Copy examples/mcp.example.json to your own local configuration (the suggested name mcp.local.json is gitignored), and replace every absolute path.

Configuration shape for real Copilot:

{
  "mcpServers": {
    "copilot-supervisor": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/claude-copilot-supervisor/src/server.mjs",
        "--project-root", "/absolute/path/to/empty-test-project",
        "--state-dir", "/absolute/path/to/private-session-state"
      ]
    }
  }
}

Then load it temporarily in Claude Code without writing global settings:

claude --strict-mcp-config --mcp-config /absolute/path/to/mcp.local.json

--strict-mcp-config makes that Claude session load only the explicitly configured MCP servers; it does not change other sessions' settings. Do not authorize an entire server, home directory, or project containing keys.

Suggested supervisor instructions:

Use the copilot-supervisor tools only for the task I explicitly specify.
After starting, query with copilot_status(waitMs=10000); do not busy-poll.
On waiting_approval, inspect the exact paths, diff, or complete command.
Approve once only within the project and task scope I authorized; do not expand permissions.
Deny sudo, credential access, external publication, deployment, and unrelated paths, and explain why.
Verify the actual result when finished, then close the session.

These prompts constrain the supervisor's behavior; they are not enforcement policies at the execution layer. Do not use model judgment as your only security boundary.

Demo without real models

Append --fixture to the configuration's args to use the repository's deterministic test agent. In this mode, the prompt is synthetic test JSON, not natural language, for example:

{"action":"write","file":"probe.txt","content":"approved test"}

The fixture is not Copilot and does not call a model. Remove --fixture to run real Copilot. Do not conflate the two kinds of test evidence.

MCP tools

Typical flow:

start → status → waiting_approval → inspect request → decide → status → finished
                    ↑                                          │
                    └──────── if another operation follows ────┘

• If allow_once is absent, the bridge does not silently substitute allow_always.

• Expired, cross-job, and reused approval IDs are rejected.

• completed means only that the agent's turn ended, not that the task succeeded; a denied operation may still end normally with end_turn.

• Session continuation works only within the current process. This prototype does not recover public session IDs or pending Promises after a process restart.

See docs/protocol.md for the detailed protocol and lifecycle.

Operation and limits

npm start -- --project-root /absolute/path/to/test-project --state-dir /absolute/path/to/private-state

This entry point's stdout is reserved for MCP JSON-RPC; it is not an interactive TUI. Do not write debug logs to stdout.

Defaults: 60-second approval lifetime; 5-minute task deadline; 10-second startup handshake budget; 3-second cancellation grace period; at most 4 sessions and 64 retained jobs. The state directory may contain task content or code, must remain private, and must not be committed. The default is the repository's .state/; set --state-dir explicitly to use another directory.

The current Copilot launch arguments disable built-in GitHub MCP servers and custom instructions, exposing only view,create,edit,apply_patch,bash. The acpx client's fs/terminal callbacks are disabled; Copilot's native tools use their own execution path. This is neither a full everyday development tool set nor OS isolation.

Tests have primarily run on Linux/Node 22. Portable temporary-directory handling is not a guarantee of Windows end-to-end compatibility; in particular, process-group termination in the opt-in live scripts has not been verified on Windows.

Real-model integration tests (explicit opt-in; consumes usage)

npm run test:live:copilot-files
npm run test:live:copilot-commands
npm run test:live:claude-copilot

These respectively test real Copilot's native file permissions, exact command permissions, and real Claude approving real Copilot. They work in fresh temporary test directories, retain private reports, and do not commit real execution logs to Git.

There is also npm run test:live:claude-fixture: only the supervisor is real Claude; the executor is still the fixture. Real-model use is kept separate from ordinary regression tests.

Project layout

src/                 Approval queue, session supervisor, stdio MCP entry point
scripts/             Quality checks, opt-in model integration tests, evidence parsers
test/                Offline regressions and deterministic ACP fixture
examples/            Generic MCP configuration example without credentials
docs/                Protocol and de-identified verification summary

Privacy, publication, and license

This repository contains only implementation, tests, and de-identified documentation—not authentication state, personal configuration, raw conversations, real execution IDs, machine-specific paths, or test logs. Public publication has been explicitly authorized by the owner. Runtime state, authentication files, and real execution logs must still remain private. Source visibility and licensing are separate decisions.

This project is licensed under the MIT License. Copyright (c) claude-copilot-supervisor contributors. Dependencies retain their respective licenses. This project is not published to npm.