For Claude Code · Codex · opencode · pi

Rules your coding agents can’t quietly rewrite.

Harness Decision Records keep your team’s agent rules as decisions in the repository, each with its own append-only history, and check every tool call against the current set. Deterministic, local, and the same in every harness.

Get started → How it works

$ hdr init && hdr install claude --project

pi · scratch repository

› Change the title in .hdr/decisions/HDR-001.json

● edit .hdr/decisions/HDR-001.json

✕ Blocked by HDR

FAIL HDR-001 Decision records are append-only:

edit would alter HDR-001.json; append a new record instead

The edit tool call was blocked by the HDR hook. The file .hdr/decisions/HDR-001.json was not modified. Per the HDR rules, a new record should be appended to supersede it.

Real output from a live pi 0.84.4 session, trimmed.

Why HDR

Instructions are suggestions. Decisions should be checked.

Prompts aren’t policy

Rules in CLAUDE.md or AGENTS.md are weighed by a model. HDR rules are checked by code before the tool runs, with the same answer every time.

⊘

Guardrails an agent can edit aren’t guardrails

Agents can propose new decisions, but never change the ones that govern them. Only people revise or retire a decision, by appending to its history.

✓

You can show what happened

Every check leaves a JSON report. hdr explain turns your decisions, their history, hook coverage and recent runs into a page a reviewer can read.

How it works

Three steps, then every tool call is checked.

Write the decision

One small JSON file per decision, committed next to the code. Its history grows over time; the latest entry is what applies, and its check says how a machine verifies it.

{
  "schema_version": 2,
  "id": "HDR-003",
  "history": [{
    "date": "2026-10-21",
    "title": "Expense belongs to the event budget",
    "rationale": "Event travel is charged to the event.",
    "check": {
      "kind": "json_equals",
      "path": "expense.json",
      "pointer": "/budget",
      "expected": "event"
    }
  }]
}

2
Install once per harness

HDR registers one checker with each harness your team uses, for the project or for your whole machine.
```
hdr install claude --project
hdr install opencode --project
hdr install pi --user
```
3
Every tool call is checked

The checker runs at session start, before and after every tool call, and when the agent stops.
- Before: a violating call is denied, with the reason.
- After: a broken state is fed back to the agent.
- On stop: the agent is asked to put things right.

Harnesses

One log. Every agent your team runs.

Each harness gets the same rules through the integration it supports best.

Verified live

Deliberately boring, so you can trust it.

Deterministic

No model calls, prompt judges or network requests. Every outcome comes from files on disk.

Every decision keeps its history

Decisions change by appending, never by editing. Read any decision file top to bottom to see what it was, what it is, and why.

Fails closed

Invalid records stop every check. Plugins deny tool calls when the checker cannot run.

Evidence by default

Each run records findings and hashes, but never tool inputs, prompts or file contents.

No dependencies

Python 3.11 and the standard library. Nothing to vendor, nothing to update.

Honest about limits

It is governance, not a sandbox. The limits page says exactly where it stops.

Write your first decision in five minutes.

Seed your first decisions, install the checker, and watch the next agent session respect them.

Read the guide → How to write decisions