cursor-local-acp

# Agent Local ACP Bridge [中文文档](README.zh-CN.md) Unofficial [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) adapter for Cursor Agent Local. It lets ACP clients, such as JetBrains IDEs, connect to Cursor's local coding agent while Agent Local sends model requests to the OpenAI-compatible provider that you configure. ```text ACP client | ACP over stdio v agent-local-acp-bridge | agent-local --print --output-format stream-json v Cursor Agent Local -----> OpenAI-compatible provider ``` This project is not affiliated with or endorsed by Cursor, Anysphere, xAI, or any model provider. ## What This Bridge Does Cursor Agent Local can run through `agent-local --print` and emit machine-readable `stream-json` events. This bridge: 1. Implements an ACP server for clients such as JetBrains IDEs. 2. Starts `agent-local --print --output-format stream-json` behind the scenes. 3. Maps Agent Local events to ACP messages, tool calls, status updates, and usage data. This avoids native `agent-local acp` startup failures that can happen in some BYOK/authless setups while keeping Agent Local's context, tool execution, and image input behavior. ## `agent-local` vs the regular Cursor CLI These are easy to confuse: | Command | Source | Main purpose | Used by this project | | --- | --- | --- | --- | | `agent` | Public Cursor CLI shown on Cursor's CLI page | Terminal Cursor Agent and automation scripts | No | | `agent-local` / `cursor-agent-local` | Cursor Agent Local package | Local Agent Local entry point with `--print`, `stream-json`, `--image`, and related flags | Yes | Installing the regular Cursor CLI alone may not install `agent-local`. This bridge depends on `agent-local` because it emits the `stream-json` events that the bridge parses. ## Features - ACP stdio server implemented with the official ACP TypeScript SDK. - OpenAI-compatible provider base URL, API key, and arbitrary model IDs. - Cursor-authless BYOK mode, with optional use of an existing Cursor login. - Streaming assistant text, reasoning chunks, tool calls, background task status, and token usage. - Session create, load, resume, list, close, delete, and metadata persistence. - ACP modes for code, plan, and ask workflows. - Runtime ACP configuration for model, authless mode, and force mode. - Prompt content support for text, images, resource links, and embedded resources. - Image handling for inline ACP images, embedded image resources, `file://`/local-path image links, and image links embedded in Markdown text. - ACP-provided stdio, HTTP, and SSE MCP servers converted to temporary Cursor plugins for each turn. - Output cleanup for duplicate partial messages, raw `<think>` blocks, and noisy connection-status events. - Windows-safe process launch without interpolating prompts through `cmd.exe`. ## Quick Start Follow these steps in order. ### 1. Install Node.js Node.js 20 or newer is required: ```bash node --version npm --version ``` ### 2. Install Agent Local This bridge requires the `agent-local` command. Windows PowerShell: ```powershell irm 'https://cursor.com/internal-local-install-nHZIc6RZgTXIfai0aO?win32=true&channel=prod' | iex ``` macOS / Linux: ```bash curl -fsSL 'https://cursor.com/internal-local-install-nHZIc6RZgTXIfai0aO?darwin=true&channel=prod' | bash ``` Notes: - On Windows, the installer installs `cursor-agent-local` and creates `agent-local.exe`, `agent-local.cmd`, and `agent-local.ps1` aliases. - On Windows, the default install directory is `%LOCALAPPDATA%\cursor-agent-local`, and the script attempts to add it to the user `PATH`. - On macOS/Linux, the installer uses `~/.local/share/cursor-agent-local` and creates `agent-local` and `cursor-agent-local` symlinks in `~/.local/bin`. - If a new terminal cannot find `agent-local`, add the relevant directory to `PATH` or restart the terminal. - These commands execute remote installer scripts. If your environment requires stricter controls, download and inspect the script before running it. Verify the command is available: ```bash agent-local --help ``` ### 3. Verify Agent Local can reach your provider This validates Agent Local and your model provider, not the bridge. Windows PowerShell: ```powershell $env:CURSOR_LOCAL_AGENT_BASE_URL = "https://api.example.com/v1" $env:CURSOR_LOCAL_AGENT_API_KEY = "your-provider-key" agent-local --authless --model "grok-4.5" --print "Only reply OK" ``` If this fails, fix Agent Local, the base URL, the API key, or the model ID first. The bridge does not rewrite provider HTTP behavior and cannot make an unsupported provider compatible. ### 4. Build the bridge ```bash git clone <repository-url> cd agent-local-acp-bridge npm ci npm run build ``` `dist/cli.js` is the entry point launched by the ACP client. Re-run `npm run build` after changing TypeScript source files. ### 5. Optional bridge self-check ```bash node dist/cli.js --doctor --model "grok-4.5" --authless ``` `--doctor` is useful for catching local setup mistakes: - whether `dist/cli.js` starts; - whether CLI arguments parse correctly; - whether `agent-local` can be resolved; - whether a supplied `--base-url` is syntactically valid; - whether the selected model, authless flag, state directory, temp directory, and API-key presence look as expected. It does not call the model provider, consume tokens, validate the API key, or prove that the model ID is supported. Treat it as a recommended local sanity check, not a required model test. ### 6. Configure your ACP client JetBrains custom ACP agent example: ```json { "Cursor Agent Local": { "command": "node", "args": [ "C:\\path\\to\\agent-local-acp-bridge\\dist\\cli.js", "--model", "grok-4.5", "--authless" ], "env": { "CURSOR_LOCAL_AGENT_BASE_URL": "https://api.example.com/v1", "CURSOR_LOCAL_AGENT_API_KEY": "REPLACE_WITH_YOUR_KEY", "AGENT_LOCAL_MODELS": "grok-4.5" } } } ``` On macOS/Linux, replace the script path with a POSIX path such as `/path/to/agent-local-acp-bridge/dist/cli.js`. A ready-to-edit generic example is available at [`examples/jetbrains.openai-compatible.json`](examples/jetbrains.openai-compatible.json). Keep real API keys in your ACP client's environment map or a secret manager. Do not commit credentials. ## Cursor Login Modes The model provider and Cursor login are separate settings: | Setting | Behavior | | --- | --- | | `AGENT_LOCAL_AUTHLESS=true` | Does not use Cursor account-backed session services. Recommended for pure BYOK. | | `AGENT_LOCAL_AUTHLESS=false` | Allows an existing Agent Local/Cursor login to provide auxiliary services. Provider variables are still inherited by Agent Local. | Complete any Cursor login interactively before starting an ACP process. The bridge intentionally does not collect or proxy Cursor credentials. ## Common Configuration Environment variables are the preferred configuration mechanism. CLI flags override the corresponding environment values. | Variable | Default | Purpose | | --- | --- | --- | | `CURSOR_LOCAL_AGENT_BASE_URL` | Agent Local default | OpenAI-compatible `/v1` base URL. | | `CURSOR_LOCAL_AGENT_API_KEY` | unset | Provider API key. | | `AGENT_LOCAL_COMMAND` | `agent-local` | Executable name or absolute `agent-local.ps1` path. | | `AGENT_LOCAL_MODEL` | `gpt-5.5` | Default model ID. | | `AGENT_LOCAL_MODELS` | default model | Comma-separated model IDs shown in ACP. | | `AGENT_LOCAL_AUTHLESS` | `true` | Add `--authless`. | | `AGENT_LOCAL_FORCE` | `false` | Add `--force` for non-interactive tool execution. | | `AGENT_LOCAL_TRUST` | `true` | Add `--trust` to avoid a workspace-trust prompt. | | `AGENT_LOCAL_APPROVE_MCPS` | `true` | Add `--approve-mcps` for client MCP servers. | | `AGENT_LOCAL_SINGLE_TURN` | `false` | Add `--single-turn`. | | `AGENT_LOCAL_STREAM_PARTIAL_OUTPUT` | `true` | Stream token-level output and remove aggregate duplicates. | | `AGENT_LOCAL_DISABLE_AUTO_UPDATE` | `true` | Keep the ACP-launched binary stable. | | `AGENT_LOCAL_SANDBOX` | unset | `enabled` or `disabled`. | | `AGENT_LOCAL_BRIDGE_STATE_DIR` | `~/.agent-local-acp-bridge` | Session metadata directory. | | `AGENT_LOCAL_BRIDGE_TEMP_DIR` | OS temp directory | Temporary image and MCP plugin directory. | | `AGENT_LOCAL_BRIDGE_LOG_LEVEL` | `info` | `silent`, `error`, `warn`, `info`, or `debug`. | | `AGENT_LOCAL_MAX_STDERR_BYTES` | `131072` | Maximum stderr retained per Agent Local run. | Run `node dist/cli.js --help` for all flags. ## Permission Model Agent Local's `stream-json` print interface can emit interaction-query events, but it does not expose a supported input channel for forwarding an ACP permission response back into that running turn. Therefore the bridge cannot provide native ACP permission dialogs for individual Cursor tool calls. Workspace trust is enabled by default to prevent startup prompts that would make headless ACP processes exit. `force` remains disabled by default. Enable `AGENT_LOCAL_FORCE=true` only for repositories and MCP servers you trust. ## Privacy and Repository Hygiene - The bridge does not persist provider API keys or Cursor credentials. - Temporary MCP plugin files can contain MCP environment values and headers for the duration of a prompt turn, then they are removed. - Session metadata stores workspace paths, model/mode flags, timestamps, title, and the last request ID. Do not publish local state directories. - Keep `.env`, IDE metadata, build output, logs, and temporary state out of source control. The included `.gitignore` covers common local files. Before publishing, run a scan similar to: ```powershell rg -n --hidden --glob '!node_modules/**' --glob '!dist/**' ` "C:\\Users|AppData|file:///|sk-[A-Za-z0-9]|api[_-]?key|https://your-private-host" . ``` ## Known Limitations - Loading or resuming continues the Agent Local session, but previous chat messages cannot be replayed into the ACP client through the print interface. - ACP-transport MCP servers cannot be converted to a Cursor plugin. Stdio, HTTP, and SSE transports are supported. - Tool descriptions are derived from Cursor's evolving stream event payloads; unknown tool variants are reported as `other` rather than discarded. - Compatibility depends on the installed Agent Local CLI and may require an adapter update after Cursor changes its private stream format. ## Development ```bash npm run typecheck npm test npm run build npm run check ``` Tests include an in-process ACP client/server negotiation using the official SDK and a fake Agent Local stream, so protocol behavior is verified without calling a paid model endpoint. See [Architecture](docs/ARCHITECTURE.md), [Contributing](CONTRIBUTING.md), and [Security Policy](SECURITY.md) for more detail. ## License MIT ## Community This open-source project has been linked and recognized [LINUX DO 社区](https://linux.do)