axuse — browser & computer use, done right

Accessibility-first browser and computer use for agent harnesses. One MCP server plugs into Codex, Claude Code, OpenCode, Antigravity, or any MCP-capable host. Zero dependencies (Node ≥ 22). Windows desktop driver is verified; macOS desktop control is available as an explicit opt-in with native TCC permission checks; Linux desktop control runs over X11/XWayland (XTEST input + capture + EWMH windows, zero extra packages).

The design is distilled from the two best implementations of this problem — OpenAI's Codex Chrome extension and the ZCode harness — and exists to prove a point: a screenshot loop is not the right interface for a machine. The DOM tree, the accessibility tree, and CDP are. axuse instruments the target instead of photographing it.

Not a developer? You don't need anything below. In the Claude desktop app, download axuse.mcpb from ax-use.com and double-click it. In ChatGPT's Codex app, Claude Code, Cursor or any other agent, paste the install prompt and the agent sets axuse up for you. See the non-developer guide.

Proven in production

axuse is maintained by CTOL Digital Solutions (ctol.digital), a leading AI, Strategy and IT consultancy. This work has been tested and used at large scale across many client engagements. CTOL Digital Solutions holds the copyright of all the code.

Quick start

You need Node.js 22+ and a Chromium-family browser (Chrome, Edge, Chromium, or Chrome for Testing; found automatically, or set AXUSE_BROWSER=/path/to/chrome). On a bare server with no browser and no sudo: node src/cli.js install-browser provisions a pinned Chrome for Testing under ~/.cache/axuse — nothing else: axuse has no npm dependencies.

1. Get it and check the environment

git clone https://github.com/ctoldigital/axuse.git
cd axuse
node src/cli.js doctor        # finds a browser, launches it, takes a snapshot

For a daily Chrome/Edge session, use the guided bridge setup. It registers the native host, opens the extensions page, prints the exact folder to load, and can print your harness configuration in the same command:

node src/cli.js setup --browser chrome --harness codex

After clicking Load unpacked once, verify the connection with:

node src/cli.js bridge verify

2. Add it to your harness (use your absolute path to src/cli.js)

# Codex
codex mcp add axuse -- node /abs/path/axuse/src/cli.js mcp

# Claude Code
claude mcp add --scope user axuse -- node /abs/path/axuse/src/cli.js mcp

# OpenCode, Antigravity, any other MCP host: print the config block to paste
node src/cli.js print-config --harness opencode   # or agy | generic

3. Ask for something in the browser

Open https://example.com, find the "More information" link and tell me where it goes.

The agent calls ax_open, reads the accessibility snapshot, and acts on element refs like [ref=e7]. Each action returns only what changed.

Optional settings (environment variables for the MCP server)

| variable | effect | |---|---| | AXUSE_SERVER_MODE | auto (default): on a display-less Linux server, boot a private Xvfb and keep Chrome fully headed on it (anti-bot-safe; see Servers, no desktop) | | AXUSE_DISPLAY_SIZE | virtual display geometry for server mode (default 1920x1080x24; random = a stable geometry per machine, so a fleet is not all 1920x1080) | | AXUSE_TIMEZONE | IANA TZ for the Chrome process — Date/Intl in pages and workers match the egress persona (validated by doctor) | | AXUSE_LANG | --accept-lang for Chrome — navigator.language(s) and the Accept-Language header match the egress persona | | AXUSE_PROXY | route every launched browser through a proxy (http://·socks5://, credentials supported — answered over CDP); ax_open {proxy} sets it per launch, and ax_open {timezone, lang} completes the per-instance persona | | AXUSE_AMBIENT_MOTION | 0 disables idle pointer park-fuzz (default: automatic in server mode — the agent's "thinking" pauses still show a live hand) | | AXUSE_MAX_BROWSERS / AXUSE_MAX_TABS | governance caps for massive operations (defaults 8 / 48) — typed failures instead of OOM spirals | | AXUSE_NO_SANDBOX=1 | force --no-sandbox (auto for root/container server runs) | | AXUSE_NEUTRALIZE_WEBDRIVER=0 | disable the navigator.webdriver posture-fix fallback (the AutomationControlled launch flag already fixes it at the source) | | AXUSE_HEADLESS=1 | launch the browser without a window — trusted internal pages only: challenge/anti-bot pages detect headless first; servers get server mode instead | | AXUSE_BROWSER | path to the browser binary | | AXUSE_PROFILE_DIR | where temporary browser profiles go (default: OS temp; they are deleted on exit) | | AXUSE_BRIDGE_DIR | override the local bridge state directory (default: ~/Library/Application Support/axuse on macOS) | | AXUSE_ENABLE_MACOS_CUA=1 | enable macOS desktop tools (Accessibility + Screen Recording grants are still required) | | AXUSE_BRIDGE_DEBUG=1 | trace the extension bridge |

To drive your own logged-in Chrome instead of a fresh browser, see Driving your daily browser.

Servers, no desktop (Ubuntu server lane)

axuse runs under agent CLIs (codex, claude code, opencode) on headless Ubuntu servers. Challenge/anti-bot pages check is this a headless browser? first, so server mode never uses --headless: it boots a private Xvfb and runs Chrome fully headed on it — real headed build, no headless fingerprint (verified live against Turnstile: ax_solve_captcha solves on a server with no desktop, and the slider engine's human-curve drags land 10/10). Beyond headed-vs-headless, server mode covers persona coherence (AXUSE_TIMEZONE/AXUSE_LANG matching the egress persona, AXUSE_DISPLAY_SIZE=random fleet diversity, --disable-blink-features= AutomationControlled so navigator.webdriver stays false at the source) and fleet hygiene (zombie-Xvfb sweep). Solver plugins that need vision call a multimodal model through any OpenAI-compatible API; keys come from env vars or an owner-only secrets file. One-time setup, systemd wiring, env reference and scale notes: docs/server-mode.md — and node src/cli.js doctor verifies the whole lane (it prints the measured anti-bot posture and persona).

Benchmark

On 16 server-scored browser tasks, run in the same harness (Codex CLI) with the same model against Codex's own Chrome extension and browser-use 0.13:

| | axuse | Codex + Chrome extension | browser-use | |---|---|---|---| | tasks passed | 28/28 | 27/27 | 27/27 | | median time per task | 17 s | 26 s | 56 s | | tokens, all runs | 4.7M | 9.8M | 8.8M | | median tool calls | 5 | 7 | 12 |

Accuracy tied on those tasks. A harder 7-task extension (checkout flow, virtualized grid, date pickers, signup errors, nested iframes, file upload, local dev app) has been run once so far: axuse 7/7; Codex + Chrome failed 2 by stopping to ask for confirmation; browser-use failed 1. Method, anti-cheat rules and how to reproduce: bench/suite/README.md. Install footprint and setup comparison: bench/suite/EASE.md.

Why this is faster and more reliable than screenshot CUA

| | Screenshot CUA loop | axuse | |---|---|---| | Observation | ~1–2MB base64 raster per step, ~1k+ image tokens, vision-encoder latency | YAML-like AX snapshot in KBs; diff by default (only removed/added/changed lines) | | Targeting | pixel coordinates guessed from an image; drifts with resolution/DPR | stable element refs bound to element identity (insertion-safe) + Playwright-style semantic lines | | Input | synthetic DOM events (rejected by sites) or fragile OS injection | trusted CDP Input.dispatch* events (isTrusted) | | Failure mode | silent misclick, discovered 2–3 screenshots later | typed errors: REF_NOT_FOUND / STALE_STATE / DIALOG_OPEN with retry hints and action_sent facts | | Change detection | re-photograph everything | sequenced event ring buffer + snapshot diffing | | Cost control | none | budgets enforced in code: snapshot char/node caps, screenshot byte budget with quality fallback, one raster per call |

Install into a harness

node src/cli.js print-config --harness codex       # or claude-code | opencode | agy | generic

• Codex — append the printed [mcp_servers.axuse] block to ~/.codex/config.toml
• Claude Code — claude mcp add --scope user axuse -- node <path>/src/cli.js mcp
• OpenCode — merge the printed mcp block into opencode.json
• Antigravity / any MCP host — the printed mcpServers block

Verify the environment: node src/cli.js doctor.

The model-facing usage contract lives in SKILL.md — point your harness's skill system (or system prompt) at it.

Solver plugins (open core ↔ paid solvers)

axuse's core is CAPTCHA-agnostic and ships no solvers. Turnstile / hCaptcha / reCAPTCHA solvers are separate, commercially licensed packages that plug in through a thin, frozen seam (src/plugins/):

# install: drop a solver package into plugins/ (or list dirs in AXUSE_PLUGINS)
node src/cli.js plugins          # → ✓ captcha-pro@1.0.0 — providers: turnstile, recaptcha-v2, hcaptcha
node src/cli.js solve turnstile --url https://demo.turnstile.workers.dev/

From any MCP harness: ax_solve_captcha { provider, url? } and ax_plugins. Plugins that own capabilities (session vaults, network governors, guarded actions…) can also contribute their own MCP tools through a validated tools() export (ax_vault, ax_net, ax_guard, …) — same seam, same trust boundary. The ABI, the solver context, the tools() contract, and packaging/licensing guidance: docs/plugins.md. A complete free (PolyForm Noncommercial 1.0.0) reference solver lives in examples/plugin-turnstile-demo/.

Architecture

harness (Codex / Claude Code / OpenCode / Antigravity / …)
        │  MCP over stdio (JSON-RPC 2.0) — the universal integration layer
        ▼
src/mcp/ — thin, stateless-per-call adapter (hand-rolled, zero deps)
        │  one frozen command contract (src/core/commands.js)
        ▼
src/core/ — the state owner (Codex native-host / ZCode host pattern)
   ├─ controller.js  sessions, tabs, state_id, dialogs, auto-observe diffs,
   │                OOPIF frame registry (f-slot namespaced refs)
   ├─ cdp.js         launch/attach Chromium, browser-level WebSocket, flat sessions,
   │                Target.setAutoAttach for OOPIF auto-entry
   ├─ serialize.js   injected AX serializer: element-identity refs, shadow DOM,
   │                same-origin iframes (coordinate-translated), budgets
   ├─ diff.js        per-ref diff + text-line multiset diff + cost-based full fallback
   ├─ actuate.js     trusted Input.dispatch*, live ref resolution (frame-chain
   │                coordinate translation), combos, waits
   ├─ screenshot.js  one raster, byte budget, quality fallback, crop hints
   └─ errors.js     typed codes, retry hints, action_sent, side_effect
        │
        ├─ src/bridge/ — Codex-style extension backend for the user's daily
        │   Chrome/Edge: hub (TCP rendezvous, token auth, NDJSON) ←
        │   native-messaging host (framed stdio relay) ← MV3 extension
        │   (chrome.debugger = real CDP over the user's real browser)
        │   + installer (registry/HKCU, host manifest, launcher) + backend
        │   duck-typed onto the same command contract
        ▼
src/desktop/ — computer use (driver matrix)
   ├─ Windows: resident PowerShell + SendInput/GDI, DPI-aware —