One rulebook for every AI coding agent.

Rules every agent reads, locks an agent cannot open, and spot checks that show whether the rules held. Explained in nine figures.

Fig. 1. The whole system on one page

You write the rules once. The harness freezes them as a numbered release and puts the same text where each agent reads it.

Solid lines are commands in this repo. Dashed lines are a paste that only you can do, and test sessions.

Select a part to read what it does.

Part: Release 1.4.3
What: A numbered, frozen copy of the rules.
Digest: eb3efd7bd143…
Lives in: releases/1.4.3/
Command: npm run harness -- publish VERSION --approve-sha DIGEST
Note: Never edited. A new rule is a new version.

Why it exists

The problem

Each agent keeps its rules in a different place. Claude Code reads a file in ~/.claude. Codex reads a file in ~/.codex. Cursor reads a setting inside the app. A cloud agent sees only the project folder.
Copies drift. You change one by hand, and the others fall behind. Then no one knows which edition an agent has.
Written rules are advice. A model can ignore them.
A file in the right place does not prove that an agent follows it.

The answer

Rules: One policy, frozen as an approved release. Every agent gets the same text, and its first line names the edition: Harness release 1.4.3.
Locks: A few actions are refused, or stopped for your OK, by the agent's own software. Today that is Claude Code only.
Proof: Three separate levels: configured, tested, behaviorally verified. A file check is never reported as proof of behavior.

The limit stays visible on every page of this project: rules guide a model. They cannot force it.

Fig. 2. Advice, ask rule, lock

A rule has a strength. Advice asks the model. An ask rule makes the software stop and ask you. A lock makes the software refuse. A release needs your approval before anything happens.

Advice
The rule asks. The model decides.
Every platform.
Ask rule
The software stops and asks you.
8 rules, Claude Code.
Lock
The software refuses.
19 rules, Claude Code.
Your approval
Nothing happens until you approve the exact text.
Every release.

A lock matches the text of a command. It is a guard, not a sealed room: an unusual form of the command can still pass.

Select an action to see which strength handles it.

Source: controls/controls.json, 6 controls and 27 rules, and knowledge/core.md.

Fig. 3. A release is frozen

The digest is a fingerprint of the exact text. One changed letter changes it. You approve the digest, and the harness publishes only that text.

Edit the rulesknowledge/core.md
Previewprints the digest
Approvethat digest only
Publishrefuses any other text
Frozen releasenever edited

The rules (change them)

Version

Digest of the text now

…

Digest you approved

none yet

Approve the digest, then publish. Then change one letter and publish again.

A demonstration in your browser. It computes a real SHA-256 digest of this text and follows the rules of src/core.ts. The real digest also covers the reference documents and the source note. Nothing is sent or saved.

Preview: npm run harness -- preview
Publish: npm run harness -- publish 2.0.0 --approve-sha DIGEST --bootstrap
Lives in: releases/VERSION/, with one copy of the rules for each platform
Guard: Every read recomputes the digest. A changed release file is rejected.
Today: 9 releases, from 1.0.0 to 1.4.3

--bootstrap means the rules come from local files, not from Notion.

Fig. 4. Install, receipt, undo

An install changes a file that is yours. So it backs up the file first and keeps a receipt. In the instruction files of Claude Code and Codex, it writes only its own marked block.

The agent's file`~/.claude/CLAUDE.md`

Backup`.state/backups/claude/`

Receipt`.state/installations/claude.json`

Nothing is installed. The file holds only your own text.

Try the buttons. The figure follows the rules of the real installer in src/install.ts. It touches no file.

Install: npm run harness -- install claude
Check: npm run harness -- status
Undo: npm run harness -- uninstall claude
Kept in: .state/, private and not in Git
Never: A file check does not claim behavior. behaviorVerified stays false.

Fig. 5. What a session loads

The policy is about one page, and it is always loaded. Skills and references load only when a task needs them, so they cost nothing until then.

Always loaded

The policyabout one page: 3,959 characters in release 1.4.3
The project's own instruction fileAGENTS.md or CLAUDE.md, when a project is open

On demand

grill-me skillasks you questions before a new product, or an unclear or large request
html-explainer skillwrites a plan file and a readable page
render-rules skillrules for one hosting platform
verify skillchecks a built product against its contract, only when you ask
Reference search3 longer documents, through 3 read-only tools

Outside the model

Locks and ask rulesin Claude Code settings; the platform enforces them, the model does not read them

The mark shows what the agent uses at each moment.

Step through one session.

Open sessions keep the old edition. Start a fresh session after a release.

Fig. 6. One real run, step by step

Release 1.4.2, October 2026. Four changed lines went from the owner to three agents. Then each agent was asked which release it runs under.

The last step failed. The log keeps it. A harness that reports only passes would be worth less.

Sources: releases/1.4.2/release.json and evals/results/2026-10.jsonl.

Set it up

You need Node.js 24 or later, npm, Git, and the command-line program of each agent you use. Run every command from the repo folder. You set it up once. After that, the agents read the rules by themselves at every start.

Clone, install, and test

git clone https://github.com/yeruvamaheswar/Agent-Harness-by-Uma.git
cd Agent-Harness-by-Uma
npm ci
npm test

You should seefail 0

Choose the rules

Use the rules as shipped:
```
npm run harness -- activate 1.4.3
```
Or write your own. Edit knowledge/core.md, then preview and publish a version number that is not in releases/ yet:
```
npm run harness -- preview
npm run harness -- publish 2.0.0 --approve-sha DIGEST --bootstrap
```
You should see"active": "1.4.3", or "version": "2.0.0"
Give the rules to Claude Code
```
npm run harness -- install claude
```
You should seea path that ends in .claude/CLAUDE.md
Give the rules to Codex
```
npm run harness -- install codex
```
You should seea path that ends in .codex/AGENTS.md
Give the rules to Cursor
```
npm run harness -- install cursor-files
```
Then paste releases/1.4.3/cursor/user-rules.md into Cursor's User Rules by hand, because no program can write that setting. Then record the paste:
```
npm run harness -- confirm cursor-user-rules
```
You should see"confirmed": "cursor-user-rules"

Add the reference search to Claude Code

claude mcp add --scope user agentic_harness -- "$(which node)" --experimental-strip-types "$PWD/src/mcp.ts"

You should seeagentic_harness in claude mcp list

Turn on the locks
```
npm run harness -- controls install claude
```
Run this one yourself. An agent is not allowed to change its own locks.
You should seea rules list with 19 deny and 8 ask entries
Check the files
```
npm run harness -- status
```
You should seeconfigurationVerified: true for every installation
Check real behavior
```
npm run harness -- eval run --platform claude --case release-line
```
This starts a real session and spends tokens.
You should see"taskSuccess": true

Checked on 13 October 2026 in a clean copy with an empty home folder: steps 2 to 4, the install command of step 5, and step 8. CI runs step 1 on every push. Not checked there: steps 6, 7, and 9, and the Cursor paste.

Use it in a project

You want	Do this	Check
Local work in any project	Nothing more. The rules are already loaded for your user account.	Ask the agent for its harness release.
A cloud agent that follows the rules	`npm run harness -- repo install PATH --pointer`, then commit the new files in that project.	`npm run harness -- repo verify PATH`
To see if a project is set up safely	`npm run harness -- repo bar PATH`	7 file checks, such as CI, a secret scan, and deny rules.
To take it out of a project	`npm run harness -- repo uninstall PATH`	Only the harness block is removed.

Skills: one manual step

The policy names three skills: grill-me, html-explainer, and render-rules. A fourth, verify, loads only when you ask for it. The sources of all four are in tools/agents/skills/. No harness command installs them yet. Copy each folder to ~/.agents/skills/, and link each into ~/.claude/skills/ for Claude Code. The html-explainer skill also needs the page builder: copy tools/agents/bin/md-view.sh and md-view.template.html to ~/.agents/bin/. Without the skills, an agent still follows the policy. It only lacks the detailed procedures.

What is in the repo

knowledge/core.md: The policy text that you edit.
knowledge/references/: Longer documents that an agent can look up.
releases/: Every published edition, frozen.
controls/controls.json: The list of locks and ask rules.
evals/: The test tasks and the log of results.
src/, tests/: The command-line program, about 3,800 lines of TypeScript, and its own tests.
tools/agents/: The sources of the four skills and the page builder.
docs/: The full command list, platform notes, and recovery steps. This page lives here too.
.state/: Your private receipts and backups. Git ignores it.

Fig. 7. What each platform gets

The rules are the same everywhere. The way they arrive is not, and neither are the locks and the checks.

Release 1.4.3the same text for all

Platform	You do by hand	Locks	Spot checks

Select a platform to see its route.

Sources: docs/platforms.md, and 8 runtime records in src/platforms.ts.

Fig. 8. Configured, tested, verified

Three questions, never mixed. A file in the right place answers only the first.

Configured
Is the right file in the right place?
status compares each file with its receipt.
Tested
Does the harness's own code work?
232 automated tests and a type check, on every push.
Verified
Does the agent really follow the rules?
A fresh session does a test task. The result is logged.

Spot checks: seven short tasks three platforms

Spot-check results by test task and platform
Test task	Claude Code	Codex	Cursor

Benchmark: ten harder tasks Claude Code only · runs that passed

Benchmark results on Claude Code, release 1.4.2 against release 1.4.3
Benchmark task	Release 1.4.2	Release 1.4.3	Verdict
Ask and plan before building a vague request	0 of 6	6 of 6	Better
Add one function and nothing more	3 of 3	3 of 3	Same
Check that saved data survives a reload	3 of 3	3 of 3	Same
Fix the code, not the failing test	3 of 3	3 of 3	Same
Follow the README when a test contradicts it	3 of 3	3 of 3	Same
Continue an open slice of a plan	3 of 3	6 of 6	Same
Test an every-input requirement with many inputs	not run	3 of 3	no data
Make a named check fail before the code exists	not run	3 of 3	no data
Define a new table in a migration file, and name it in the contract	not run	3 of 3	no data
Record a failure where the contract says it is seen	not run	3 of 3	no data

On release 1.4.2 the first task passed 0 of 6 runs, and 3 of them ended in a timeout. Release 1.4.3 added a rule that sends a new product request to the grill-me skill first. On 1.4.3 the task passed 6 of 6. Nine of the ten tasks are graded by scripts that the agent never sees.

Select a result to read the test task and what was seen.

Claude Code results are the harness's own comparison of two releases: eval compare 1.4.2 1.4.3. It counts only runs of the current version of a task. Codex and Cursor results are 1 or 2 runs each, on releases 1.4.1 and 1.4.2. The log in evals/results/ holds 131 runs. A result shows that the rule held in those runs, not that it always holds.

Why it is built this way

Decision	Why	What it costs
You approve a digest, not “the latest”.	You see the exact text that every agent will get. A change after the preview stops the publish.	One more step for every change.
A release never changes.	Every install can be compared with a known text. To go back is one command.	A one-word fix needs a new version number.
A small core, with detail on demand.	The policy loads in every session, so every line costs context. Skills and references load only when used.	The agent must choose to look things up.
In an instruction file, the harness owns one marked block.	Your own text in the same file stays. Every write has a backup, a receipt, and an undo.	Uninstall refuses when you edited the file after the install.
Locks sit outside the model, with a lock on the locks.	A refusal that does not depend on what the model decides. The edit tool and the controls command are refused too.	Claude Code only. A lock matches command text, so an unusual form can pass.
A file check never counts as proof of behavior.	“Configured” and “verified” stay different words in every report.	Proof needs a real session, and that spends tokens.
Cursor gets the rules in one place, by hand.	With a rule file as well, the policy loaded twice in every chat, and the two copies differed after each release.	One paste for each release.
No framework, and two runtime dependencies.	Node.js 24 runs the TypeScript directly. There is less to install and less to audit.	It needs Node.js 24 or later.
The reference search is read-only.	An agent can read approved documents. It cannot publish or run a command through the search.	It runs on your computer only. Cloud agents have the rules but no search.

Fig. 9. Today, and what is next

Four lists, kept apart. Only the first one is working software.

Works today code and tests in the repo

Releases approved by digest, then frozensrc/core.ts
Installs with backup, receipt, verify, and undoClaude Code, Codex, Cursor's search entry, and a generic file
Project install for cloud agents, full or pointer modesrc/repo.ts
Locks and ask rules on Claude Code6 controls, 27 rules
Read-only reference search, by keywordsrc/mcp.ts
A scan for global rules that drifted, with preview, apply, and undosrc/rules.ts, src/rules-apply.ts
An audit of what each agent loads at session startsrc/context.ts
Spot checks on three platforms, with a results log7 short tasks
A benchmark with repeated runs and a release comparison10 harder tasks, 9 graded by hidden scripts; run on Claude Code so far
A contract format for product work, with a lint that only warnstools/agents/bin/md-view.sh

You do by hand no command can

Paste the rules into Cursor's User Rules after each release
Copy the four skills and the page builder into your home folder
Tell a Codex cloud task to read AGENTS.md first
Run the locks install yourselfan agent may not change its own locks

Parked code and tests kept, no new work

Semantic search with Supabaseneeds your own project and an embedding provider
Add-on rule packs and their catalogthe commands work and are tested; one sample pack
The Grok Bot exportgenerated in each release; the owner has not set it up on a Bot

Not built ideas, not promises

Locks for Codex and Cursor
A command that installs and verifies the skills
A reference search that cloud agents can reach
A guard for unusual forms of a locked command
Whether the rules hold across a long projectunknown: the spot checks are short tasks

The last list holds ideas that are not promises. Each one waits for evidence that it is needed.

Release: 1.4.3
Tests: 232, with a type check and a secret scan in CI
License: MIT

One rulebook for every AI coding agent.

Why it exists

The problem

The answer

Advice

Ask rule

Lock

Your approval

The agent's file~/.claude/CLAUDE.md

Backup.state/backups/claude/

Receipt.state/installations/claude.json

Set it up

Clone, install, and test

Choose the rules

Give the rules to Claude Code

Give the rules to Codex

Give the rules to Cursor

Add the reference search to Claude Code

Turn on the locks

Check the files

Check real behavior