### Initial setup: install and enable a plugin for first-time debugging

Source: https://github.com/zai-org/zcode/blob/main/UI_PLUGIN.md

Sets up a development environment by building the plugin repository and installing a specific plugin (excalidraw) into the ZCode host using the CLI. Requires setting ZCODE_REPO and PLUGINS_REPO to your checkout paths. Uses Node.js 24.14.0 and pnpm 10.33.2. The commands are for macOS/Linux; Windows can set the same environment variables in PowerShell.

```shell
ZCODE_REPO=/path/to/z-code
PLUGINS_REPO=/path/to/zcode-plugins

# 可选隔离开发配置；后续 CLI 和桌面启动保持同一个值。
export ZCODE_DATA_BASE_DIR="$HOME/.zcode-ui-plugin-dev"

# 主仓库首次初始化；已完成时跳过。
cd "$ZCODE_REPO"
pnpm bootstrap

# 插件仓库：编译并生成本地目录，不会自动注册或安装插件。
cd "$PLUGINS_REPO"
pnpm install --frozen-lockfile
pnpm build

# 主仓库：使用刚构建的 CLI，将插件装进同一个开发配置。
cd "$ZCODE_REPO"
node apps/zcode-cli/packages/cli/dist/zcode.cjs plugins marketplace add "$PLUGINS_REPO/dist/local-marketplace" --scope user
node apps/zcode-cli/packages/cli/dist/zcode.cjs plugins install excalidraw@zcode-plugins-local --scope user
node apps/zcode-cli/packages/cli/dist/zcode.cjs plugins enable excalidraw@zcode-plugins-local --scope user
node apps/zcode-cli/packages/cli/dist/zcode.cjs plugins list --json
pnpm dev:desktop
```

--------------------------------

### Lifecycle and mode boundaries for Windows Helper

Source: https://github.com/zai-org/zcode/blob/main/docs/superpowers/specs/2026-08-04-windows-cua-upstream-main-forward-port-design.md

ASCII diagram showing the lifecycle when desktop-local with win32 and official plugin enabled, and the boundary for remote environments where the helper is not installed or started.

```text
desktop-local + win32 + official plugin enabled
        |
        v
Host resolves verified packaged runtime
        |
        v
spawn Electron Node child
  argv: entry / socket / parent-pid
  env : bearer token（不进入 argv/日志）
        |
        v
ready + health exact PID evidence
        |
        v
Agent receives broker credentials
        |
        v
30-tool continuous local CUA

SSH / WSL / Docker / remote workspace / mobile /remote
        |
        `--> 不安装、不暂存、不启动独立 Windows Helper
```

--------------------------------

### Clean and start dev:desktop

Source: https://github.com/zai-org/zcode/blob/main/docs/migration/start-guide.md

Recommended startup sequence: clean caches, return to project root, set Node.js memory limit, and launch the desktop dev server.

```bash
# 清理缓存
cd packages/desktop
rm -rf node_modules/.vite .vite

# 回到项目根目录
cd ../..

# 增加内存限制并启动
$env:NODE_OPTIONS="--max-old-space-size=4096"
pnpm run dev:desktop
```

--------------------------------

### Start Desktop test environment

Source: https://github.com/zai-org/zcode/blob/main/docs/testing/workspace-hook-trust-manual-acceptance.md

Starts the Desktop app for the UAT after recording the workspace path.

```bash
pnpm dev:desktop:test
```

--------------------------------

### Staging pipeline for Windows CUA runtime

Source: https://github.com/zai-org/zcode/blob/main/docs/superpowers/specs/2026-08-04-windows-cua-upstream-main-forward-port-design.md

ASCII diagram showing the staging flow from pnpm install to the Desktop local Host starting the Windows Helper. It includes fail-closed behavior for missing build/source artifacts and validation steps.

```text
pnpm install（固定 producer SHA）
        |
        v
读取 producer runtime contract
        |
        +-- build/source artifacts 缺失 --> fail closed
        |
        v
校验 native / Electron / target arch
        |
        v
生成带 digest 的 staged runtime
        |
        v
electron-builder -> resources/tools/cua-helper
        |
        v
Desktop local Host 按需启动 Windows Helper
```

--------------------------------

### Start desktop development build

Source: https://github.com/zai-org/zcode/blob/main/docs/superpowers/plans/2026-07-23-browser-background-screenshot-surface.md

Launches the current desktop development build for runtime verification.

```powershell
pnpm dev:desktop:prod
```

--------------------------------

### getRepoWikiClient() Without wireClient

Source: https://github.com/zai-org/zcode/blob/main/docs/working-memory/provider-refactor/steps/todo-44-repo-wiki-agent-runtime-headers-and-cancellation.md

Current getRepoWikiClient() implementation that only gets and marks the client ready without calling wireClient(client, params). This omission prevents the installation of Host Protocol handlers, including the reverse RPC for interaction/requestProviderRuntimeHeaders, causing the Agent's runtime headers request to hang with zero listeners.

```ts
const client = await repoWikiProcessManager.getClient(params);
repoWikiProcessManager.markReady(params, client);
return client;
```

--------------------------------

### setupBrowserRuntime 初始化 agent.browsers 对象图

Source: https://github.com/zai-org/zcode/blob/main/docs/browser-use/2026-07-07-browser-client-lib-spec.md

定义 setupBrowserRuntime 函数，接收 globals 和 execute 回调，创建 BrowsersFacade 并挂载到 globals.agent.browsers。用于在 node_repl 中注入浏览器控制能力。

```typescript
// browser-client/index.ts
export function setupBrowserRuntime(opts: {
  globals: Record<string, unknown>;
  execute: (command: BrowserCommand) => Promise<BrowserCommandResult>;
}): void {
  const agent = (opts.globals.agent ??= {}) as { browsers?: BrowsersFacade };
  agent.browsers = new BrowsersFacade(opts.execute);
}
```