ACP Gateway

English | 한국어 | 日本語 | 简体中文

Let the coding agent you already use delegate work to Claude Code, Codex, and Grok on demand — over MCP + ACP, with persistent sessions, interactive approvals, and no predefined workflows.

ACP Gateway is a local daemon and Model Context Protocol (MCP) server: whichever of Claude Code, Codex, or Grok you talk to uses it to delegate work to the others, and to any other installed agent listed in the official Agent Client Protocol (ACP) registry.

Do you use more than one AI agent?

Do you ask Claude a question, have Codex fix the code, then hand the review to Grok — juggling terminals and conversations the whole time?

Have you ever thought, “Instead of directing each of these agents myself, I wish one agent would just put the others to work for me…”?

That is what this is for.

Overview

ACP Gateway is middleware that lets the AI you talk to directly — the orchestrator — discover the AI Workers installed on your machine, run them over ACP, and manage everything from long-running tasks and permission requests to retrieving the final result. Main, as used in the code and tool descriptions, means this orchestrator role.

• Claude Code, Codex, and Grok are supported as built-in Workers; other ACP-capable AIs installed locally are discovered by matching them against the official ACP registry.
• The daemon keeps ACP sessions and provider processes alive.
• Worker sessions can be recovered even when MCP restarts.
• The orchestrator controls models, permissions, questions, cancellation, and result collection.
• The Gateway strips its token, socket and Main identity from Worker environments, but a Worker that reads files without going through the Gateway can still find the token; see Permission policies.
• Designed for local, single-user, single-machine use.

Use cases

• One conversation, several agents — From Claude Code, have Codex implement a change and Grok review it, without leaving the conversation or switching terminals.
• Follow-ups in the same session — Send feedback to the Worker that did the work instead of starting over. If its session was unloaded while idle, the next prompt reconnects it on providers that support resume or load.
• Approvals from your main agent — Under the ask policy, a Worker's permission requests and questions come to the agent you talk to, which approves, denies or answers them, or checks with you first.
• Results after a reconnect — After your host reconnects or the Gateway restarts, agent_acp_inbox {action: "attention"} lists what is still waiting on you and the finished results you have not collected.
• Reviews that cannot touch your tree — Open a reviewer with workspace: "snapshot" so it works in a private copy of the repository, then read its changes as a patch with workspace_diff and apply only what you want.
• Why a session stopped — Each session records the reason for its status, and agent_acp_session {action: "check"} tells you, without starting anything, whether it can come back.

Quick start

Requirements

Node.js 22 or later, and macOS or Linux.

Install

Install the Gateway from npm, then let the bootstrap set it up for the agents on your machine:

npm install -g acp-gateway-daemon
acp-gateway-bootstrap --install-all --refresh-registry --dry-run
acp-gateway-bootstrap --install-all --refresh-registry

The Claude Worker runs the Claude CLI you have installed: the one CLAUDE_CODE_EXECUTABLE names if it is not blank, otherwise the first claude in an absolute directory on the daemon's PATH (skipping copies inside the Gateway's own dependencies and any binary bundled with the Claude Agent SDK), otherwise ~/.local/bin/claude; if none is found, Claude is reported as not installed.

Of the last two commands, the first is a dry-run that only shows the installation plan, and the second performs the actual installation. --install-all can install or update, globally, the npx and uvx packages named by the official ACP registry, so check the targets and versions in the dry-run output first. The registry manifest is maintained by ACP, but the actual packages and binaries are downloaded from each vendor's distribution site. What the installation changes on your machine is listed in What installation changes on your machine.

By default, --install-all asks which of Codex, Claude, or Grok you want to use as the front door — the agent you talk to. The Control MCP for the orchestrator is registered only with the one you choose, while the read-only Guide MCP and the skill are installed for every discovered agent. In non-interactive installs Codex is the default, and you can choose explicitly like this:

acp-gateway-bootstrap --install-all --front-door codex
acp-gateway-bootstrap --install-all --front-door claude
acp-gateway-bootstrap --install-all --front-door grok

From source

To run the Gateway from a Git checkout instead, for example to change the code, clone and link it:

git clone https://github.com/creverse-ai-lab/agent_gateway.git
cd agent_gateway
npm ci
npm link
acp-gateway-bootstrap --install-all --refresh-registry --dry-run
acp-gateway-bootstrap --install-all --refresh-registry

npm link puts the same commands on your PATH, running straight from the checkout. The last two commands and the front-door choice work exactly as above.

First delegation

The installer also installs the agent-delegator skill for every discovered AI. From your request, the skill works out the Worker, model, and permission scope, and it guides everything from creating a Gateway session and handing over the task to checking progress, handling questions and permission requests, and retrieving the result. After installation you do not need to memorize MCP tool names — just ask the orchestrator in natural language.

For example, you can ask the orchestrator AI you are talking to:

Have Claude Sonnet review the authentication code in this repository, read-only, and summarize the result.

Have Grok 4.5 red-team the security weaknesses of the current design, and check with me on any permission requests.

Internally it works in this order:

1. agent_acp_setup checks the providers
2. agent_acp_session_open creates a Worker session
3. If needed, agent_acp_config reads and sets parameters the Worker supports, such as model, mode, and reasoning level
4. agent_acp_run hands over the task
5. agent_acp_wait waits until the Worker finishes or needs a response, instead of polling with agent_acp_poll
6. If needed, agent_acp_permission or agent_acp_answer responds
7. When done, reuse the session or close it with agent_acp_session

The bundled agent-delegator is a general-purpose starting point. If you have a Worker you use often, a default model, a permission policy, a review order, or a result format, you can edit the installed skill to fit the way you work. acp-gateway-bootstrap --update and a plain --update-skill do not overwrite your edited copy. Run --update-skill --force explicitly only when you want to reset it to the version bundled with the installed Gateway.

Permission policies

Choose one of the following policies when you open a session.

| Policy | Use | |---|---| | read_only | Analysis, review, and other read-only work | | ask | Orchestrator approval is required before changing files or running commands | | auto_approve | Automatic approval within the session boundary the user has allowed |

The Control token, the orchestrator identifier (Main ID), and the Gateway socket path are removed from the ACP Worker's environment, and re-injecting the Control MCP into a Worker session is blocked, whether by its name, its installed path, or the identity in its environment. Nor can a Worker's own CLI start it from your agent configuration, as a Codex Worker would from ~/.codex/config.toml: the Control MCP refuses to run inside a Worker's process tree, and the daemon refuses Control to any caller running under it (WORKER_CONTROL_DENIED). On macOS and Linux, where the process tree cannot be read at all (no /proc, and ps missing or blocked, so the Control MCP cannot read even its own process), both refuse, since a Worker cannot then be told from a Main. Windows has neither, so there nothing is refused for that, and a Worker is told apart only by the ACP_GATEWAY_WORKER variable the Gateway sets on it, or when the agent CLI asking for Control is itself a process the daemon started. The daemon also removes the token and Main ID from its own environment at startup, so nothing it starts, adapter updates through npm or uv included, inherits them. The rest of the daemon's environment, which comes from whatever started it, usually a front door or the installer, still reaches Workers and their terminals, API keys, cloud credentials and SSH_AUTH_SOCK included, so a provider that signs in through its environment keeps working.

File reads and writes the Gateway makes for a Worker (ACP fs/read_text_file and fs/write_text_file) stay inside the session roots and off the protected paths even when the Worker swaps in a symbolic link or another directory while they run. A read also never returns a file that holds the Gateway's Control token, such as a copy of install.json. When the installer replaces install.json, it also empties the old file if a hard link still holds it, as far as it can: not on Windows, which has no open that refuses to follow a link, and not when the old file cannot be opened for writing; such a link keeps the old content, but the Gateway's read still refuses it for the token it holds. On macOS, and on Linux with /proc, a write creates a new file only in the directory that was checked. Elsewhere (Linux without /proc, other systems) such a swap during a write can still leave a new, empty file where the swapped-in link points; the write is refused, nothing is written into that file, and the Gateway does not delete it, since a deletion by name could be redirected the same way. Gateway clients, the Control MCP included, send the token only to a socket owned by the same user, on a path no other user can redirect. Terminals the Gateway opens for a Worker run on macOS in a sandbox that denies the protected paths (~/.acp-gateway, the state directories and the socket); setuid programs such as ps and top cannot start inside it, and a command that cannot start exits with status 71. Where there is no such sandbox, auto_approve sends each terminal to the orchestrator first. Approving a Worker's command lets that exact command through once, word for word, with exactly the same environment variables and values, and in the same working directory: the directory that was at that path when the orchestrator was asked, not another one put there since. Approving an edit lets one write through to each file it named, as long as its path still leads to the file that was there when the orchestrator was asked; where there was no file, the write may only create one. When the edit request showed the orchestrator diffs of a file, the write must also be exactly what those diffs make of the file; any other content is asked about anew. Any other terminal or write reaches the orchestrator with its command, arguments, working directory and environment variables (the values of those that make a program load or run code, such as PATH, `PYTHONP