LongHorizon-Harness

Advancing Long-Horizon Agents for Real-World Tasks

Operate the whole computer like a human. Work across desktop apps and the command line for dozens of hours.

No state drift. Verifiable progress. Complex tasks carried through to completion.

Usage · What You Get · How It Works · Results · Project Website · 简体中文

The model determines what an agent can do in one round. LongHorizon-Harness determines whether that work can be verified, preserved, and continued until the task is actually complete.

Works with Claude Code and Codex. One-command install, ready to run.

LongHorizon-Harness is an execution, state-management, and result-verification system for long-horizon tasks. It does not train a new model or replace an existing agent. It runs on top of systems such as Codex and Claude Code, helping agents operate autonomously in real computer environments for extended periods and continuously move complex tasks forward.

✨ News

🚀 We’re iterating rapidly. Stay tuned!

Video Demo

https://github.com/user-attachments/assets/ca8b77ce-9220-4d85-a272-b346009b2454

Open the promotional video (1440p MP4)

Three roles. One trusted state.

LongHorizon-Harness separates planning, execution, and verification so that one growing context is not responsible for everything.

Only results that pass independent verification enter persistent task state. Even when the context is refreshed, an action fails, or a deliverable does not pass inspection, the system retains previously verified progress and continues from what remains.

Desktop apps and CLI. One continuous task.

LongHorizon-Harness supports both GUI and CLI workflows.

One task can begin in a browser, move to the command line for data processing, continue in desktop software to produce an artifact, and return to the terminal for validation or debugging. The goal, progress, and evidence remain under the same state-management system throughout.

Any model. Any agent backend.

LongHorizon-Harness is not tied to a specific model or agent backend. Existing models and agents connect through configuration without changing their original workflows.

A lightweight AgentAdapter preserves each agent's native execution loop while LongHorizon-Harness coordinates role boundaries, verified task state, and cross-round progress around it.

Use one model for all three roles, or combine different models and backends to balance quality, speed, and cost.

Hundreds of real tasks. Measured gains.

LongHorizon-Harness is not demonstrated only on a handful of carefully selected success cases.

We ran it on hundreds of complex tasks across GUI, CLI, and mixed computer environments:

Same model. Same execution backend. Only the harness changes.

📊 Full benchmark results and experimental settings

_{All rows use Qwen 3.7-Plus as the backbone and Claude Code as the execution backend.}

Full result tables and case trajectories are available on the LongHorizon-Harness project website.

One command. Full visibility.

Quick start

For detailed setup and configuration options, see Installation.

1. Install LongHorizon-Harness:

uv tool install lh-harness

1. Check the environment, then explicitly install and enable the Codex GUI plugin:

lh-harness doctor
lh-harness doctor --install-codex-gui

1. Enter your project and generate its configuration:

cd /path/to/your/project
lh-harness init

1. Open .lh-harness/config.toml and adjust the defaults if needed. The generated configuration uses Codex, gpt-5.6-sol, and an enabled Dashboard by default.

2. Run a task:

lh-harness run --task "hi"

The Dashboard opens automatically and shows the complete Manager → Executor → Auditor workflow.

Installation

Requirements

• Python 3.10 or later
• uv for the recommended isolated installation method
• At least one supported agent runtime available on PATH:
  • claude — Claude Code CLI
  • codex — Codex CLI

Install with uv

uv tool install lh-harness

To upgrade an existing installation:

uv tool upgrade lh-harness

Install with pip

pip install lh-harness

Generate a project configuration

lh-harness init

This creates ./.lh-harness/config.toml without replacing an existing file. Use lh-harness init --force only when you want to regenerate it.

When lh-harness run starts, it reads this file automatically. Configuration precedence is:

1. Explicit CLI arguments
2. Values in ./.lh-harness/config.toml
3. Built-in defaults

The generated file includes run storage, Agent/model assignment, role timeouts, MCP, prompt language, and Dashboard defaults. Task text, run IDs, and API keys remain command-line or environment inputs and are not stored in the generated configuration.

Check the installation, Python runtime, available agent CLIs, and Codex GUI support:

lh-harness doctor

doctor also checks PyPI for updates with a 3-second timeout. When automatic detection fails, the output points to the PyPI page for a manual check.

To check for updates directly:

lh-harness check-update

Codex Computer Use setup is intentionally separate from task execution. To explicitly install and enable the official plugin:

lh-harness doctor --install-codex-gui

To remove the plugin:

lh-harness doctor --uninstall-codex-gui

Plain lh-harness doctor only checks status. Running lh-harness run never installs, removes, or changes Codex plugins.

Configure a computer-use MCP server

GUI interaction is supplied through a compatible external computer-use MCP server. LongHorizon-Harness does not bundle or enable a specific computer-use implementation by default.

Both Claude Code and Codex accept a Claude-style MCP configuration through --mcp-config. Codex translates this configuration into its native command-line overrides. Use simple server names containing letters, numbers, hyphens, or underscores.

Example configuration for a local stdio MCP server:

{
  "mcpServers": {
    "computer-use": {
      "command": "/path/to/mcp-server",
      "args": ["--option", "value"],
      "env": {
        "EXAMPLE_VARIABLE": "value"
      }
    }
  }
}

Example configuration for an HTTP MCP server:

{
  "mcpServers": {
    "computer-use": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Run the harness with the MCP configuration and any directories that the agent needs to access:

lh-harness run --task @task.md --agent claude_code \
  --mcp-config /path/to/mcp.json \
  --mcp-add-dir /path/to/mcp/files

The same configuration works with Codex:

lh-harness run --task @task.md --agent codex \
  --mcp-config /path/to/mcp.json \
  --mcp-add-dir /path/to/mcp/files

--mcp-add-dir may be repeated. MCP configuration and additional directories can also be supplied through environment variables:

Separate multiple directories using the operating system path separator (: on macOS/Linux and ; on Windows). Avoid storing API keys directly in the MCP JSON file when the MCP server can read them from its environment.

Dashboard commands

lh-harness run --task @task.md --dashboard      # Monitor a live run
lh-harness dashboard                            # Browse completed and active runs

Common CLI options

Run a task:

lh-harness run \
  --task "Inspect the current directory and summarize its files."

Run a longer task from a file and open the Dashboard:

lh-harness run --task @task.md --dashboard

The Dashboard shows every round's plan, execution result, audit evidence, and reason for rework. It also provides human gates when a task completes, becomes blocked, needs input, or fails repeatedly.

Every run is stored in an isolated runs/<run-id>/ directory. The complete task state and audit trail make the agent's progress inspectable, recoverable, and reproducible.

Evaluation Reproduction

eval/ provides frozen reproduction suites for two benchmarks:

See each directory's README.md or README.zh-CN.md for environment setup, parameters, and launch commands. The nested cua_harness packages are frozen compatibility copies used for evaluation; new integrations should use src/lh_harness/.

Citation

@article{longhorizonharness2026,
  title={LongHorizon-Harness: Advancing Long-Horizon Agents for Real-World Tasks},
  author={Ziyu Ma and Hailang Huang and Shun Zou and Yong Wang and Shidong Yang and Yiming Hu and Fei Wei and XiangXiang Chu},
  journal={arXiv preprint arXiv:2608.01964},
  year   = {2026},
  url    = {https://arxiv.org/abs/2608.01964}
}