# arc-cua

> Superfast action layer for computer-use agents, powered by decision models.

arc-cua lets a planner or CUA agent hand off bounded desktop subtasks to a fast decision model (JEV) that executes the UI loop. No frontier model needed for every click.

## Key concepts

- Subtask contract: The upstream agent defines goal, literal inputs, constraints, and verification criteria. The executor never invents text or verification.
- Caller-supplied shortcuts: Subtask.shortcuts maps keyboard chords to descriptions (for example, MOD+S to Save). JEV chooses from defaults plus these task-local choices. Defaults remain unchanged; undeclared non-default hotkeys are rejected.
- JEV (Judge-Evaluate-Verify): Fast decision backend by TypeSafe. Given structured desktop state, it selects the next UI operation from a dynamically built action space.
- Hybrid perception: macOS Accessibility (AX) for semantic controls + Apple Vision OCR for visible text. Both normalize into DesktopElements.
- Background control: the macOS backends act on one app by process ID, without moving the user's pointer, raising the window or changing the front app.
- Driver: arc_cua.Driver, or `arc-cua mcp` as MCP tools, reads and controls macOS apps in the background with no decision model: observe, act (refused with a fresh snapshot when the app changed since the observation), wait, menu commands, screenshots and raw input at window points. Works in minimized windows and hidden apps.
- Command line: `arc-cua run` reads one JSON request (app, subtask, provider) from stdin, prints one JSON line per action and a final result line, and exits.
- Freshness guards: SHA-256 fingerprints on element state prevent stale execution. A mutation is never applied against an outdated target.
- Post-action settling: After a mutating action, the runtime re-observes the desktop until structurally stable.
- Terminal states: SUBTASK_COMPLETE (verification criteria satisfied), BLOCKED (cannot progress), NEEDS_AGENT (higher-level reasoning required).
- Observability: run_iter() yields StepEvents after each decision cycle for live monitoring.

## Install

```
pip install 'arc-cua[macos]'
export TYPESAFE_API_KEY=...   # only for the decision-model action layer
```

Requires macOS with Accessibility and Screen Recording permissions.

## Links

- Full documentation: https://arc.tryisle.com/llms-full.txt
- Source: https://github.com/shhivv/arc-cua

## Sections in llms-full.txt

- Quick start
- Architecture
- Subtask contract
- API reference: all types, classes, functions
- Protocols: DesktopBackend, DecisionPolicy
- Runtime configuration
- Backends: MacOSHybridBackend, MacOSAXBackend, ChromeBackend, StateMachineBackend
- Policies: ChoicePolicy (any ChoiceTransport), TypeSafeJevPolicy, ScriptedPolicy
- Error types
- Extending arc-cua
