harness

Declarative control plane for agent harnesses.

Overview

A coding agent like Claude Code is configured across half a dozen files: settings.json, CLAUDE.md, memory notes, MCP registrations, hook scripts, per-project overrides. No single file answers "what can this agent do right now, and why is it set up that way?" harness puts all of it in one zod-validated YAML manifest you read, validate, and diff; generates the config the agent runtime loads from it; and at runtime blocks tool calls through one enforcing gate, branch-protection. The branch-protection gate asks git and records nothing. Most config tools describe what an agent is configured to use; harness decides what it is allowed to do, under the exact context.

Key concepts

| Term | What it is | |------|-----------| | manifest | The one YAML file (harness.yaml) where you declare everything: grounding, tools, memory, hooks, policy packs. | | apply | harness apply renders the manifest into the config files the agent runtime actually reads. | | gate switch | harness gate disable / harness gate enable: the operator kill switch. Disable removes the hook groups whose matcher substring-matches --matcher <substring> from ~/.claude/settings.json (with --runtime codex, neutralises the matching units of the managed block in ~/.codex/config.toml) and keeps a snapshot; enable restores them. | | hook | A script the agent runtime runs at a lifecycle event (session start, before every tool call, ...). How gates get wired in. | | policy pack | A bundle of hooks and instructions shipped under one name and enabled with a single manifest key (policy_packs[], via harness pack add <name>). |

Quick start

npm i -g @lannguyensi/harness                            # Node 20 or newer
harness init                                             # minimal manifest, no policies
harness pack add branch-protection                       # the one recommended pack
harness validate
harness apply --target ~/.claude/settings.json --merge   # Claude Code; then restart it
harness apply --runtime codex --install                  # Codex, if you use it; then restart it

From then on, while an agent works in a repository on master, main or develop, its edits there through the file-editing tools (Write and Edit under Claude Code, apply_patch under Codex) are refused until it cuts a feature branch (git checkout -b <feature>). Codex runs the new hooks only once you trust them in its startup hook review. The step-by-step version, with what each command writes: docs/quickstart.md. Full operator walkthrough: docs/for-humans.md (it starts from the wizard and the solo template).

Upgrading? A manifest that still names a pack or key removed in 1.0.0 loads with a warning and the entry is ignored; see docs/CLI.md#removed-keys-packs-and-commands.

Usage

See the gate decide without starting an agent: from inside a repository, pipe a sample Write event into the hook Claude Code runs before every Write or Edit.

echo '{"session_id":"demo","tool_name":"Write","tool_input":{"file_path":"README.md"}}' \
  | harness pack hook branch-protection

On a protected branch it prints a deny decision naming the branch and the protected list; on a feature branch it allows the edit and says why on stderr. The protected-branch list, the agent-facing message and the operator controls are documented in docs/policy-packs/branch-protection.md.

Documentation

• docs/for-humans.md: operator path, install through the first refusing gate, diagnostics cheat sheet.
• docs/for-agents.md: agent integration contract, workflow lifecycle, CLI cheat sheet by side-effect class.
• docs/quickstart.md: five-minute bare-command path to the branch-protection gate.
• docs/init-interactive.md: the harness init --interactive wizard, walkthrough and limitations.
• docs/CLI.md: every CLI verb, grouped by purpose.
• docs/policy-packs/README.md: the built-in policy pack (branch-protection).
• docs/uninstall.md: the single-command teardown, dry-run by default.
• docs/examples/full-manifest.yaml: a schema-coverage reference (not a runnable config; its header explains why).
• docs/ARCHITECTURE.md: the architecture reference: manifest schema, file layout, CLI surface.
• docs/VISION.md: why a declarative control plane, not more individual tools.
• CHANGELOG.md: what shipped in each version.

Related projects

• agent-grounding: evidence-ledger and claim surfaces outside harness; grounding-mcp is the MCP server harness can register and point at the ledger path (EVIDENCE_LEDGER_DB), and harness itself queries nothing there.
• agent-memory: the memory surfaces the control plane inventories.
• agent-tasks: MCP-registered task platform whose registration and health appear in harness describe.
• agent-preflight: a standalone local preflight validator an operator can call directly or from a custom hook.
• codebase-oracle: opt-in MCP for multi-repo RAG search; declare it with harness add mcp codebase-oracle --command codebase-oracle,mcp, then register it with Claude Code using the claude mcp add-json command harness doctor prints.
• agent-dx: ships git-batch-cli, a day-to-day tool whose inventory appears in harness describe.

Development and contributing

npm install
npm run build
npm test

See CONTRIBUTING.md for the full PR checklist (import-boundary and duplication gates, changelog coverage, release steps).

Status

The current release is v1.0.1. What shipped in each version is in CHANGELOG.md.

License

MIT, see LICENSE.