Harness the Repo, Not the Agent

The Harness Is in the Wrong Place

Anyone who has run a small, fast coding agent for more than a day knows the failure mode. It is not that the agent writes bad code. It is that it writes the right thing in the wrong place: a test dropped next to the source instead of in tests/, a fourth markdown file describing a concept that already has three, a config invented where a canonical one exists. Each mistake is small, reasonable in isolation, and corrosive in aggregate. The repo does not break; it dissolves.

Our whole toolbox for this problem operates on the agent. We tune system prompts, tighten permission modes, add hooks, write ever-longer AGENTS.md files and hope the model reads past the first screen. All of it shares an assumption that stopped being true sometime last year: that there is oneagent to harness. In practice a living repo is now touched by Claude Code today, OpenCode tomorrow, Aider from a teammate's machine, and a human at midnight — and an agent-side harness governs exactly one of those actors, in exactly one tool, for exactly as long as its config survives.

henxels, a research preview we are releasing today, makes the opposite bet: put the harness in the artifact, not the actor. The repository is the only surface every agent and every human shares — so that is where the contract belongs. The move is the same one CI made twenty years ago, when testing stopped being developer discipline and became repository infrastructure. Discipline does not scale across actors. Contracts do.

A Contract That Reads Like a Whiteboard

The contract is a single file, henxels.yaml, and it is deliberately a dumb, readable list. Each rule — a henxel, from the Finnish henkselit, “suspenders” — is a plain-language sentence plus the statements that must all pass. The logic lives inside the statements; the YAML stays legible to a human skimming it on a whiteboard, which matters because the same sentence is also the failure message an agent sees.

Two design decisions here are, I think, the interesting research contributions. The first is that failure is an instruction, not a boolean. A henxels check does not return false; it returns a sentence telling the agent what to do instead — “split it — keep under 500 lines,” “this belongs in the existing page, not a new one.” The project's principle is steer before you stop. For a language-model audience this is the entire difference between a linter and a colleague: a red exit code teaches a model nothing, while a corrective sentence lands in exactly the medium the model reasons in.

The second is that the contract steers before the agent ever writes. On every sync, henxels renders the contract into a digest inside AGENTS.md— the file every major coding agent already reads on startup. The structure is in front of the model before the first token of a change, and enforced by git hooks after the last one. Prompting and enforcement stop being separate systems that drift apart; they are two renderings of one source of truth. A henxel's optional why: field rides along into the digest, so the agent learns the purpose of a structure and not merely its shape — some of the cheapest, highest-leverage steering you can give a small model.

Under the hood henxels is a framework plus a growing library of built-in checks — structure, naming, link integrity, append-only files, secrets, size budgets (including budgets measured in tokens, the unit an agent actually feels). When a check is missing, you write one in three lines of Python: a decorated function whose arguments are injected by name, pytest-style, and whose return value is the instruction shown on failure. Custom checks are committed with the contract, because they are contract.

Disobedience Is a Diff

A harness that merely blocks would make agents useless the moment reality disagrees with the contract — and reality always eventually disagrees. henxels' answer is its most quietly important principle: disobey responsibly. There is exactly one escape hatch, and it is editing henxels.yaml. Breaking structure by accident becomes impossible; breaking it on purpose becomes a conscious, reviewable act that shows up in the diff like any other design decision. The contract plays the role a type system plays for values — not a wall but a channel, where exceptions are declared rather than accumulated.

The same philosophy shapes what henxels refuses to block. Duplication — the signature failure of eager agents — triggers awareness, not rejection: a similarity warning fires when a new file looks suspiciously like a committed one, and destructive reflexes like force-pushes and large deletions are held behind guards that release only with a deliberately minted, one-time token bound to the exact commit. Awareness beats blocking. The agent stays fast; the repo stays deliberate.

The Flagship Recipe: A Wiki That Doesn't Rot

The clearest place to watch all of this pay off is the LLM wiki— the pattern Andrej Karpathy described this April: a markdown knowledge base that an agent builds and maintains, so that knowledge compounds across sessions instead of being re-derived from raw documents on every question, the way RAG re-derives it. Karpathy's framing is that the wiki is a persistent, compounding artifact, and that the reason it works where human wikis fail is that LLMs don't get bored and don't forget to update a cross-reference. In June, Google formalised the pattern into the Open Knowledge Format (OKF): a vendor-neutral spec where each concept is one markdown file with YAML frontmatter, links are the edges of a knowledge graph, and index.md and log.md carry navigation and history.

But OKF is minimally opinionated by design — the only field it requires is type — and consumers are told to tolerate almost anything. That is the right call for an interchange format, and it has a sharp consequence: the entire quality bar sits with whoever writesthe bundle. And the writer, in this pattern, is a small model. Small models drift hard against an unenforced bar. They skip frontmatter, forget timestamps, leave dead links — and, worst of all, they scatter: knowledge that belongs in one page ends up spread across five near-duplicate files. Karpathy's compounding property holds only while the graph stays coherent. A wiki that fragments is not a knowledge base anymore; it is RAG with extra steps.

This is precisely a structural-contract problem, and it is henxels' flagship template. henxels init --template okf-llm-wiki scaffolds a wiki that is green from birth: every concept doc must carry type, title, and description; timestamps are real ISO 8601 values that a diff-aware check forces to be bumped when the page changes; every link must resolve; every concept must be referenced from the index and must link out at least once — a concept is a node in the graph, not an orphan; the log stays append-only under dated headings. And the similarity warning catches the agent at the exact moment it is about to create the fifth slightly-different page about the same idea, and tells it — in a sentence — to merge instead. Pointed at an existing wiki, the same rules start as warnings, so the findings become the agent's migration plan rather than a wall of blocked commits.

The division of labour Karpathy proposed was human as curator, LLM as bookkeeper. henxels adds the missing third role: the contract as auditor — the piece that lets the bookkeeping compound for months without a human re-checking the books.

Try It

henxels is MIT-licensed and installs from PyPI (uv tool install henxels) or npm (npm i -g henxels). The npm package is its own small piece of deep-tech fun: there is one engine, in Python, and the Node launcher bootstraps it on first run by fetching a checksum-pinned uv binary that provisions Python by itself — no Python required on the machine, and the npm version is hard-pinned to the identical PyPI version, so the two registries can never skew. Run henxels init, tailor the contract to your folders, and commit it; or start from the OKF wiki template and let your agent inherit a knowledge base that cannot quietly fall apart.

And in the spirit of eating one's own cooking: the henxels repository is governed by its own henxels.yaml, including a meta-check that verifies every shipped check has documentation and a test. The tail-eating is the test.

We spent two years making agents smarter and their harnesses thicker. The repositories they share deserve the same attention. A contract that lives in the repo outlasts every agent that visits it — and in a world where the visitors change monthly, the durable half of the system is the one worth engineering.