Installation

pnpm add -D @agentskit/harness   # or: npm i -D @agentskit/harness

The package exposes two binaries: ak-harness (everything) and ak-verify (the same binary under the common verification-protocol name). Node.js 22 or newer.

What has to be there

Requirement	Why	What happens without it
A git repository with a committed `HEAD`	Evidence is bound to a revision; a repository with no first commit cannot prove currentness	`GIT_REQUIRED`
At least one coding-agent CLI on `PATH`	The worker is that CLI, running in its own worktree	`loop doctor` reports the role as unroutable and `tick` dispatches nothing
A runner: Orca, or git + tmux + cron	Where a worker actually runs	`connectors.runner` decides; `local` needs `tmux` and a crontab
A tracker the loop can read	The queue	`loop doctor` fails the `linear.queue` check
`gh`, authenticated	Pull requests, checks, comments, merge	`deliver` cannot see or merge anything
`agentskit-review` on `PATH`	The adversarial review	`loop doctor` warns; `deliver` cannot review until it is installed

Run ak-harness loop doctor before anything else. It answers all of the above at once, without dispatching.

Where state lives

project.stateDir — .ak-loop by default, next to loop.config.yaml, and gitignored. Inside it:

Path	What it holds
`events.ndjson`	Every event, append-only, rotated by size
`issues/<id>/contract.json`	The frozen contract
`issues/<id>/plan.json`	The approved plan and the votes that approved it
`issues/<id>/dispatch.json`	Who is working on it, where, since when
`issues/<id>/delivery.json`	Fix rounds, nudges, handoffs, the final outcome
`release.json`	The current approval and the release history
`plans/<id>/state.json`	A `loop plan` run, from objective to issues

Nothing else. No daemon, no database, no background process: every command reads those files, does its pass, and exits.

Providers

Each entry under models.providers is a CLI the harness knows how to launch:

models:
  providers:
    codex:
      bin: codex
      auth: subscription
      tui: codex -m {model} -s danger-full-access -a never
      headless: [codex, exec, --model, '{model}', '{prompt}']
      effortFlag: -c model_reasoning_effort={effort}

tui is what runs in a worker's terminal; headless is what the harness calls for its own work (freezing a contract, writing a plan, casting a vote). A provider with no headless template can still build, but cannot be an orchestrator.

One trap worth knowing: Codex's workspace-write sandbox blocks .git writes and has no network. A codex worker that cannot commit or push needs -s danger-full-access (or an equivalently open sandbox) in its tui.

What has to be there

Where state lives

Providers

On this page