Skip to main content

Operations

The harness should be understandable in failure, not only in success.

Operator surfaces

  • npm run harness -- doctor for prerequisites and path validation
  • npm run harness -- status for run visibility
  • npm run harness -- report for structured outcome review
  • npm run harness -- approve <runId> <taskId> for approval decisions
  • npm run harness -- cancel <taskId> for queued or active distributed tasks
  • npm run harness -- export <runId> for compliance-oriented evidence export
  • npm run harness -- diff <runId> <taskId> for task-level change review
  • approval flows for gated tasks
  • audit and compliance artifacts for deeper inspection

Default operator habits

  1. validate setup before the first run
  2. run one bounded task before scaling up
  3. inspect structured artifacts before diving into raw logs
  4. keep recovery behavior predictable and documented

✦Evidence before escalation

Read the report's verifier output, recovery summary, and routing ladder before changing models. The evidence usually tells you whether to narrow the task, fix the environment, or approve a recovery path.

Approval and recovery commands

Approve a task that is waiting for operator review:

npm run harness -- approve <runId> <taskId>

Reject it with an explanation:

npm run harness -- approve <runId> <taskId> --reject --comment "reason"

For a distributed task, request cancellation with:

npm run harness -- cancel <taskId>

The report and export surfaces preserve recovery, retry, failure-category, and approval evidence. Treat those artifacts as the source of truth when deciding whether to retry or narrow a task.

The controller and UI are local services by default. In a distributed setup, secure the configured controller host and any auth token before allowing remote workers to connect.

What good product behavior looks like

  • a new user can run one task without reading source
  • a failed run points to the next corrective action
  • example configs validate even in offline environments

Agent Terminal integration

Agent Terminal is the optional context and operator layer in front of Harness. When a run is launched from Terminal, Harness receives the bounded context pack, requested worker profile, task constraints, and verification commands. Terminal retains the run status and links the resulting artifacts back to the session that requested the work.

Configure the controller URL in Terminal:

export HARNESS_BASE_URL=http://127.0.0.1:5001

To configure Claude Code and Codex for the shared Terminal → Brain → Harness loop, run the Terminal installer once:

AGENT_TERMINAL_URL=http://127.0.0.1:4302 \
BRAIN_BASE_URL=http://127.0.0.1:9090 \
HARNESS_BASE_URL=http://127.0.0.1:5001 \
node scripts/setup-agent-integration.mjs

It preserves existing Claude settings and installs the codex-terminal launcher. Run one harmless task after setup, then verify Terminal history and the Harness run report before scaling up. Native Windows installs create a .cmd launcher under %LOCALAPPDATA%\AgentTerminal\bin.

Harness remains usable directly when Terminal is unavailable. In that mode, the run still follows Harness routing, approval, worker, and verification policy; only Terminal's session enrichment and cockpit view are absent.