LongHorizon-Harness: A Three-Role Loop That Keeps AI Agents Alive on Long Tasks

Project Overview

LongHorizon-Harness is a loop engineering system open-sourced by Amap (高德). It does not train new models or replace existing agents; instead, it adds a persistent execution loop around Claude Code, Codex CLI, OpenCode, and DeepSeek Harness. The goal: give a single instruction and let the agent work across desktop apps and terminals for dozens of hours, continuously recovering goals and verified state, picking the next bounded sub-step, executing with a fresh context, checking results in the real environment, and persisting verified progress or feeding failure evidence to the next round.

Core Capabilities

Three-Role Isolation Loop (MEA) : Manager plans the next sub-task, Executor runs with a fresh context, Auditor performs read-only verification of the real environment. Any completion claim must be backed by an audit report.

Audit Facts as Sole Cross-Round Memory : The executor's raw trajectory and reasoning are discarded; only the audit report enters the task state, preventing "self-assessed progress" from contaminating later decisions.

Backend-Agnostic : The AgentAdapter protocol is minimal (a single run_episode method). Claude Code, Codex, OpenCode, DeepSeek Harness can each serve any role, with independent model and reasoning-effort settings per role.

GUI + CLI Dual Surface : Uses codex-computer-use, open-computer-use, and claudcursor plugins to operate desktop apps (browsers, office, design, 3D tools) and terminals interchangeably within one task.

Recoverable Persistent Ledger : Each round writes to runs/<run-id>/, supporting resume, a web dashboard, and follow-up conversational continuation.

Role-Level Permission Isolation : In Claude Code mode, --disallowedTools injects write bans for Manager/Auditor; Auditor also snapshots the workspace diff — any change triggers an integrity violation and rollback.

Human Gate : On completion, block, need-input, or repeated failure, the dashboard prompts the user to answer, extend budget, or inject instructions.

Quick Start

Requirements

Python 3.10+

(recommended install via uv)

At least one agent runtime on PATH: claude, codex, opencode, or dsh For GUI: Node.js 20+ plus the corresponding computer-use plugin

Primarily tested on macOS; Windows support included but not fully validated

Installation

uv tool install lh-harness   # or pip install lh-harness

For GUI, choose one plugin:

lh-harness plugin install codex-computer-use   # Codex only
lh-harness plugin install open-computer-use    # Claude Code / Codex

On macOS, grant Accessibility and Screen Recording permissions, then re-run the install command to verify.

Project Config

cd /path/to/your/project
lh-harness init   # generates ./.lh-harness/config.toml

Run a Task

CLI:

lh-harness run --task "Inspect the current directory and summarize its files." \
  --agent codex --model gpt-5.6-sol --max-rounds 30

Web dashboard (recommended, shows each round's plan/execute/audit evidence):

lh-harness web --workspace-root .
# opens http://127.0.0.1:8799/

Task text can be read from a file with @task.md. Per-role agent/model selection:

lh-harness run --task @task.md \
  --manager-agent claude_code --manager-model opus-4-7 \
  --cli-executor-agent codex --cli-executor-model gpt-5.6-sol \
  --auditor-agent opencode --auditor-model qwen3.7-plus

Why Long Context Isn't the Answer — A State Machine Is

Long-running agents (tens of minutes to hours) suffer from three problems: error accumulation , context corruption , and task state loss . LongHorizon-Harness reframes long execution as a task state management problem . State lives outside execution and is updated only with independently verified facts . This is implemented as the Manage-Execute-Audit loop.

The key difference from traditional agents: a single session that self-evaluates vs. three roles that cannot self-assess. The executor's self-report is not recorded; the audit report is. This design blocks unverified premises from entering the record and cascading into later decisions.

Commands & Configuration

Commands

lh-harness run

— Run a long-horizon task (core entry) lh-harness web — Start FastAPI web control service (dashboard) lh-harness dashboard — Browse completed and running tasks (same dashboard, different semantics) lh-harness doctor — Read-only environment check: Python, agent CLIs, Node.js, plugins lh-harness plugin — Install/uninstall computer-use plugins ( list / install / uninstall) lh-harness init — Generate

./.lh-harness/config.toml

lh-harness check-update

— Check PyPI for new version

Key config.toml Fields

agent

— Default agent backend for all roles model — Default model for all roles reasoning_effort — Reasoning depth, passed to supporting backends max_rounds — MEA round budget runs_root — Run directory root workspace — Agent working directory (defaults to launch directory) prompt_language — Prompt language: en or

zh

dashboard

— Whether to start dashboard per run claude_mcp_config / codex_mcp_config — Custom MCP config paths mcp_add_dirs — Extra directories readable by MCP servers

MEA Loop Breakdown

The main loop is while round_index < round_budget, executing three roles per round.

Step 1: Manager Re-plans

Manager sees only the original task, its own task state, and audit reports — never raw trajectories or previous full prompts. Its output is a structured plan with a five-way routing:

Next: gui      → dispatch GUI executor
Next: cli      → dispatch CLI executor
Next: done     → declare completion
Next: blocked  → declare blocked
Next: ask      → need user input

It maintains two persistent fields: task_state (what's done, what's pending) and task_contract (current sub-task contract), parsed via extract_role_task_state / extract_role_task_contract into round_dir/task_state.txt.

Manager saying done does not count. The loop first checks the latest audit report for status=complete, integrity=clean, and contract_audit=aligned simultaneously. If not satisfied, a repair report is synthesized and fed back to the next Manager round.

Step 2: Executor Executes

Routed to gui or cli, the corresponding executor agent and budget are selected (GUI and CLI can use different backends). The executor receives: original task, Manager's plan, task state, rules, and relevant audit reports referenced by current rules .

After execution, the raw trajectory is written to executor_raw_trajectory.jsonl and then removed from cross-round memory . Only executor_output (natural language) is kept and passed to the auditor. GUI sub-tasks also capture a final screenshot.

Step 3: Auditor Verifies

The auditor is the final checkpoint. Its prompt includes: original task, Manager's plan, executor output, task state, contract, relevant audit reports, and workspace path. It never sees the executor's raw trajectory and can only inspect the environment via read-only tools.

Audit report format (machine-parseable):

Status: complete | incomplete
Integrity: clean | suspect | violation
Contract audit: aligned | misaligned | unknown

Because the auditor is an LLM, one automated repair pass is allowed to avoid "auditor gets one line wrong, whole task wasted".

Round End: Human Gate

Based on the round outcome (completed, blocked, round limit, repeated failure), a human gate may trigger. The operator can continue (extend budget), stop, or inject instructions. Queued operator messages are merged into the next Manager prompt, enabling post-run follow-up and continuation.

Full Data Flow of Round i

Original task + task state
  │  build_role_manager_prompt (no raw trajectory)
  ▼
① Manager (fresh context)
  │  Output Next: gui/cli/ask/done/blocked + task_state + task_contract
  │  done must be backed by recent audit report, else synthesize repair_report and return
  ▼
② Executor (fresh context, GUI/CLI)
  │  Execute sub-task → raw trajectory jsonl archived then discarded → keep executor_output
  │  GUI sub-task adds final screenshot
  ▼
③ Auditor (fresh context, read-only)
  │  Inspect real env → output three control lines + audit facts
  │  Workspace modified during audit → integrity=violation + snapshot rollback
  ▼
Audit report written to round record (sole cross-round memory)
  │  _human_gate decision: completed / blocked / progress
  ├─ Continue → round_index+1 → back to ①
  ├─ Round limit reached → human gate decides extend/terminate
  └─ Completed → final_response role writes final answer from verified state

Benchmark Results — Gains from Harness Swap, Not Model Swap

Official evaluation on three public benchmarks, all rows using Qwen 3.7-Plus as main model and Claude Code as execution backend:

WeaveBench (8 domains): all improved . DOM 47.1% → 76.5%, GAM 29.4% → 58.8%, SPA domain +60 percentage points.

OSWorld 2.0 : 34-task subset with Claude Opus 4.7. Binary score 20.6 → 35.3 (+14.7), proving gains come from the framework, not a specific model — "main model decides per-round action quality; harness decides how much verified outcome survives across rounds".

Cost : Manager uses only 2.0%-8.1% of total tokens; Auditor is the largest share (19.4%-38.1%). On Terminal-Bench 2.1, LH-Harness used 24% fewer tokens than baseline while scoring 7.5 points higher.

Summary

LongHorizon-Harness

is a research-grade harness that restructures long-horizon AI computer operation into a task state machine: Manager plans, Executor executes, Auditor verifies. Only independently verified facts enter cross-round memory. It improves the probability that model capabilities survive to task completion without improving the models themselves.

References

Repository: https://github.com/AMAP-ML/LongHorizon-Harness
Documentation: https://lh-harness.pages.dev
Paper: https://arxiv.org/abs/2608.01964