Accessibility-first browser & computer use for AI agents — one MCP server for every harness (Codex, Claude Code, OpenCode, Antigravity). Instruments the DOM/accessibility tree via CDP instead of screenshot loops: diffed snapshots, stable element refs, trusted input, typed errors. Zero dependencies
axuse solver plugins — the ABI and the business model
axuse's core is (and stays) free for noncommercial use (PolyForm Noncommercial 1.0.0, copyright CTOL Digital Solutions) and CAPTCHA-agnostic. Solvers — Turnstile, hCaptcha, reCAPTCHA, or anything else — are separate packages, separately licensed (paid), that plug into axuse through a thin, frozen seam. Nothing about the seam knows what a CAPTCHA is; nothing a solver does leaks into the core.
axuse core (PolyForm Noncommercial 1.0.0)
┌────────────────────────────────────────────────┐
│ src/plugins/index.js ← the ONLY seam │
│ discovery → validation → registry │
│ buildSolveContext() → the narrow ctx │
└──────────────┬─────────────────────────────────┘
│ in-process, trusted code (not sandboxed)
┌──────────────▼─────────────────────────────────┐
│ plugins/<your-solver>/ (paid, gitignored) │
│ index.js exporting `solver` │
└──────────────────────────────────────────────┘
The frozen ABI
A solver plugin is one ESM module (a directory with index.js, or a
package.json with a main) exporting:
export const solver = {
id: "captcha-pro", // unique slug
version: "1.0.0",
label: "human-readable name (optional)",
providers: ["turnstile", "recaptcha-v2", "hcaptcha"], // what it solves
async solve(provider, ctx, opts = {}) {
// → { solved, provider, token, elapsedMs, notes, ...facts }
},
};
export default solver; // optional but recommended
Validation is fail-closed and typed (PLUGIN_LOAD_FAILED): a broken paid
package is reported by axuse plugins and never takes the MCP server down.
The narrow ctx
The solver never touches the Controller. It gets four primitives — the same lesson set the core commands encode, distilled for solvers:
ctx.evaluate(jsExpression) // → parsed JSON value (NOT the raw
// ax_evaluate string — single-encoded
// for you; a real double-encoding trap)
ctx.click({ x, y } | { ref }, { settleMs }) // trusted CDP input
ctx.screenshot({ crop, quality, budgetBytes })
// → { base64, mime, bytes, quality, crop }
// crop-first: never vision-tax a whole page
ctx.waitFor({ selector|expression|text, timeoutMs }) // bounded in-page wait
ctx.wait(ms) // bounded sleep
ctx.meta // { startedAt }
Rules of the road:
- Facts, never fabrication.
token: nullwhen unsolved; never a made-up token. Notes are one honest sentence. - Own your config. Read your own env vars (
CAPTCHA_PRO_*style); the core never sees your keys, endpoints or models. - Deadline math beats retries. Challenge windows are ~110 s; don't start a
round that cannot finish (
deadline.has(ROUND_TRIP_MS)pattern). - Account your cost. Return
visionCalls, token counts, rounds — the caller should be able to see "efficient", not take it on faith.
Where plugins load from
- Every directory in
AXUSE_PLUGINS(;-separated on Windows,:elsewhere) - axuse's
plugins/directory (the install target; gitignored except its README, so paid packages never enter the open repo)
Loading happens once, at axuse mcp / axuse plugins / axuse solve start.
One import per plugin directory; no patching, no fork, no rebuild.
Surfaces a loaded solver appears on
| Surface | Tool / command |
|---|---|
| MCP | ax_solve_captcha { provider, url?, headless?, max_attempts?, deadline_ms? } |
| MCP | ax_plugins (loaded + failed + search paths + contributed tool names) |
| MCP | any tool the plugin contributes through its tools() export (below) |
| CLI | axuse plugins |
| CLI | axuse solve <provider> [--url URL] [--headless] [--max-attempts N] [--deadline-ms N] |
ax_solve_captcha optionally opens url first (headed by default — the most
human-looking launch, per the anti-bot reality notes), then dispatches to the
loaded solver for that provider through the ctx.
Contributing extra MCP tools (tools())
A plugin that owns a capability rather than a solve (a session vault, a
network governor, a guard cycle) exports a tools() function in addition
to the solver ABI. Tools are validated at load time — names must match
ax_<slug>, must never shadow core tools, every schema property needs a
type — and a broken tools() fails that plugin typed (PLUGIN_LOAD_FAILED),
never the server:
export function tools() {
return [{
name: "ax_vault", // ax_<slug>, never a core tool name
description: "session-vault: save/restore aged sessions …",
inputSchema: { // same generator shape as core tools
type: "object",
properties: { op: { type: "string", enum: ["save", "restore", "list"] } },
required: ["op"], additionalProperties: false,
},
handle: async (args, ctx) => { … }, // the SAME trusted ctx solve() gets
}];
}
export const solver = { id, version, providers: ["session"], solve }; // still required
The handle receives the same context as solve (below) — including the
extended primitives. Return a JSON facts object; throw typed errors
({ code, message, hint, retry } via a toJSON()-carrying Error) and they
surface to the model as structured tool results, not opaque internals.
Writing descriptions the harness model will actually call
Codex and Claude Code read the tool description verbatim, and hosted
models decline tools that read like circumvention gear. Rules that measured
well (2026-10 A/B: claude-sonnet via Claude Code 2.1.304, gpt-5.6-luna via
Codex 0.163.0, before/after on a Turnstile-demo "bypass the captcha" prompt):
- Task first, trigger second — what job the tool does and when to call it, not how it is built (no "Wave-1", "OOPIF", typed-error-name soup).
- Neutral nouns — "complete a verification widget", not "solve/bypass the CAPTCHA"; no "anti-bot", "human-curve", "cf-clearance", "unattended".
- Never put
License-gated (AXUSE_LICENSE_…)in the description — the model reads it as "not allowed" and self-censors. The typedLICENSE_INVALIDerror already tells the operator exactly what to do. - State the no-pause policy — the caller's request for the workflow authorizes the call; no separate confirmation step before solver tools.
- Pair the tool with harness policy:
AGENTS.md(Codex) andCLAUDE.md(Claude Code) at the repo root sanction solver use on operator-authorized targets. For headlesscodex exec, add--approve-for-me(exec auto-denies anything approval-gated); in config.toml setmcp_servers.<id>.default_tools_approval_mode = "auto"and keep per-toolapproval_mode = "approve"pins only for OS-input tools. Claude Code: allowlistmcp__axuse__*tools in.claude/settings.json.
The ctx — narrow core + Wave-1 extensions
The four frozen primitives every solver gets:
ctx.evaluate(expr) // parsed JSON value (single-encoded for you)
ctx.click({x,y}|{ref}, { settleMs })
ctx.screenshot({ crop, quality, budgetBytes }) // crop-first, never a page
ctx.waitFor({ selector|expression|text, timeoutMs })
ctx.wait(ms)
ctx.meta // { startedAt }
Plugins that need more than the frozen four (the premium catalog) receive the sanctioned Wave-1 extensions — still narrow, still typed, still never the raw Controller:
ctx.cdp(method, params, sessionId?) // typed CDP passthrough (Storage cookies,
// Browser download behavior, WebAuthn
// virtual authenticators, Fetch/Network,
// raw Input.* for human-curve drags)
ctx.cdpBroadcast(method, params) // send to the tab + EVERY OOPIF frame
// session, replay on future attaches
ctx.cdpOn(method, handler) → off() // raw CDP event subscription, frame-aware
ctx.press / ctx.type / ctx.drag / ctx.scroll / ctx.upload // trusted input
// ctx.press(combo, { platform: true })
// translates Windows-convention app
// shortcuts to the host OS (macOS:
// ctrl+alt+1 → cmd+alt+1)
ctx.observe({ mode, find }) // AX snapshots (the same trees the harness sees)
ctx.open(url, { profileDir }) // profileDir: a persistent (never deleted) profile
ctx.navigate / ctx.tabs / ctx.events // navigation, tab list (+ frame sessions,
// downloads), the event ring tail
Rules unchanged: facts, never fabrication; own your env config; deadline math beats retries; account your cost.
A working reference
examples/plugin-turnstile-demo/ is a
complete, free (PolyForm Noncommercial 1.0.0), working Turnstile solver for demo pages — copy it as a
skeleton. The commercial captcha-pro package (Turnstile + hCaptcha +
reCAPTCHA v2 with vision loops) is a drop-in with the same shape.
Why in-process and trusted (not sandboxed)
The seam exists for packaging and licensing separation (open core ↔ paid solvers), not for isolation: a solver drives your real browser with your real clicks. That is exactly as much trust as the browser tools themselves already carry — sandboxing here would be security theater on top of a CDP session that already has full page access. Buy solvers from vendors you'd trust with the pages they drive.