Faster Mac Use (fmu)
Background-first, multi-cursor browser and native macOS computer-use engine for AI agents, modeled after and extending OpenAI Codex's cua_repl architecture.
- Website & Interactive Benchmark Explorer: https://clifan.com/faster-mac-use/
- Architecture & 5-Workload Benchmark Report:
docs/architecture_and_benchmarks.md
Why faster-mac-use?
Most computer-use tools force a painful choice:
- Pixel screenshot loops (
computertool) hijack your physical mouse cursor, steal window focus, and burn 40k–80k tokens across 10–30 turns. - Standard Accessibility/Playwright MCPs (
@playwright/mcp,chrome-devtools-mcp) inject 4,000–12,500 tokens of tool schemas upfront and return full ARIA trees on every click. - Single-session REPLs (
cua_repl) are fast for one agent, but serialize multi-agent workflows and fall back to screenshots on custom-rendered macOS windows or HTML5<canvas>apps.
faster-mac-use combines a 268-token single-tool MCP/CLI schema, a stateful async cua_repl sandbox, persistent @u1..@uN / @a1..@aN element UIDs with pre-registered table folding, push-based AXObserver < 1 ms dirty-subtree diffs, auto-synthesized Virtual WebMCP site macros (~/.fmu/macros/), 0-vision-token <canvas> & macOS window OCR, outbound MV3 extension WebSocket bridging for live logged-in Chrome "🤖 Agent" tab groups (zero Chrome 144 popups), and true multi-cursor parallel execution — verified at 0.0 px physical cursor movement and 0 focus changes.
| Workload | faster-mac-use (Cumulative Tokens / Engine Time) |
OpenAI Codex cua_repl Ref |
@playwright/mcp / Stacked MCPs |
Anthropic Pixel CUA |
|---|---|---|---|---|
| A. Enterprise SaaS Console (10 ops) | 1,290 tok / 94 ms (Native WebMCP) 1,290 tok / 97 ms (Virtual WebMCP Macro) 2,024 tok / 133 ms (DOM Diff) |
5,732 tok / 359 ms | 231,125 tok / 1,850 ms | 83,215 tok / 3,400 ms |
| B. macOS Native Calculator (11 ops) | 1,264 tok / 395 ms (< 1 ms AXObserver diff) |
1,502 tok / 554 ms | 48,477 tok / 12,718 ms (ocu) |
— |
| C. Hybrid Web + macOS (14 ops) | 2,179 tok / 335 ms | 2,437 tok / 568 ms | 129,010 tok / 3,200 ms | — |
| D. 3-Agent Multi-Cursor Swarm (25 ops) | 1,510 tok / 326 ms (2 turns) | 15,923 tok / 1,122 ms (6 turns) | 293,950 tok / 4,850 ms | 430,800 tok / 7,600 ms |
| E. Long-Horizon 30-Op + Window OCR | 4,584 tok / 494 ms (0 vision tok) | 8,355 tok / 942 ms | 400,725 tok / 6,100 ms | 620,535 tok / 9,200 ms |
Core Architecture
-
Tier 1 — Native Browser Engine (
BrowserEngine)- Dual-Mode Zero-Popup Chrome Control:
- Live Logged-In Chrome via Outbound MV3 Extension WebSocket Bridge (
ws://127.0.0.1:19222/ext):extension/background.jsconnects outward to/tmp/fmu-runtime.sock's single-ownerExtensionWebSocketBridge(fmu mcpproxies calls through the daemon so port19222is never contested; inspectable via{"bridgeStatus": true}/await cua.getBridgeStatus()) and drives unfocused, per-agent color-coded"🤖 Agent"Tab Groups (active: false, with multi-windowwindow,windowId, andreuseExistingtab targeting) viachrome.debugger/chrome.scripting/chrome.tabGroupswith zero Chrome 144DevToolsActivePort"Allow remote debugging?"modal popups. Whenmode: "extension"(or"live"/requireExtension: true) is requested while disconnected,fmufails fast with an actionable setup diagnostic; when defaultmode: "chrome"targets an external URL without the extension connected,fmutags the headerbridge="headless-fallback"and emits an explicit! warning:(and! errors:ifels=0) instead of silently failing in an unauthenticated session. - Zero-Config Background Worker (
mode: "headless"& local dev URLs): When running in"headless"mode or against local/test URLs without the extension bridge,fmuuses a thread-safe background Playwright worker (fmu-pw-worker) with per-tab background focus and lifecycle emulation (Emulation.setFocusEmulationEnabled({enabled: true})+Page.setWebLifecycleState({state: "active"})).
- Live Logged-In Chrome via Outbound MV3 Extension WebSocket Bridge (
- Persistent
WeakMapUIDs (@u1..@uN) + Pre-Registered Table Row Folding (foldTables): Indexes all table rows inuidToRefso agents can target folded rows by label or UID while cutting initial dense table snapshots by >2.5×. - Native WebMCP (
navigator.modelContext) + Auto-Synthesized Virtual WebMCP Macros (~/.fmu/macros/): Detects page-registered WebMCP tools and allows agents to synthesize multi-step DOM trajectories into reusable 1-turn Virtual WebMCP tools (await tab.saveMacro(name, steps, desc)->await tab.callTool(name, args)), auto-loaded per domain in the# web ... webmcp=[...]header. - In-Browser
<canvas>/ WebGL Semantic OCR Fusion: Clip-captures<canvas>elements via CDP and runs Apple SiliconVision.framework(VNRecognizeTextRequest) viafmu-axto inject clickable@ocr1..@ocrN canvas-text "..." (x,y) [wxh]targets directly into the web snapshot (await tab.ocr()or automatic canvas detection) with 0 VLM image tokens. - Deterministic Rich-Text Editing & Zero-Dialog File Uploads: Replaces (or appends with
append: true) multi-blockcontenteditable/ Draft.js / ProseMirror editors in< 50 mswithout touching the system clipboard, and intercepts<input type="file">uploads via CDP (DOM.setFileInputFiles) so native macOSNSOpenPaneldialogs never open or get blocked by AppKit/TCC.
- Dual-Mode Zero-Popup Chrome Control:
-
Tier 2 — Native macOS Accessibility, Push-Based
AXObserver& Vision OCR (fmu_ax.swift/MacNativeEngine)- Persistent Unix Socket Daemon (
/tmp/fmu-ax.sock, universal2 binarybin/fmu-ax): Keeps a warm 4,000-elementAXUIElementLRU cache, PID/window cache, per-agent+/~/-diff baselines, and per-agent virtual cursors (VirtualCursorState) across turns. - Push-Based
AXObserverDirty-Subtree Tracking: Subscribes tokAXValueChangedNotification,kAXTitleChangedNotification,kAXCreatedNotification,kAXUIElementDestroyedNotification, and window/layout notifications on a dedicatedCFRunLoopthread (fmu-ax-observer). Turn 2+ unchanged or leaf-dirty snapshots short-circuit full AX tree walks in< 1 ms(obs=sequence telemetry). - Batched Attribute Reads, Non-Destructive Clipboard Hygiene & Multi-Window Guards: Batches reads via
AXUIElementCopyMultipleAttributeValues, lazily wakes background Electron/Chromium AX trees (AXManualAccessibility = true), never overwritesNSPasteboard.generalonop: "set"(verifyingAXTextArearead-back and detectingNSOpenPanelTCC-disabledOpenbuttons), and guardsCGEvent.postToPidkey routing when targeting a non-main window of a multi-window process. - 0-Vision-Token Apple Silicon Window & Canvas OCR: Built-in
CGWindowListCreateImage+ImageIO+VNRecognizeTextRequestengine (op: "ocr"/await app.ocr()) extracts clickable text and bounding boxes in< 70 ms. - Real-Time Pixel
fmu Live ViewHUD & One-Click Menu Bar Stop: Streams live pixels of the actual controlled background Chrome tab (Page.startScreencast+ async post-actionPage.captureScreenshotoverws://127.0.0.1:19222/ext) or native macOS app window (ScreenCaptureKit) into a non-activating floating PiP monitor with target cursor reticles,⤢HD Zoom (460px/740px,{"toggleZoom": true}),🎯 Highlight(fmu --highlight), draggable positioning, and instant⏹ Stop/▶ Resume(fmu --stop/fmu --resume).
- Persistent Unix Socket Daemon (
-
Tier 3 — Unified Multi-Cursor / Multi-Agent Stateful REPL, Warm Daemon & Context Hygiene (
FasterMacUseRuntime)- 268-Token Single-Tool Schema & Strict
stepsValidation: Supports OpenAI Codex-style statefulcua_replscripts (cua.createBrowserTab,cua.getTab,cua.getApp,cua.getBridgeStatus,cua.saveMacro,cua.listMacros,cua.getState,cua.getCursors), 1-trip declarativestepsbatches (withop/uidandaction/target/textnormalization plus explicit error reporting on missing or unsupported"op"), and concurrent multi-agent swarms ({"parallel": [{"agent": "agent-1", "code": "..."}, ...]}). - Per-Agent Isolation & Stale-Observation Masking: Each
AgentSessionhas independent REPL handles, virtual cursor(x, y)coordinates (tab.moveCursor/app.moveCursor), andContextWindowTracker18-token tombstones that replace superseded snapshots to prevent quadratic O(N²) context growth. - 50Hz Hardware Intrusion Guard (
BackgroundIntrusionGuard): Polls CoreGraphics (CGEventGetLocation+CGEventSourceSecondsSinceLastEventType) andlsappinfo frontat 50Hz to prove0.0 pxcursor displacement and0automated focus changes.
- 268-Token Single-Tool Schema & Strict
Quick Start
1. Install (1-Line uvx / uv tool / pip / Homebrew)
# Option A: Run or install directly from GitHub via uv / pip (includes universal2 fmu-ax binary + auto-compiler fallback)
uvx --from git+https://github.com/lifan-builds/faster-mac-use.git fmu mcp
uv tool install git+https://github.com/lifan-builds/faster-mac-use.git
pip install git+https://github.com/lifan-builds/faster-mac-use.git
# Option B: Clone for development
git clone https://github.com/lifan-builds/faster-mac-use.git
cd faster-mac-use
pip install -e .
# Option C: Homebrew Formula
brew install --Formula ./Formula/faster-mac-use.rb
2. Add to Your MCP Client (Claude Code, Codex, Cursor, Antigravity)
{
"mcpServers": {
"faster-mac-use": {
"command": "fmu",
"args": ["mcp"]
}
}
}
(Or point "command" to /path/to/faster-mac-use/bin/fmu.)
3. CLI Usage (fmu or ./bin/fmu)
# Native macOS Calculator in background (zero focus steal, <1ms AXObserver diff on Turn 2+)
./bin/fmu '{"surface":"app","app":"Calculator","steps":[{"op":"key","name":"escape"},{"op":"click","name":"7"},{"op":"click","name":"Multiply"},{"op":"click","name":"6"},{"op":"click","name":"Equals"}]}'
# Codex-style stateful cua_repl script + Virtual WebMCP macro recording
./bin/fmu '{"code":"let tab = await cua.createBrowserTab(\"chrome\", \"https://example.com\", {sessionName: \"🤖 Agent\"}); await tab.saveMacro(\"quick_lookup\", [{op: \"click\", uid: \"More information\"}], \"Click More info\");"}'
# Multi-cursor / multi-agent parallel execution across Chrome tabs + native macOS apps
./bin/fmu '{"parallel":[{"agent":"agent-1","code":"let t = await cua.createBrowserTab(\"chrome\", \"https://example.com\"); await t.move(\"More information\");"},{"agent":"agent-2","code":"let a = await cua.getApp(\"Calculator\"); await a.pressKey(\"escape\"); await a.click(\"8\");"}]}'
# Review real-world p50/p95/p99 latency, sub-phase breakdowns, and token efficiency (~/.fmu/logs)
./bin/fmu --perf 7
4. Run the 28-Test Unit & Integration Suite
PYTHONPATH=src python3 tests/test_fmu.py
5. Run the 5-Workload Competitor Benchmark Suite
PYTHONPATH=src python3 benchmarks/run_benchmarks.py
Results are written to benchmarks/results/latest_benchmark.md and benchmarks/results/latest_benchmark.json.
License
MIT © Lifan Chen
Metadata
Release files for faster-mac-use 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| faster_mac_use-0.1.0.tar.gz | 163.8 kB | With provenance | Details for faster_mac_use-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| faster_mac_use-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for faster_mac_use-0.1.0-py3-none-any.whl |
Total release size: 302.8 kB
Release files / faster_mac_use-0.1.0.tar.gz
| Download URL | faster_mac_use-0.1.0.tar.gz |
|---|---|
| Size | 163.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4bd6fedbcd37ba3b3d2e86af861c4d42f4891acbf441d32b68a096cadd91bcce
|
|
BLAKE2b-256 checksum How to use checksums |
9cc45e00bc1b981238d7366b1b530f3933650f07052bed4f9f1ab4f69a50c526
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / faster_mac_use-0.1.0-py3-none-any.whl
| Download URL | faster_mac_use-0.1.0-py3-none-any.whl |
|---|---|
| Size | 139.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2ffebf2ceb68d2f3a9d699ad3bfbd330188d64162f3d04b1396c6e5cf4e32343
|
|
BLAKE2b-256 checksum How to use checksums |
b20f975660531a04449d8bf8ac9d7469f7c309a284db824e73c86c1bab0f74ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for faster-mac-use 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for faster_mac_use-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.