feat(cli): add acp attach mode

Author: shekohex

packages/opencode/src/acp/README.md

@@ -42,6 +42,12 @@ opencode acp
 
 # Start in a specific directory
 opencode acp --cwd /path/to/project
+
+# Bridge ACP stdio to an existing OpenCode server
+opencode acp --attach http://localhost:4096
+
+# When attaching, --cwd still applies on the attached server
+opencode acp --attach http://localhost:4096 --cwd /path/to/project
 ```
 
 ### Question Tool Opt-In

packages/opencode/src/cli/cmd/acp.ts

@@ -13,22 +13,22 @@ export const AcpCommand = cmd({
   command: "acp",
   describe: "start ACP (Agent Client Protocol) server",
   builder: (yargs) => {
-    return withNetworkOptions(yargs).option("cwd", {
-      describe: "working directory",
-      type: "string",
-      default: process.cwd(),
-    })
+    return withNetworkOptions(yargs)
+      .option("attach", {
+        type: "string",
+        describe: "attach to a running opencode server (e.g., http://localhost:4096)",
+      })
+      .option("cwd", {
+        describe: "working directory",
+        type: "string",
+        default: process.cwd(),
+      })
   },
   handler: async (args) => {
     process.env.OPENCODE_CLIENT = "acp"
-    await bootstrap(process.cwd(), async () => {
-      const opts = await resolveNetworkOptions(args)
-      const server = Server.listen(opts)
-
-      const sdk = createOpencodeClient({
-        baseUrl: `http://${server.hostname}:${server.port}`,
-      })
+    const dir = args.cwd
 
+    async function execute(sdk: ReturnType<typeof createOpencodeClient>) {
       const input = new WritableStream<Uint8Array>({
         write(chunk) {
           return new Promise<void>((resolve, reject) => {
@@ -65,6 +65,24 @@ export const AcpCommand = cmd({
         process.stdin.on("end", resolve)
         process.stdin.on("error", reject)
       })
+    }
+
+    if (args.attach) {
+      const sdk = createOpencodeClient({
+        baseUrl: args.attach,
+        directory: dir,
+      })
+      return await execute(sdk)
+    }
+
+    await bootstrap(dir, async () => {
+      const opts = await resolveNetworkOptions(args)
+      const server = Server.listen(opts)
+      const sdk = createOpencodeClient({
+        baseUrl: `http://${server.hostname}:${server.port}`,
+        directory: dir,
+      })
+      return await execute(sdk)
     })
   },
 })

packages/web/src/content/docs/acp.mdx

@@ -19,6 +19,8 @@ To use OpenCode via ACP, configure your editor to run the `opencode acp` command
 
 The command starts OpenCode as an ACP-compatible subprocess that communicates with your editor over JSON-RPC via stdio.
 
+You can also run `opencode acp --attach <url>` to bridge ACP stdio to an existing OpenCode server instead of starting a local backend. `--cwd` still applies when attaching, and the path is interpreted on the attached server.
+
 Below are examples for popular editors that support ACP.
 
 ---

packages/web/src/content/docs/cli.mdx

@@ -479,13 +479,26 @@ opencode acp
 
 This command starts an ACP server that communicates via stdin/stdout using nd-JSON.
 
+You can also attach to a running `opencode serve` instance to bridge ACP stdio to it instead of starting a local backend:
+
+```bash
+# Start a headless server in one terminal
+opencode serve
+
+# In another terminal, bridge ACP stdio to it
+opencode acp --attach http://localhost:4096
+```
+
+When attaching, `--cwd` still applies, but the path is interpreted on the attached server.
+
 #### Flags
 
-| Flag         | Description           |
-| ------------ | --------------------- |
-| `--cwd`      | Working directory     |
-| `--port`     | Port to listen on     |
-| `--hostname` | Hostname to listen on |
+| Flag         | Description                                                   |
+| ------------ | ------------------------------------------------------------- |
+| `--cwd`      | Working directory                                             |
+| `--attach`   | Attach to a running opencode server (e.g. http://localhost:4096) |
+| `--port`     | Port to listen on                                             |
+| `--hostname` | Hostname to listen on                                         |
 
 ---
 

packages/web/src/content/docs/pl/acp.mdx

@@ -21,6 +21,8 @@ Aby używać OpenCode przez ACP, skonfiguruj swój edytor tak, aby uruchamiał p
 
 Uruchamia to OpenCode jako podproces zgodny z ACP, który komunikuje się z edytorem za pomocą JSON-RPC przez stdio.
 
+Możesz też uruchomić `opencode acp --attach <url>`, aby zmostkować stdio ACP do istniejącego serwera OpenCode zamiast uruchamiać lokalny backend. Podczas podłączania `--cwd` nadal działa, ale ścieżka jest interpretowana na podłączonym serwerze.
+
 Poniżej znajdują się przykłady dla edytorów obsługujących ACP.
 
 ---

packages/web/src/content/docs/pl/cli.mdx

@@ -479,13 +479,26 @@ opencode acp
 
 Uruchamia serwer ACP, który komunikuje się przez stdin/stdout przy użyciu JSON-RPC.
 
+Możesz też podłączyć się do działającego `opencode serve`, aby zmostkować stdio ACP do istniejącego serwera zamiast uruchamiać lokalny backend:
+
+```bash
+# Start a headless server in one terminal
+opencode serve
+
+# In another terminal, bridge ACP stdio to it
+opencode acp --attach http://localhost:4096
+```
+
+Podczas podłączania `--cwd` nadal działa, ale ścieżka jest interpretowana na podłączonym serwerze.
+
 #### Flagi
 
-| Flaga        | Opis                                       |
-| ------------ | ------------------------------------------ |
-| `--cwd`      | Katalog roboczy                            |
-| `--port`     | Port do nasłuchiwania                      |
-| `--hostname` | Nazwa hosta, do której należy się powiązać |
+| Flaga        | Opis                                                          |
+| ------------ | ------------------------------------------------------------- |
+| `--cwd`      | Katalog roboczy                                               |
+| `--attach`   | Dołącz do działającego serwera OpenCode (np. http://localhost:4096) |
+| `--port`     | Port do nasłuchiwania                                         |
+| `--hostname` | Nazwa hosta, do której należy się powiązać                    |
 
 ---
 

packages/web/src/content/docs/tr/acp.mdx

@@ -19,6 +19,8 @@ opencode'u ACP aracılığıyla kullanmak için düzenleyicinizi `opencode acp`
 
 Komut, opencode'u, editörünüzle stdio aracılığıyla JSON-RPC üzerinden iletişim kuran ACP uyumlu bir alt süreç olarak başlatır.
 
+Yerel bir arka uç başlatmak yerine ACP stdio'yu mevcut bir OpenCode sunucusuna köprülemek için `opencode acp --attach <url>` komutunu da çalıştırabilirsiniz. Bağlanırken `--cwd` yine geçerlidir, ancak yol bağlı sunucuda yorumlanır.
+
 Aşağıda ACP'yi destekleyen popüler düzenleyicilere ilişkin örnekler verilmiştir.
 
 ---

packages/web/src/content/docs/tr/cli.mdx

@@ -479,13 +479,26 @@ opencode acp
 
 Bu komut, nd-JSON kullanarak stdin/stdout aracılığıyla iletişim kuran bir ACP sunucusunu başlatır.
 
+Yerel bir arka uç başlatmak yerine ACP stdio'yu mevcut bir sunucuya köprülemek için çalışan bir `opencode serve` örneğine de bağlanabilirsiniz:
+
+```bash
+# Start a headless server in one terminal
+opencode serve
+
+# In another terminal, bridge ACP stdio to it
+opencode acp --attach http://localhost:4096
+```
+
+Bağlanırken `--cwd` yine geçerlidir, ancak yol bağlı sunucuda yorumlanır.
+
 #### Bayraklar
 
-| Bayrak       | Açıklama            |
-| ------------ | ------------------- |
-| `--cwd`      | Çalışma dizini      |
-| `--port`     | Dinlenecek port     |
-| `--hostname` | Dinlenecek host adı |
+| Bayrak       | Açıklama                                                      |
+| ------------ | ------------------------------------------------------------- |
+| `--cwd`      | Çalışma dizini                                                |
+| `--attach`   | Çalışan bir opencode sunucusuna bağlanın (ör. http://localhost:4096) |
+| `--port`     | Dinlenecek port                                               |
+| `--hostname` | Dinlenecek host adı                                           |
 
 ---
 

packages/web/src/content/docs/zh-cn/acp.mdx

@@ -19,6 +19,8 @@ ACP 是一个开放协议，用于标准化代码编辑器与 AI 编码代理之
 
 该命令会将 OpenCode 作为兼容 ACP 的子进程启动，通过 stdio 上的 JSON-RPC 与编辑器进行通信。
 
+你也可以运行 `opencode acp --attach <url>`，将 ACP 的 stdio 桥接到现有的 OpenCode 服务器，而不是启动本地后端。连接时，`--cwd` 仍然生效，但该路径会在所连接的服务器上解析。
+
 以下是支持 ACP 的常用编辑器的配置示例。
 
 ---

packages/web/src/content/docs/zh-cn/cli.mdx

@@ -479,13 +479,26 @@ opencode acp
 
 此命令启动一个通过 stdin/stdout 使用 nd-JSON 进行通信的 ACP 服务器。
 
+您也可以连接到正在运行的 `opencode serve` 实例，将 ACP 的 stdio 桥接到该实例，而不是启动本地后端：
+
+```bash
+# Start a headless server in one terminal
+opencode serve
+
+# In another terminal, bridge ACP stdio to it
+opencode acp --attach http://localhost:4096
+```
+
+连接时，`--cwd` 仍然生效，但该路径会在所连接的服务器上解析。
+
 #### 标志
 
-| 标志         | 描述       |
-| ------------ | ---------- |
-| `--cwd`      | 工作目录   |
-| `--port`     | 监听端口   |
-| `--hostname` | 监听主机名 |
+| 标志         | 描述                                                   |
+| ------------ | ------------------------------------------------------ |
+| `--cwd`      | 工作目录                                               |
+| `--attach`   | 连接到正在运行的 opencode 服务器（例如 http://localhost:4096） |
+| `--port`     | 监听端口                                               |
+| `--hostname` | 监听主机名                                             |
 
 ---