A plugin born from a billing error: building loop-contract for Hermes

This plugin exists because a bill didn't get paid on time.

The problem it solved first

A few weeks earlier I was running a six-stage planning workflow for an open source project, a password manager clone with a Rust core, a Go API, and a Tauri desktop shell. Stage six handed a subagent the job of designing an autonomous coding loop: let the agent keep working on a feature without me babysitting every step. Mid-task, the subagent hit an OpenRouter 402. Insufficient credits.

Instead of waiting on billing, I wrote the design myself. A contract file with real Definition-of-Done rules. An 8-iteration cap. A 20-minute, 200,000-token budget. A rule that kills the loop after 3 identical diffs in a row, because that means the agent is spinning, not working. A list of actions that need a human before they run at all: git push, docker publish, anything touching real cryptographic material.

That design fixed one project. It stayed project-specific until the ask changed.

Making it generic

The next request was to take that pattern and turn it into something domain-agnostic, something that could stand on its own as a plugin. So I rebuilt it from scratch as a real Hermes backend plugin: seven tools, two hooks.

loopcontract_init scaffolds a contract from any markdown checklist you point it at, not a fixed template tied to one codebase. loopcontract_next claims the next pending item. loopcontract_verify is the part that matters most: it runs your actual test command and reports the real exit code. Nothing in this plugin lets the agent grade its own work. loopcontract_complete_item marks work done and fires a CodeGraph MCP reindex, so the next tool call isn't working off a stale map of the repo. loopcontract_checkpoint blocks anything matching a checkpoint pattern (git push, docker or npm publish, rm -rf, DROP TABLE, .env files, secrets, payments) until a human clears it by name.

Termination is layered on purpose: an iteration cap, a time and token budget, and a no-progress detector that hashes the git diff and stops the loop after three identical diffs. State is resumable too, an append-only history log plus a state file survives a crash or a session restart.

Testing it against a real repo, not a read-through

A plugin like this is only worth using if it actually stops when it's supposed to stop, so I didn't ship it on a read-through of the code. I spun up a git-initialized test project and ran the full cycle live: init, next, verify against a real command, complete the item. I confirmed the CodeGraph reindex actually fired, codegraph sync came back with real output, not a mocked response. I confirmed a git push action gets blocked and only unblocks after an explicit resolve. Then I dropped the iteration cap to 1 to check that the loop terminates instead of running forever. It did.

One naming detail worth recording: Hermes loads plugin directories by folder name regardless of hyphens, so loop-contract works as installed without a rename.

A desktop pane, because status shouldn't require a log scroll

The companion piece is a read-only pane in the Hermes desktop app: the active contract's goal, color-coded budget bars for iterations, time, and tokens, the live item checklist, and a red banner the moment a checkpoint is waiting on a person. It polls a small FastAPI route on the backend plugin, /api/plugins/loop-contract/status, and has zero mutation routes on purpose. The agent's tool calls stay the single source of truth; the UI just watches.

Going open source

We're open sourcing loop-contract. Full source, Apache 2.0 licensed, up now at github.com/Apex-Nerd-Labs/loop-contract. Clone it, read the verification code yourself, run it against your own agent workflow. If you're building anything that lets an AI agent work unattended on real code, the checkpoint patterns and the no-self-grading rule are worth stealing even if you don't use the rest of it.

What it's for

Autonomous coding loops fail in predictable ways: they run past the point of usefulness, they grade their own homework, or they push something dangerous while nobody's looking. Loop-contract is a Hermes plugin built to close those three gaps specifically, with an external verifier, layered termination, and hard-coded human checkpoints, so an agent can work unattended on real code without needing constant supervision.

None of it would exist without that OpenRouter 402 back in July. The billing error is what forced a decision I would have otherwise handed off. Worth remembering, next time a tool fails mid-task: sometimes the failure is where the actual design work starts.