Skip to content

docs: fix Zed config schema and add cross-platform ZCODE_BIN paths #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
william0wang merged 1 commit into from
Jul 5, 2026
Merged

docs: fix Zed config schema and add cross-platform ZCODE_BIN paths #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 45 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,35 +35,57 @@ The compiled entry point is `dist/index.js` (also exposed as the

## Configure Zed

Add the server to Zed as an external agent. In `~/.config/zed/settings.json`:
Add the server to Zed as a custom agent server. In `~/.config/zed/settings.json`
(`%APPDATA%\Zed\settings.json` on Windows):
Comment on lines +38 to +39

@gemini-code-assist gemini-code-assist Bot Jul 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

On Windows, Zed stores its global configuration in %LOCALAPPDATA%\Zed\settings.json rather than %APPDATA%\Zed\settings.json (which points to the Roaming directory). Let's update this path to ensure Windows users can find their settings file correctly.

Suggested change
Add the server to Zed as a custom agent server. In `~/.config/zed/settings.json`
(`%APPDATA%\Zed\settings.json` on Windows):
Add the server to Zed as a custom agent server. In `~/.config/zed/settings.json`
(`%LOCALAPPDATA%\Zed\settings.json` on Windows):


```jsonc
{
"assistant": {
"entitled": true
"agent_servers": {
"ZCode": {
"type": "custom",
"command": "node",
"args": ["/absolute/path/to/zcode-acp-server/dist/index.js"],
"env": {
// Point at the ZCode CLI bundled inside the desktop app (not on PATH by default).
// See the platform-specific path below.
"ZCODE_BIN": "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
},
},
},
"acp": {
"agents": [
{
"name": "zcode",
"command": { "path": "node", "args": ["/absolute/path/to/zcode-acp-server/dist/index.js"] }
}
]
}
}
```

Restart Zed and pick **ZCode** from the agent dropdown.

### `ZCODE_BIN` per platform

The ZCode CLI ships inside the desktop app and is not added to `PATH`
automatically. Point `ZCODE_BIN` at the bundled `zcode.cjs`:

| Platform | `ZCODE_BIN` path |
| ----------- | --------------------------------------------------------------------------- |
| **macOS** | `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs` |
| **Windows** | `%LOCALAPPDATA%\Programs\ZCode\resources\glm\zcode.cjs` |
| **Linux** | Inside the extracted app directory: `<install-dir>/resources/glm/zcode.cjs` |

> If the path doesn't match your install, locate it with:
>
> ```bash
> # macOS / Linux
> find / -name zcode.cjs -path '*resources/glm*' 2>/dev/null
> # Windows (PowerShell)
> Get-ChildItem -Path $env:LOCALAPPDATA,$env:APPDATA,'C:\Program Files' -Recurse -Filter zcode.cjs -ErrorAction SilentlyContinue

@gemini-code-assist gemini-code-assist Bot Jul 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Running Get-ChildItem -Recurse on the entire $env:LOCALAPPDATA and C:\Program Files directories can be extremely slow, potentially taking several minutes and causing high CPU/disk usage. Since ZCode is typically installed in a ZCode subdirectory within these locations, we can restrict the search path to those specific folders to make the command run almost instantly.

Suggested change
> Get-ChildItem -Path $env:LOCALAPPDATA,$env:APPDATA,'C:\Program Files' -Recurse -Filter zcode.cjs -ErrorAction SilentlyContinue
Get-ChildItem -Path "$env:LOCALAPPDATA\Programs\ZCode", "$env:ProgramFiles\ZCode", "${env:ProgramFiles(x86)}\ZCode" -Recurse -Filter zcode.cjs -ErrorAction SilentlyContinue

> ```

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `ZCODE_BIN` | `zcode` | Path to the ZCode CLI binary or its `.cjs` entry |
| `ZCODE_NODE` | _(discovered)_ | Explicit Node binary to run `ZCODE_BIN` with (must support `node:sqlite`) |
| `ZCODE_MODEL` | _(from config)_ | Override the active model id |
| `ZCODE_BASE_URL` | _(from config)_ | Override the provider base URL |
| `ZCODE_ACP_DEBUG` | _(unset)_ | Set to `1` to enable verbose diagnostic logs (event flow, probe loops, status updates). Default is quiet — only warnings (backend pipe errors, command/permission failures, lock timeouts) are emitted. Enable this when diagnosing bridge issues; the logs appear in `Zed.log` prefixed with `[zcode-acp]`. |
| Variable | Default | Purpose |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ZCODE_BIN` | `zcode` | Path to the ZCode CLI binary or its `.cjs` entry |
| `ZCODE_NODE` | _(discovered)_ | Explicit Node binary to run `ZCODE_BIN` with (must support `node:sqlite`) |
| `ZCODE_MODEL` | _(from config)_ | Override the active model id |
| `ZCODE_BASE_URL` | _(from config)_ | Override the provider base URL |
| `ZCODE_ACP_DEBUG` | _(unset)_ | Set to `1` to enable verbose diagnostic logs (event flow, probe loops, status updates). Default is quiet — only warnings (backend pipe errors, command/permission failures, lock timeouts) are emitted. Enable this when diagnosing bridge issues; the logs appear in `Zed.log` prefixed with `[zcode-acp]`. |

## Develop

Expand Down Expand Up @@ -100,11 +122,11 @@ See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full architecture docum

## Version Compatibility

| ZCode CLI version | Support | Notes |
|:-----------------:|:-------:|------|
| **>= 0.15.0** | Full | All extension methods available |
| **>= 0.14.8** | Full | Event-stream push, all extension methods |
| **< 0.14.8** | Incompatible | Event-stream subscription unavailable |
| ZCode CLI version | Support | Notes |
| :---------------: | :----------: | ---------------------------------------- |
| **>= 0.15.0** | Full | All extension methods available |
| **>= 0.14.8** | Full | Event-stream push, all extension methods |
| **< 0.14.8** | Incompatible | Event-stream subscription unavailable |

## Documentation

Expand Down
68 changes: 45 additions & 23 deletions README.zh-CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,35 +34,57 @@ ACP 客户端里配置启动它 —— 见下方的 **在 Zed 中配置** 或你

## 在 Zed 中配置

将本服务端作为外部 agent 添加到 Zed。在 `~/.config/zed/settings.json` 中：
将本服务端作为自定义 agent server 添加到 Zed。在 `~/.config/zed/settings.json`
（Windows 上为 `%APPDATA%\Zed\settings.json`）中：
Comment on lines +37 to +38

@gemini-code-assist gemini-code-assist Bot Jul 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

On Windows, Zed stores its global configuration in %LOCALAPPDATA%\Zed\settings.json rather than %APPDATA%\Zed\settings.json (which points to the Roaming directory). Let's update this path to ensure Windows users can find their settings file correctly.

Suggested change
将本服务端作为自定义 agent server 添加到 Zed。在 `~/.config/zed/settings.json`
（Windows 上为 `%APPDATA%\Zed\settings.json`）中：
将本服务端作为自定义 agent server 添加到 Zed。在 `~/.config/zed/settings.json`
（Windows 上为 `%LOCALAPPDATA%\Zed\settings.json`）中：


```jsonc
{
"assistant": {
"entitled": true
"agent_servers": {
"ZCode": {
"type": "custom",
"command": "node",
"args": ["/absolute/path/to/zcode-acp-server/dist/index.js"],
"env": {
// 指向桌面应用内置的 ZCode CLI（默认不在 PATH 上）。
// 各平台路径见下方表格。
"ZCODE_BIN": "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
},
},
},
"acp": {
"agents": [
{
"name": "zcode",
"command": { "path": "node", "args": ["/absolute/path/to/zcode-acp-server/dist/index.js"] }
}
]
}
}
```

重启 Zed，然后从 agent 下拉菜单中选择 **ZCode**。

### 各平台的 `ZCODE_BIN` 路径

ZCode CLI 内置于桌面应用中，默认不会加到 `PATH`。用 `ZCODE_BIN` 指向内置的
`zcode.cjs`：

| 平台 | `ZCODE_BIN` 路径 |
| ----------- | ---------------------------------------------------------- |
| **macOS** | `/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs` |
| **Windows** | `%LOCALAPPDATA%\Programs\ZCode\resources\glm\zcode.cjs` |
| **Linux** | 解压后的应用目录内：`<安装目录>/resources/glm/zcode.cjs` |

> 如果路径与实际安装不符，可用以下命令定位：
>
> ```bash
> # macOS / Linux
> find / -name zcode.cjs -path '*resources/glm*' 2>/dev/null
> # Windows (PowerShell)
> Get-ChildItem -Path $env:LOCALAPPDATA,$env:APPDATA,'C:\Program Files' -Recurse -Filter zcode.cjs -ErrorAction SilentlyContinue

@gemini-code-assist gemini-code-assist Bot Jul 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Running Get-ChildItem -Recurse on the entire $env:LOCALAPPDATA and C:\Program Files directories can be extremely slow, potentially taking several minutes and causing high CPU/disk usage. Since ZCode is typically installed in a ZCode subdirectory within these locations, we can restrict the search path to those specific folders to make the command run almost instantly.

Suggested change
> Get-ChildItem -Path $env:LOCALAPPDATA,$env:APPDATA,'C:\Program Files' -Recurse -Filter zcode.cjs -ErrorAction SilentlyContinue
Get-ChildItem -Path "$env:LOCALAPPDATA\Programs\ZCode", "$env:ProgramFiles\ZCode", "${env:ProgramFiles(x86)}\ZCode" -Recurse -Filter zcode.cjs -ErrorAction SilentlyContinue

> ```

## 环境变量

| 变量 | 默认值 | 用途 |
|----------|---------|---------|
| `ZCODE_BIN` | `zcode` | ZCode CLI 二进制文件路径或其 `.cjs` 入口 |
| `ZCODE_NODE` | _（自动发现）_ | 显式指定运行 `ZCODE_BIN` 的 Node 二进制（必须支持 `node:sqlite`）|
| `ZCODE_MODEL` | _（来自 config）| 覆盖当前使用的模型 id |
| `ZCODE_BASE_URL` | _（来自 config）| 覆盖 provider 的 base URL |
| `ZCODE_ACP_DEBUG` | _（未设置）| 设为 `1` 可开启详细诊断日志（事件流、探测循环、状态更新）。默认安静——只输出警告类日志（后端管道错误、命令/权限失败、锁等待超时）。诊断桥接问题时开启；日志出现在 `Zed.log` 中，前缀为 `[zcode-acp]`。 |
| 变量 | 默认值 | 用途 |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ZCODE_BIN` | `zcode` | ZCode CLI 二进制文件路径或其 `.cjs` 入口 |
| `ZCODE_NODE` | _（自动发现）_ | 显式指定运行 `ZCODE_BIN` 的 Node 二进制（必须支持 `node:sqlite`） |
| `ZCODE_MODEL` | _（来自 config） | 覆盖当前使用的模型 id |
| `ZCODE_BASE_URL` | _（来自 config） | 覆盖 provider 的 base URL |
| `ZCODE_ACP_DEBUG` | _（未设置） | 设为 `1` 可开启详细诊断日志（事件流、探测循环、状态更新）。默认安静——只输出警告类日志（后端管道错误、命令/权限失败、锁等待超时）。诊断桥接问题时开启；日志出现在 `Zed.log` 中，前缀为 `[zcode-acp]`。 |

## 开发

Expand Down Expand Up @@ -98,11 +120,11 @@ CI 会在每次 push 和 pull request 时运行 `typecheck`、`lint`、`build`

## 版本兼容性

| ZCode CLI 版本 | 支持 | 说明 |
|:-----------------:|:-------:|------|
| **>= 0.15.0** | 完整 | 所有扩展方法可用 |
| **>= 0.14.8** | 完整 | 事件流推送、所有扩展方法 |
| **< 0.14.8** | 不兼容 | 无事件流订阅能力 |
| ZCode CLI 版本 | 支持 | 说明 |
| :------------: | :----: | ------------------------ |
| **>= 0.15.0** | 完整 | 所有扩展方法可用 |
| **>= 0.14.8** | 完整 | 事件流推送、所有扩展方法 |
| **< 0.14.8** | 不兼容 | 无事件流订阅能力 |

## 文档

Expand Down
43 changes: 18 additions & 25 deletions docs/DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,26 +47,27 @@ node dist/index.js
```

Then manually send an ACP JSON-RPC request:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": 1 } }
```

### Method 2: Connect via Zed

Add the following to `~/.config/zed/settings.json`:
Add the following to `~/.config/zed/settings.json` (see the README for the
full `ZCODE_BIN` per-platform paths):

```json
{
"acp": {
"agents": [
{
"name": "zcode",
"command": {
"path": "node",
"args": ["/absolute/path/to/zcode-acp-server/dist/index.js"]
}
"agent_servers": {
"ZCode": {
"type": "custom",
"command": "node",
"args": ["/absolute/path/to/zcode-acp-server/dist/index.js"],
"env": {
"ZCODE_BIN": "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs"
}
]
}
}
}
```
Expand All @@ -78,15 +79,12 @@ Restart Zed and pick **ZCode** from the agent dropdown.
See `tests/backend.test.ts` for how to mock `ZcodeBackend`:

```typescript
import { describe, it, expect, vi } from 'vitest';
import { ZcodeBackend } from '../src/backend/client.js';

describe('backend', () => {
it('should handle request/response', async () => {
const backend = new ZcodeBackend(
['node', 'mock-zcode.js'],
{ ...process.env }
);
import { describe, it, expect, vi } from "vitest";
import { ZcodeBackend } from "../src/backend/client.js";

describe("backend", () => {
it("should handle request/response", async () => {
const backend = new ZcodeBackend(["node", "mock-zcode.js"], { ...process.env });
// test logic
});
});
Expand Down Expand Up @@ -144,12 +142,7 @@ export async function customAction(
const zcodeSid = resolveSidOrThrow(server, params);
const resp = await server
.ensureBackend()
.request(
server.nextId(),
"session/customAction",
{ sessionId: zcodeSid, ...params },
15000,
);
.request(server.nextId(), "session/customAction", { sessionId: zcodeSid, ...params }, 15000);
if (resp.error) throw new Error(`customAction failed: ${resp.error.message}`);
log("session/customAction -> ok");
return (resp.result ?? {}) as Result;
Expand Down
Loading