ctoldigital/axuse

Maintainer? Show your league in your README

Card: your league's emblem, from Copper to Legendary

[![bestofgithub](https://bestofgithub.dev/badge/ctoldigital/axuse.svg?style=card)](https://bestofgithub.dev/repo/ctoldigital/axuse)

Flat: fits beside your other badges

[![bestofgithub](https://bestofgithub.dev/badge/ctoldigital/axuse.svg)](https://bestofgithub.dev/repo/ctoldigital/axuse)

Loading README…

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

	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

	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

Pattern	Codex lineage	ZCode lineage	axuse implementation
Diff-first observation	page-state diffing, default-on	"the tree comes back as a diff only… unchanged rows are omitted and their indices stay valid"	per-ref diff; refs bound to element identity so unchanged rows stay valid
Element addressing	axState `element_index`/locators	refs `e1,e2…` in page + live resolution	`window.__axuseRefRegistry` (identity-stable across insertions), resolved live at action time
Trusted input	`chrome.debugger` → `Input.dispatch*`	`webContents.debugger`	raw CDP `Input.dispatch*` / `Input.insertText`
Event buffer	`tab_cdp_events` sequenced ring (limit ≤1000)	event routing with teardown discipline	ring buffer, sequence cursor, filtered methods
Context budgets	64k DOM text cap	2×200KB images at protocol boundary, one-raster rule	snapshot node/char caps; screenshot 200KB budget + quality fallback + crop hint
Error vocabulary	structured locator errors	`STALE_STATE`, `sideEffect:none\|uncertain`, `actionSent`	typed codes + `retry: reobserve\|retry\|never` + `action_sent`
Frozen contract	command envelopes w/ zod	one discriminated union for all backends	`Contract` → validation AND MCP schemas generated from it
Real user session	attaches to the user's real Chrome profile	`extension` backend via user Chrome	extension bridge: MV3 extension + native messaging + hub; `ax_open {backend:"extension"}`
Frame entry (OOPIF)	webmcp/extension content merging	IAB merges frames; OOPIF via CDP	`Target.setAutoAttach` per tab; frames serialized in their own sessions, merged under `f<slot>:` identity-stable refs, input dispatched frame-locally

ctoldigital/axuse

axuse — browser & computer use, done right

Proven in production

Quick start

Servers, no desktop (Ubuntu server lane)

Benchmark

Why this is faster and more reliable than screenshot CUA

Install into a harness

Solver plugins (open core ↔ paid solvers)

Architecture

The patterns, and where each one comes from

Tool surface

The loop the model is guided into

Driving your daily browser (the Codex pattern)

Honest scope notes

Development

License