Ui.Vision for Desktop is a new helper app that is part of the Ui.Vision Desktop Automation XModule. The browser extension (Ui.Vision for Chrome, Edge, Firefox) stays the place where you record, edit and run macros. The helper app does three things:
It is the native XModule host. You never have to start it for that.
It runs JavaScript macros on the desktop without a browser. Open it,
pick a macro from the Files tab, press Play. The same uiv.* API as in the
extension, desktop commands only (no page/DOM commands). Use it when you need speed - it runs desktop macros much faster. Macros with the file ending *.d.js are automatically run by the app (so it looks for .d at the end of the file name).
It answers Claude Code, OpenAI Codex and other MCP clients. With the MCP bridge on, an AI agent can list, edit and run your desktop macros in this app. So you no longer need to have a browser open for desktop automation.
If you only use Ui.Vision in the browser, you can ignore the app window entirely.
Every setting lives in a plain JSON file that the app and the browser
extension share, so a change on either side shows up on the other, and a copy
of the folder moves the whole setup with your macros.
MCP bridge — “Connect to the MCP bridge” and the bridge port (default
50888). This is the same local bridge the extension uses for Claude Code.
Off = the app is invisible to MCP clients.
Desktop animations — the blue border around the display while a macro
runs, the shaded search areas, the red match marks and the click/key cues.
Turn them off for the fastest scans (they cost a few milliseconds per look
on some machines) or when a macro must not paint over the screen.
Failsafe corner — which corner aborts a run when the mouse enters it:
top-left (default), top-right, bottom-left, bottom-right, or off.
Which macros the Files tab lists — the ones written for this app, as
a folder tree, in green: named <name>.d.js (d = desktop app). All .js
lists every file; the others are browser macros (globe icon). Play on
a browser macro hands it to the browser extension’s side panel, which plays
it from the same macro folder — like a bookmark or command-line run — and
streams its log back here. The side panel must be open in the browser (it
links to this app by itself), and both programs must use the same macro
folder (hard-drive storage in the XModule home folder); otherwise Play says
what is missing. The other way round, the extension plays a .d.js macro
in this app when you press Play in its tree.
Macro folder — where the Files tab looks for .js macros. Empty = the macros folder inside the home folder (below). In the extension’s
hard-drive storage mode this is the same folder the extension uses, so both
programs see the same macros.
Extension link port — the local port on which the browser extension
reaches this app: always the bridge port + 1 (50889 by default), not a
setting of its own.
Self-test — measures this machine’s capture and input path (how old a
polled frame is, how long one screen read costs, key latency) and publishes
the numbers to macros as !CAPTURE_AGE_MS, !SCAN_MS, !INPUT_LAG_MS and
friends. It runs once on the first start; repeat it after a display or
driver change.
AI (uiv.ai.ask / uiv.ai.find) — shows the provider the app will call.
Choose the provider and enter keys in the extension’s Settings > AI, or
edit the files by hand (below).
Show test targets — a strip of five red squares (48 to 12 points), a
text field and a Reset button, for the app’s own self-test macros: Desktop
App GUI SelfTest clicks the tabs, the squares and types into the field, Desktop App ClickAccuracyRange clicks every square three times and
reports where each click landed. A hit turns a square green and shows
the landing offset. Both macros ship in the extension’s demo folder
“Desktop App (high speed)” and in the app’s macro folder.
macOS permissions — Accessibility (input) and Screen Recording
(capture) must be granted to the app. The buttons request them; macOS
shows its own prompt.
Where the settings live (and how to edit them by hand)
All of it is in the home folder of the Desktop Automation module —
by default Desktop/uivision (the extension’s Settings > Desktop Automation
shows and can change it):
Desktop/uivision/
settings.json the shared settings (machine-level, no secrets)
settings.example.json a documented copy of every key — read this first
keys.json API keys — secrets, keep this file to yourself
macros/ your macros in hard-drive mode
Rules that both programs follow:
Edit settings.json with any text editor; both the extension and the app
reload it when it changes. Unknown keys are kept, so you can add your own
notes as extra keys.
Invalid JSON is reported in the log and left untouched — nothing is
overwritten while the file does not parse. Fix the syntax and save again.
The file wins over the extension’s browser-storage copy whenever it is
newer than the extension’s last write; the extension writes it back when
you change a setting in its Settings tabs.
keys.json ships with "uivisionAi": "ui-vision-ai-free". That value
means “use the Ui.Vision free tier”, exactly like no key at all. Replace it
with your PRO key to move up; put OpenRouter, Anthropic, local-server and
OCR.space keys in their own slots. Never zip, sync or commit keys.json —
that is why the keys are not inside settings.json.
The app finds the home folder without a browser: a tiny pointer file in the
app’s data folder (UiVision RPA/config.json) says where it is, and only
when you moved it. The data folder also keeps the app log (log.txt), the
self-test results and files a macro stores.
Typical use without any browser: copy settings.example.json to settings.json, set macroDir if your macros are elsewhere, start the app,
press Play.
Where things are on each system
Home folder (default)
App data folder
Windows
%USERPROFILE%\Desktop\uivision
%APPDATA%\UiVision RPA
macOS
~/Desktop/uivision
~/Library/Application Support/UiVision RPA
Linux
~/Desktop/uivision
~/.local/share/UiVision RPA
Troubleshooting
“could not connect” in the extension’s Settings > Desktop Automation:
start the app (“Ui.Vision for Desktop” in the Start menu, in Applications,
or in the Linux app launcher), then Connect again. The extension can also
start it for you when the module is installed as the native host.
Nothing happens on clicks or captures (macOS): grant Accessibility and
Screen Recording in System Settings > Privacy & Security; after an app
update the grants can need a re-toggle.
Slow scans, late key presses: run the self-test; if it says a screen
read costs a whole display frame or that key presses are dropped, the
verdict names the cause. Desktop animations off helps on some machines.
The app shows an old setting: check settings.json — the newer of the
file and the extension’s copy wins; a hand edit saved a moment ago is the
newer one.
- it runs desktop macros much faster. Macros with the file ending 