Skip to main content
Glama
README.md
# dsh-zcode-cua

Brings [ZCode](https://zcode.ai)'s Computer Use into [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).

The model can click, type, read the accessibility tree and take screenshots of native desktop apps through a single `js` tool. DSH's own `dsh-cua-bundle` reports `unsupported-platform` on Windows, so this is the route that works there.

[中文](README.zh.md) · [Changelog](CHANGELOG.md)

## What it adds

One MCP tool, `mcp__zcode-cua__js`. Every call runs top-level `await` in a **fresh Node.js kernel**; the model drives the desktop with code:

```js
const root =
  process.env.ZCODE_CUA_PLUGIN_ROOT ??
  process.env.ZCODE_PLUGIN_ROOT ??
  process.env.CLAUDE_PLUGIN_ROOT;
const { join } = await import("node:path");
const { pathToFileURL } = await import("node:url");
const { setupComputerUseRuntime } = await import(
  pathToFileURL(join(root, "scripts", "computer-use-client.mjs")).href
);
await setupComputerUseRuntime({ globals: globalThis });

const app = await agent.computerUse.getApp({ pid: 1234 });
await app.getAXState();      // read the accessibility tree
await app.click(12);         // click by element index
await app.typeText("hello");
await app.getScreenshot();
```

`agent.computerUse` exposes `getState` / `getApp` / `listApps` / `requestAccess` / `stop`, plus fourteen low-level `computer.*` tools. The ordered path is: `getAXState()` first, find the element by role and name, then act on its index. Coordinates are the last resort, for canvas and Electron content accessibility cannot see.

The full API reference is `agent.documentation.get("computer-use")`, fetched on demand.

## How it is wired

```
DSH  ──MCP stdio──▶  this plugin's server/index.js
                       ├─ injects ZCODE_CUA_PERMISSION_BROKER_SOCKET and friends
                       └──▶ node-repl-host (ZCode's official MCP server, one `js` tool)
                               └──▶ cua-helper (native Windows process, ax_native.node)
                                       └──▶ Win32 UI Automation / input injection
```

This plugin does exactly two things: **resolve ZCode's installation layout**, and **translate between MCP 1.x and the modern protocol**. The CUA execution logic is ZCode's own runtime, unmodified, which is why behaviour matches ZCode.

The upstream `js` tool is strict — anything beyond `code`, `timeout_ms` and `title` is refused — and this plugin passes it through untouched, adding no parameters.

## Install

### Prerequisites

1. **Windows**
2. **ZCode installed and launched at least once** — this plugin reuses the native helper in ZCode's install directory and redistributes none of it.
3. **DeepSeek Harness** (this is a DSH bundle)

### Into DSH

Option 1 (recommended): inside DSH, **Plugins → Add plugin**, then pick this directory. DSH links the checkout, so source edits take effect immediately.

Option 2: install from the checkout with the same command this was verified with:

```powershell
cd "D:\path\to\dsh-zcode-cua"
dsh plugin --profile desktop add "link:$PWD"
```

Restart DSH afterwards. The tool appears as `mcp__zcode-cua__js`, and the plugin row reads **ZCode computer control**.

> **The package name must stay `dsh-zcode-cua`**, unscoped. The registration row points at the relative path `node_modules/dsh-zcode-cua/server/index.js`; that is what makes one file work on every machine, and it assumes the package is installed under the profile's `node_modules` under exactly that directory name.

### Skill (optional, strongly recommended)

The tool works on its own, but the model will not know how to use it well. The skill lives at `skills/zcode-computer-use/SKILL.md` in this repository; install it into a DSH skill directory:

```powershell
# user level (every project)
Copy-Item -Recurse .\skills\zcode-computer-use "$env:USERPROFILE\.dsh\skills\zcode-computer-use"

# or project level (only that project)
Copy-Item -Recurse .\skills\zcode-computer-use "D:\your-project\.dsh\skills\zcode-computer-use"
```

DSH does **not** load skills from a plugin directory — it scans `<project>/.dsh/skills`, `<project>/.agents/skills` and `~/.dsh/skills` only, so this step is manual. Restart DSH afterwards.

## Configuration

To change anything, find the `zcode-cua` row in the profile's `cordis.patch.yml`:

```yaml
- id: zcode-cua
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: zcode-cua
    transport: stdio
    command: 'node'
    args: ['node_modules/dsh-zcode-cua/server/index.js']
    toolCallTimeoutMs: 180000
```

`command` defaults to `node`, which needs Node 18.17+ on PATH. The DSH desktop app ships its own Node; point `command` at it if you prefer an absolute path.

### Environment variables

When layout resolution fails — ZCode installed somewhere unusual — override the three probes:

| Variable | Points at |
|---|---|
| `ZCODE_BRIDGE_SERVER` | `node-repl-host`'s `dist/mcp/server.js` |
| `ZCODE_CUA_PLUGIN_ROOT` | the `computer-use` plugin root (holds `scripts/computer-use-client.mjs`) |
| `ZCODE_BRIDGE_HELPER_ROOT` | the `cua-helper` directory (holds `build/Release/ax_native.node`) |

Usually none are needed: the plugin looks for ZCode in the **uninstall registry** (`InstallLocation`), in `ZCODE_HOME`, and in the conventional install locations.

## Limitations

- **Windows only.** It needs `resources/tools/cua-helper` from ZCode's install directory (the `ax_native.node` native module). ZCode currently has peer-identity verification disabled on Windows (`WINDOWS_PEER_IDENTITY_GATE_TEMPORARILY_OPEN = true` in `windows-helper.js`) — **this plugin did not open that gate**; the day ZCode closes it, this plugin stops working.
- **No on-screen activity indicator.** ZCode's ghost cursor is drawn by a long-lived render scheduler inside the helper, and this path only has short-lived call processes, so the overlay never paints. Picture-in-picture is unavailable for the same reason — `ax_native.node` exports no `pip*` functions at all and `pipSessionEnabled` is always false on Windows.
- **No Browser Use.** Upstream `node-repl-host` implements a Browser Use bridge, but it needs a `browserBroker` from the host and this plugin only wires the Computer Use bridge. Use DSH's own Browser Use for web pages.
- **Every `js` call is a fresh kernel.** Variables do not survive between calls, so bootstrap every time.
- **The model really clicks and types on your desktop.** That is the capability, not a defect; disable the plugin row when you do not need it.

## Security notes

- The helper's permission broker socket is created inside this plugin's own process under a random name (`\\.\pipe\zcode-cua-helper-<uuid>`) and disappears with the process.
- This plugin reads, stores and forwards no ZCode or WorkBuddy credentials. It only drives a runtime already installed on the machine.
- Tool calls are governed by DSH's tool permission system; use a DSH permission preset for tighter limits.

## Development

```
server/paths.js     resolves ZCode's three install locations
server/index.js     the MCP stdio server; spawns upstream and translates the protocol
skills/             the skill (installed manually into a DSH skill directory)
locale/             plugin display metadata
docs/               detail page image
cordis.patch.yml    the registration row
```

No build step, no runtime dependencies, pure ESM. Restart DSH after a change.

## License

MIT. See [LICENSE](LICENSE).

This plugin contains no ZCode binaries or source. It drives a ZCode installation already present on your machine; those rights belong to their respective owners.