Harmonist: mechanical protocol enforcement for AI coding agents

The rule that only exists in a prompt

Every engineering team has rules that are not negotiable in principle and optional in practice. Money is never stored as a float. QA runs before merge. Auth code gets a security review. An assistant can be told all of this and still finish a turn without doing any of it, because nothing in the loop checks. Harmonist is aimed at that gap. The README frames the split as thin frameworks that hand you orchestration primitives and leave enforcement to the prompt, against enterprise platforms that promise governance through a separate runtime, a database and vendor lock-in. Harmonist picks a third position: enforcement lives in IDE hooks, implemented as shell and Python scripts sitting next to your code. The audience is a developer or a small team already using a hook-capable assistant, who wants the review step to be a gate rather than a suggestion. It is not aimed at someone who wants a hosted dashboard or a scheduler that runs agents without a human at the keyboard.

What the stop hook actually checks

The mechanism is narrow and worth stating plainly. The stop hook in .cursor/hooks/ parses subagent dispatch markers out of the session, then checks three things according to the README: whether qa-verifier ran, whether any required reviewer was missing, and whether session-handoff.md was updated. If a check fails, the hook returns a structured followup_message to the model and the turn does not complete. Retries are capped by loop_limit: 3. When the cap is exhausted an incident is recorded and surfaced in the next session. That is the whole enforcement story, and its limits follow from it. The hook reasons about markers in the session transcript and about the presence of a handoff file. It does not read your diff and decide whether the change is correct. A reviewer agent that ran and approved everything satisfies the gate. The value is that skipping a step becomes visible and blocking rather than silent, not that the step was performed well.

Correlation IDs the model does not get to write

Memory is the second half of the design. Entries are written only through memory.py append, which validates against a YAML schema in memory/SCHEMA.md, rejects duplicates, and scans the body for roughly thirty classes of secrets: AWS access keys, GitHub PATs, Stripe tokens, Slack webhooks, GCP service accounts, Azure connection strings, Telegram bot tokens, Discord tokens, Heroku and Postmark UUIDs with context scoping, generic high-entropy tokens carrying a secret: prefix, and database connection strings with embedded credentials. Placeholder fences such as ${VAR} or <NAME> suppress the scan so templates still write. Each entry carries a correlation_id of the form <session_id>-<task_seq>, where the session id is generated by the hooks at session start as <unix-seconds><pid4>, which the README describes as collision-safe across parallel sessions. The model reads the active id through a CLI and never writes it. The claim that follows is that ordering between a state entry, a decision and a pattern from the same task is fixed from the hook's point of view rather than trusted to the model. That is a real distinction, and it is also the part of the README that reaches furthest: the id is generated outside the model, but the content of the entry is still model-authored.

Installing it, and the template trap

The README opens with a warning addressed to agents rather than humans, and it is the most practical paragraph in the file. An agent asked to install the pack is told to read integration-prompt.md and execute its steps, and explicitly not to apply AGENTS.template.md as a live rule inside the pack folder, because that file is the template that becomes the user project's AGENTS.md during integration. The requirements line states Python 3.9 or later and stdlib only, so there is no dependency resolution step and no virtual environment to build for the pack itself. The scripts named in the material are upgrade.py, which sha-verifies each source before copying into a project, and install_extras.py, which inherits the same guard for on-demand specialist installs. The README's key scripts section is referenced in the table of contents but the supplied text does not include its contents, so the exact invocation for a first install is not something I can quote. Treat integration-prompt.md as the entry point and read it before running anything.

MANIFEST.sha256 and what it does not cover

Runtime-shipped content is hashed in MANIFEST.sha256: agents/, hooks/, memory/, playbooks/ and the root docs. The README states that CI configs and repository metadata are pack-repo-only and excluded from the manifest. upgrade.py verifies each source against the hash before copying it into a project, so a tampered security-reviewer.md, the README's example being one that returns approve for everything, is refused and never enters the project. install_extras.py applies the same check for specialist installs. This is a meaningful control and an unusual one for an agent catalogue. The boundary is where it stops: verification covers the files the pack ships, not the project files the agents later edit, and not the model's output. A manifest proves the reviewer definition is the one GammaLab published. It says nothing about whether the review was any good.

Where the gate becomes the wrong tool

The design assumes a specific environment. Enforcement runs through IDE hooks, so an assistant or a version that cannot return a followup_message from a stop hook gets you the markdown and none of the gating. The loop_limit: 3 cap is a second constraint: a session that keeps failing the same check exhausts its retries, records an incident, and hands the problem to the next session rather than resolving it. On a repository where the required reviewers have not been defined as agents, the hook has no markers to look for, and the pack degrades into a large prompt library. There is also a scale cost that the README does not discuss. Between the 193-agent catalogue across 16 categories and the 550+ tests cited in the badge line, this is a substantial tree to carry in a project, and every upgrade has to be sha-verified against a manifest that changes with each release. For a solo developer on a small script repository, that overhead buys nothing.

Against a thin orchestration library

The comparison the README draws is with frameworks such as LangChain, CrewAI, AutoGen and MetaGPT, which supply orchestration primitives and leave enforcement to the prompt. The difference is architectural rather than a matter of degree. Those libraries run the agent loop in their own process, which is what lets them compose arbitrary tools and models, and it is also why a protocol violation is something the model can talk its way past. Harmonist runs no loop of its own. It supplies files and hooks that the host assistant executes, which is why it has no runtime dependencies and why it cannot do anything the host does not expose. If you need to call a model outside an IDE, or to schedule agents without a developer present, the thin-library model fits and Harmonist does not. If your problem is that a rule keeps getting skipped inside an assistant session you are already having, the hook is the only one of the two that can refuse.

Licence, upgrades and what to verify first

Harmonist is MIT-licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission text are retained. That is a summary of the licence family, not legal advice, and the LICENSE file in the repository is the text that governs. The maintenance picture from the supplied material: three releases in the space of about two days in June 2026, v1.1.0, v1.2.0 and v1.2.3, with the last push and the last release landing within seconds of each other. That is a fast cadence, and because upgrade.py verifies sources against MANIFEST.sha256, every upgrade is a manifest comparison rather than a file copy. Pin the version you install and re-read the changelog before moving. The first thing to verify is not the agent count. It is whether your assistant's stop hook can return a followup_message in your environment, because that single capability decides whether you are adopting an enforcement layer or a folder of markdown.

Editorial conclusion

Adopt Harmonist if your team already runs a hook-capable assistant such as Cursor or Claude Code and has written rules that keep getting skipped, and you accept that the pack lives in your repository as markdown plus stdlib Python. Do not adopt it if you need a hosted control plane, a language model that is not driven by an IDE, or a workflow whose reviewers you cannot express as named agents, because the stop hook can only check markers that exist. Before installing, read integration-prompt.md rather than AGENTS.template.md, confirm your assistant version supports a stop hook that can return a followup_message, and decide whether 193 agent files in your tree is a cost you are willing to own.

Official sources

1. GammaLabTechnologies/harmonist on GitHub
2. License: MIT
3. Project website
4. README
5. Releases