suite

harness

Workflow engine for tracked test work against Kubernetes and Kuma clusters. Harness manages disposable environments, suite authoring, tracked execution, live session inspection, and cross-agent coordination for Claude, Codex, Gemini, Copilot, and OpenCode.

For the internal module map, see ARCHITECTURE.md.

Install

mise run install

Builds a release binary and installs harness to ~/.local/bin. Requires Rust 1.94+.

Commands

setup - environment and cluster preparation

harness setup bootstrap [--agents <claude,codex,gemini,copilot,opencode>]
harness setup agents generate [--check]
harness setup kuma <topology> <name> [flags]
harness setup gateway [--kubeconfig <path>] [--repo-root <path>]
harness setup capabilities

bootstrap wires agent runtimes into the project. Without --agents, it installs every supported runtime. With --agents, it narrows to the listed subset. agents generate renders shared assets from agents/ into host-specific directories. kuma creates or attaches to a cluster. gateway installs Gateway API CRDs. capabilities reports what features and providers are available and ready on this machine right now.

Generation and bootstrap expose the session entrypoints as harness:session:start and harness:session:join across the supported agent surfaces. Codex also gets direct mirrors under .agents/skills/, because repo-local plugin bundles alone are not enough for Codex skill discovery.

create - suite authoring

harness create begin
harness create save
harness create show [--kind <session|approval>]
harness create reset
harness create validate
harness create approval-begin

Guided workflow for writing new suites. begin starts the workspace, approval-begin starts the hook-enforced approval gate, validate checks content against the schema.

run - tracked execution

harness run start --suite <path> --run-id <id> --profile <profile>
harness run init
harness run preflight
harness run capture
harness run record -- <command> [args...]
harness run apply --manifest <path>
harness run validate [--manifest <path>]
harness run restart-namespace [--namespace <ns>]
harness run task <name> [args...]
harness run status
harness run logs [--namespace <ns>]
harness run cluster-check
harness run envoy <subcommand>
harness run kuma <subcommand>
harness run diff [--manifest <path>]
harness run doctor
harness run repair
harness run runner-state
harness run resume [--run-id <id>]
harness run report
harness run closeout
harness run finish

start creates a new tracked run. init and preflight prepare the cluster. apply, record, validate, and capture are the core work loop. doctor and repair diagnose and fix broken run state. finish and closeout end the run and write the report.

observe - live session inspection

harness observe [--agent <agent>] [--observe-id <id>] scan [session_id] [--action <action>]
harness observe [--agent <agent>] [--observe-id <id>] watch <session_id> [--poll-interval <s>] [--timeout <s>]
harness observe [--agent <agent>] [--observe-id <id>] dump <session_id> [--from-line <n>] [--to-line <n>] [--filter <text>]
harness observe [--agent <agent>] [--observe-id <id>] doctor [--json]

Four modes:

• scan classifies issues in a session log. Supports maintenance actions: cycle, status, resume, verify, resolve-from, compare, list-categories, list-focus-presets, mute, unmute.
• watch continuously polls for new events in a live session.
• dump prints raw events without classification. Supports line ranges, text and role filters, tool name filters, and raw JSON output.
• doctor validates observe wiring, session pointers, and compact handoff state.

agents - cross-agent lifecycle

harness agents session-start --agent <agent> [--session-id <id>]
harness agents session-stop --agent <agent>
harness agents prompt-submit --agent <agent>

Runtime API for cross-agent coordination. Generated hooks call these commands to register sessions, record prompt events, and clean up state. The shared agent ledger lives under the harness project directory, not in host-native transcript storage.

session - multi-agent orchestration