ACP Proxy Server

A WebSocket proxy server that bridges Chrome extensions to ACP (Agent Client Protocol) agents.

Part of the chrome-acp monorepo.

Installation

From npm

npm install -g @chrome-acp/proxy-server

From source

# From monorepo root
bun install

Usage

Via npx

npx @chrome-acp/proxy-server /path/to/agent

Via global install

acp-proxy /path/to/agent

Via source

bun src/cli/bin.ts /path/to/agent

Examples

# Basic usage
acp-proxy /path/to/agent

# With custom port
acp-proxy --port 9000 /path/to/agent

# With debug logging
acp-proxy --debug /path/to/agent

# Pass arguments to the agent (use -- to separate)
acp-proxy /path/to/agent -- --verbose --model gpt-4

CLI Reference

USAGE
  acp-proxy [--port value] [--debug] <command>...
  acp-proxy --help
  acp-proxy --version

FLAGS
     [--port]    Port to listen on                  [default = 9315]
     [--debug]   Enable debug logging
  -h  --help     Print help information and exit
  -v  --version  Print version information and exit

ARGUMENTS
  command...  Agent command followed by its arguments

How It Works

The proxy server:

1. Listens for WebSocket connections from the Chrome extension
2. When a "connect" message is received, spawns the configured ACP agent as a subprocess
3. Bridges messages between the WebSocket (extension) and stdin/stdout (agent)
4. Exposes browser tools to agents via MCP (Model Context Protocol)

This allows Chrome extensions to communicate with ACP agents despite not being able to spawn subprocesses directly.

Browser Tools (via MCP)

The proxy server exposes an MCP endpoint at http://localhost:{port}/mcp with these tools:

| Tool | Description | |------|-------------| | browser_tabs | List all open tabs (returns id, url, title, active status) | | browser_read | Read content of a specific tab (requires tabId from browser_tabs) | | browser_execute | Execute JavaScript in a specific tab (requires tabId from browser_tabs) |

License

MIT