Cua Driver (let agents operate desktop apps)

What it is

Cua Driver comes from the open-source CUA project (trycua, MIT licence). It is the desktop counterpart of agent-browser: agent-browser drives web pages in a throwaway browser, while Cua Driver drives the apps on the computer itself. It needs no CUA account and never calls an AI service on its own; the agent session supplies the intelligence.

It acts on the real desktop — the same screen, apps and files the user works in. Windows has no CUA sandbox, so there is no isolated copy to work in. Agents are told by the vendor skill to use it only when a task genuinely needs a desktop app and to prefer agent-browser for websites.

Where to find it

Open the Tools view and find Cua Driver in the Browser group. It is never pre-ticked and never installed in the first-run sweep, so installing it is always a deliberate click on Install.

Once it is installed, start a new agent session: nothing else is needed, because the tool and its skill are already visible to that session. Ask the agent to do something in a desktop app, and it uses the command line — for example cua-driver call list_apps. The first time, the agent starts Cua Driver's background helper with cua-driver serve; when the helper is not running, the command line prints the exact command to start it.

On macOS one-click install is not offered: CUA needs its own signed app so macOS can grant Accessibility and Screen Recording. Install shows a link to cua.ai/docs/cua-driver; once it is installed there, Omniscio finds it.

How it behaves

• Pinned and verified. Omniscio downloads Cua Driver 0.35.4 from the project's GitHub release and refuses it, writing nothing, if its SHA-256 differs from the value pinned in Omniscio or if any file in the archive would land outside the install folder. The version only moves when Omniscio itself is updated; there is no separate update notice.
• Where it lives. Windows: %LOCALAPPDATA%\Programs\Cua\cua-driver\bin (the vendor's own folder). Linux: ~/.local/share/cua-driver/bin.
• Found by new sessions. After install, and at every app start when it is installed, Omniscio adds that folder to the PATH it gives agent sessions. Nothing is written to the Windows registry or to shell startup files. A copy the user installed with the vendor's own installer (for example in ~/.local/bin) is detected too, and one that comes earlier on their PATH still wins, as it does for every tool.
• The skill. Omniscio places the vendor's skill pack — verified against the same release — in ~/.claude/skills/cua-driver. A copy the user already has there is never overwritten. A skill problem never fails the install.
• Privacy. Cua Driver reports anonymous usage to its vendor by default. Omniscio runs cua-driver telemetry disable right after install.
• What it does not add. No logon task, no admin prompt, no MCP server in sessions.

Three things worth knowing before relying on it:

• An agent can run cua-driver update --apply, which installs the vendor's newest release outside Omniscio's checksum pin. The vendor skill tells agents to ask first.
• If another Windows tool install refreshes the PATH, Cua Driver drops off the session PATH until the next Tools check or app start adds it back.
• On Windows the background helper must run inside the user's own desktop session, which is where Omniscio's agent sessions already run.

For agents

The install asset, the pinned version and the checksum live in src/main/services/toolchain/cua-driver-asset.ts and the install itself in cua-driver-install.ts; both hang off the Tools view's ordinary toolchain registry. The rules this feature must keep are cua-driver-tool-contract.md.

Related

• Tools view — where the tool is installed, alongside agent-browser and the other optional CLIs.
• Browser logins — the browser-side counterpart, for the sites an agent needs to be signed into.
• Toolchain updates — how Omniscio keeps the tools it installs up to date, and why this one only moves with the app.