<div align="center">

<p>
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/northcua-logo-dark.svg">
    <img src="docs/assets/brand/northcua-logo.svg" width="360" height="96" alt="NorthCUA">
  </picture>
</p>

**Worlds in mind. Wonders at your fingertips.**

The NorthCUA Harness for desktop and web agents.

[Quick start](#quick-start) · [Documentation](docs/README.md) · [System tour](docs/system-tour.md) · [Technical report](docs/paper/main.pdf) · [中文](README.zh-CN.md)

[From zero](docs/first-run.md) · [Local batch](docs/local-batch.md) · [Agent skill](skills/northcua/SKILL.md)

Python 3.12+ · Apache-2.0 · Built on [NexAU](https://github.com/nex-agi/NexAU)

</div>

**NorthCUA** is the project described in *NexCUA Technical Report: Turbocharging
Computer-Use Agents through Experience at Scale*. This repository currently provides
its **NorthCUA Harness**: Desktop/Web execution, long-horizon context and working memory,
outcome evaluation, and batch orchestration, built on public [NexAU](https://github.com/nex-agi/NexAU).

The harness carries a computer-use task from its initial workspace to an inspectable
result. Desktop and Web agents share execution, context, memory, evaluation and recording
services while using tools suited to their interfaces. The same foundation supports a
single local task and controller-managed batches with isolated task environments.

[![NorthCUA task lifecycle: prepare a workspace, execute with long-horizon context, inspect the live outcome, preserve records, and release resources.](docs/assets/harness-lifecycle.png)](docs/system-tour.md)

*Architecture illustration from the report. GUI scenes and trajectories are illustrative;
executed validation is documented separately in the [verification record](docs/verification.md).*

## Inside the NorthCUA Harness

Computer-use work extends beyond issuing a click. A later action may depend on a value
read several applications ago, an exported file may need inspection, and a stopped
controller may need to recover a completed attempt without running it again. NorthCUA
connects these responsibilities through one task lifecycle.

| Capability | What it gives you |
|---|---|
| **Desktop and Web, one runtime** | Native screenshots and mouse/keyboard input for Desktop; screenshots, DOM references, forms and tabs for Web. Shared session, round and step contracts keep execution consistent. |
| **Context for long tasks** | Bounded visual history, pre-action overlays, task-preserving compaction, and durable agent-written notes carry useful state into later decisions. The complete trace remains available for inspection. |
| **Evaluation in the original workspace** | A separate evaluator can retrieve recorded evidence and inspect live task state before the environment closes. Actor completion and evaluator verdict remain separate. |
| **Batch execution with recovery** | Centralized model execution, device workers, fresh environments, task-bound preparation, persistent claims and reconciliation coordinate attempts through artifact delivery and cleanup. |

The [system tour](docs/system-tour.md) explains how these pieces fit together.
The [paper map](docs/paper-map.md) connects each mechanism to its implementation and tests.

## Quick start

New to the project? Follow [the complete first-run tutorial](docs/first-run.md)
for copyable model settings, a no-key local demo and concrete success checks.
Coding assistants can start with [the operator skill](skills/northcua/SKILL.md).

The current candidate is hosted at the existing NorthCUA repository on
`codex/northcua-clean-open-source`. The Python packages and CLI retain the Harness
name `northcua`. Use Python 3.12+,
[uv](https://docs.astral.sh/uv/), and a vision model endpoint that supports tool calls.

```sh
git clone --branch codex/northcua-clean-open-source \
  https://github.com/china-qijizhifeng/NorthCUA.git nexcua
cd nexcua
uv sync --locked --extra local --extra device
uv run --no-sync playwright install chromium

export OPENAI_API_KEY='your-key'
export NORTHCUA_MODEL='your-vision-model'
uv run --no-sync northcua config validate --app-config config/app.example.yaml
uv run --no-sync northcua local web run --app-config config/app.example.yaml \
  --url https://example.com --query 'Report the main heading.' --max-steps 8
```

The sample uses the OpenAI-compatible Chat interface. Configure the model, endpoint and
API type in the agent YAML for [Chat, Responses, Anthropic or Gemini](docs/configuration.md#providers).
For Linux browser dependencies, use `playwright install --with-deps chromium`.
[Installation](docs/getting-started.md) also covers wheel-only deployment and desktop permissions.

On an interactive desktop:

```sh
uv run --no-sync northcua local desktop run --app-config config/app.example.yaml \
  --query 'Open the file manager and report the visible folder names.' --max-steps 15
```

Desktop uses the active GUI session and receives post-action screenshots directly from
its tools. It has one observation path; no mode selection is needed. The native adapters target Linux X11, macOS and
Windows; permissions and completed platform checks are listed in the
[execution matrix](docs/verification.md#execution-matrix).

## Inspect the result

A run retains step records, model/tool traces, visual evidence and its terminal result.
Working notes are saved independently of prompt history. Enable the evaluator to collect
an additional outcome report while the original browser is still available:

```sh
uv run --no-sync northcua local web run --app-config config/app.example.yaml \
  --url https://example.com --query 'Report the main heading.' \
  --session-id first-web --max-steps 8 --evaluate
```

Live probes are an explicit configuration choice. Follow the
[evaluation guide](docs/evaluation.md) to enable them and open the optional trace viewer.
That guide also explains fail-open/fail-closed behavior and artifact-only re-evaluation.

## Reproduce a local smoke test

You can check the integration without hosted-model credentials. This runs a real browser
through the real NexAU provider path against a deterministic local model endpoint:

```sh
uv sync --locked --extra local --extra device --extra dev
NORTHCUA_RUN_BROWSER_TESTS=1 uv run --no-sync pytest \
  tests/integration/test_web_modes.py -q
```

The actor changes page state; the evaluator must inspect that same browser session.
The suite exercises local, WebSocket and controller entry points. It verifies runtime
wiring and evidence delivery. It is not a benchmark of model capability.

## Run where the task lives

| Workflow | Start here |
|---|---|
| One task on your own computer | [Install and run](docs/getting-started.md) |
| Repeated requests through a local server | [WebSocket serving](docs/running.md#local-websocket-server) |
| Central models, tools on a device worker | [Controller and worker](docs/running.md#controller-and-worker) |
| Many isolated tasks with retries and resume | [Batch execution](docs/batch.md) |
| Public sandbox templates or upstream OSWorld tasks | [Environments and adapters](docs/environments.md) |
| Understand a failure or inspect an output | [Evaluation and artifacts](docs/evaluation.md) |
| Add tools or integrate another task source | [Architecture](docs/architecture.md) and [contributing](CONTRIBUTING.md) |

## Research and release status

**0.2.0 is a release candidate.** The bundled report is the 2026-10-03 research draft;
its benchmark tables remain pending. This NorthCUA release provides the Desktop/Web NorthCUA Harness.
The report's Experience Flywheel, grounding-data production, staged training and proposed
recursive collection methods belong to the broader research system.

Local regression tests and selected real-browser/native workflows have executed,
and independent review agents have provided scoped signoffs. The
[verification record](docs/verification.md) identifies the exact checks, dates, failures
repaired and remaining gates. Hosted-model capability, real E2B/OSWorld environments,
Windows physical input and remote CI acceptance require their own evidence.

## Contribute and cite

Start with [contributing](CONTRIBUTING.md), [testing](docs/testing.md), and the
[clean scope](docs/clean-scope.md). Public NexAU is pinned to
`c98f7fb73f41f338e462d0585c62c1e62362b693`; four coordinated wheels package the agent,
device worker, protocol and shared runtime. Source and wheel instructions are provided;
this candidate does not assume a PyPI release already exists.

If you use the harness in research, cite the report and record this repository's commit, the NexAU revision,
model configuration, task source and evaluation protocol. Citation metadata is in
[CITATION.cff](CITATION.cff); the [paper manifest](docs/paper/manifest.json) identifies
the exact distributed draft. No DOI or arXiv identifier has been assigned in this repository.

[Apache-2.0](LICENSE) · [Notice](NOTICE) · [Security](SECURITY.md) · [Changelog](CHANGELOG.md)