🤖 feat: Add mux acp (stdio ACP bridge) subcommand

bun.lock

@@ -5,6 +5,7 @@
     "": {
       "name": "mux",
       "dependencies": {
+        "@agentclientprotocol/sdk": "^0.12.0",
         "@ai-sdk/amazon-bedrock": "^3.0.61",
         "@ai-sdk/anthropic": "^2.0.47",
         "@ai-sdk/deepseek": "^1.0.31",
@@ -177,6 +178,8 @@
 
     "@adobe/css-tools": ["@adobe/css-tools@4.4.4", "", {}, "sha512-Elp+iwUx5rN5+Y8xLt5/GRoG20WGoDCQ/1Fb+1LiGtvwbDavuSk0jhD/eZdckHAuzcDzccnkv+rEjyWfRx18gg=="],
 
+    "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.12.0", "", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-V8uH/KK1t7utqyJmTA7y7DzKu6+jKFIXM+ZVouz8E55j8Ej2RV42rEvPKn3/PpBJlliI5crcGk1qQhZ7VwaepA=="],
+
     "@ai-sdk/amazon-bedrock": ["@ai-sdk/amazon-bedrock@3.0.65", "", { "dependencies": { "@ai-sdk/anthropic": "2.0.53", "@ai-sdk/provider": "2.0.0", "@ai-sdk/provider-utils": "3.0.18", "@smithy/eventstream-codec": "^4.0.1", "@smithy/util-utf8": "^4.0.0", "aws4fetch": "^1.0.20" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-E5KJv9OvLJitwPo6GnTgYdssTjEbwVW08TXqaQE2C6hfpg6XdwMXc7BJvQ97eXogGETAyFSS0irDYsbA90rB+g=="],
 
     "@ai-sdk/anthropic": ["@ai-sdk/anthropic@2.0.53", "", { "dependencies": { "@ai-sdk/provider": "2.0.0", "@ai-sdk/provider-utils": "3.0.18" }, "peerDependencies": { "zod": "^3.25.76 || ^4.1.8" } }, "sha512-ih7NV+OFSNWZCF+tYYD7ovvvM+gv7TRKQblpVohg2ipIwC9Y0TirzocJVREzZa/v9luxUwFbsPji++DUDWWxsg=="],

docs/acp.mdx

@@ -0,0 +1,84 @@
+---
+title: Agent Client Protocol (ACP)
+description: Use mux as an ACP agent in editors like Zed
+---
+
+`mux acp` starts an **Agent Client Protocol (ACP)** agent over **stdio**.
+
+It acts as a thin bridge to a running mux **HTTP/WebSocket API server**, so editors that support ACP (like Zed) can drive mux workspaces.
+
+## Prerequisites
+
+You need a mux API server running locally:
+
+- **Mux Desktop**: the API server is typically started automatically (unless disabled).
+- **Standalone**: run `mux server`.
+
+Server discovery order:
+
+1. `--server-url` / `--server-token`
+2. `MUX_SERVER_URL` / `MUX_SERVER_AUTH_TOKEN`
+3. `~/.mux/server.lock`
+
+If none are available, `mux acp` will exit with an error.
+
+## Zed setup
+
+Zed can run any ACP agent as a subprocess via `agent_servers`.
+
+Add this to your Zed `settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Mux": {
+      "command": "mux",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Then in Zed, create a new external agent thread and select **Mux**.
+
+### Using a specific mux server
+
+If you want to connect to a specific server instance, add args/env:
+
+```json
+{
+  "agent_servers": {
+    "Mux (custom server)": {
+      "command": "mux",
+      "args": ["acp", "--server-url", "http://127.0.0.1:3000", "--server-token", "<token>"],
+      "env": {}
+    }
+  }
+}
+```
+
+## Notes
+
+- `mux acp` reserves **stdout** for the ACP protocol. Logs go to **stderr**.
+- By default, mux uses the **local** runtime (project directory directly).
+  - For `--runtime worktree|ssh`, you must also pass `--trunk-branch`.
+
+## Troubleshooting
+
+### "No running mux API server found"
+
+- Start mux desktop (ensure API server is enabled), or run:
+
+```bash
+mux server
+```
+
+- Or explicitly set `MUX_SERVER_URL` / `MUX_SERVER_AUTH_TOKEN`.
+
+### Zed shows no output / agent immediately disconnects
+
+Open Zed’s ACP debug logs (Command Palette: `dev: open acp logs`) and look for:
+
+- JSON parsing errors (often means something wrote to stdout)
+- Connection/auth errors to the mux server

docs/cli.mdx

@@ -84,6 +84,16 @@ Options:
 - `--auth-token <token>` - Optional bearer token for authentication
 - `--add-project <path>` - Add and open project at the specified path
 
+## `mux acp`
+
+Start an ACP (Agent Client Protocol) stdio agent for editor integrations (e.g. Zed):
+
+```bash
+mux acp
+```
+
+For setup details, see the **Agent Client Protocol (ACP)** docs.
+
 ## `mux desktop`
 
 Launch the desktop app. This is automatically invoked when running the packaged app or via `electron .`:

docs/docs.json

@@ -48,6 +48,7 @@
               },
               "plan-mode",
               "vscode-extension",
+              "acp",
               "models",
               {
                 "group": "Keyboard Shortcuts",

package.json

@@ -45,6 +45,7 @@
     "postinstall": "sh scripts/postinstall.sh"
   },
   "dependencies": {
+    "@agentclientprotocol/sdk": "^0.12.0",
     "@ai-sdk/amazon-bedrock": "^3.0.61",
     "@ai-sdk/anthropic": "^2.0.47",
     "@ai-sdk/deepseek": "^1.0.31",