# Harmonist: hook-enforced agent orchestration for Cursor and Claude Code

> Harmonist is a Python-and-bash multi-agent pack that gates every code-changing turn through IDE hooks instead of trusting the model to follow its own protocol. It ships 193 agent definitions, stdlib-only tooling, and a sha256 manifest, but the enforcement is tied to the assistants that expose hook events.

**GammaLabTechnologies/harmonist** — Portable AI agent orchestration with mechanical protocol enforcement. 186 agents, zero runtime dependencies.

- Repository: https://github.com/GammaLabTechnologies/harmonist
- Website: https://gammalab.ae
- Stars: 2,256 · Forks: 208
- Language: Python
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/gammalabtechnologies-harmonist

## The problem Harmonist is aimed at

Engineering teams write rules that are supposed to be non-negotiable: no floating-point for money, QA before merge, idempotency keys on external calls, security review before auth changes. An LLM can be told all of that and still skip a step, because nothing in the loop stops it. The README frames this as a structural problem that prompt engineering cannot fix, and that framing is the whole reason the project exists.

The intended user is a developer or small team already working inside an AI coding assistant and already frustrated by skipped review steps. Harmonist is not a hosted service and not a runtime you deploy. It is a folder of markdown agent definitions, hook scripts, a memory store and playbooks that sits next to your code. The README's own summary is that it is markdown, stdlib Python and bash doing one job. If you want a control plane with a database and a dashboard, this is not that.

## How the hook gate actually works

The enforcement lives in the stop hook under .cursor/hooks/. According to the README, that hook parses subagent dispatch markers out of the session, checks whether qa-verifier ran, whether any required reviewer was missing, and whether session-handoff.md was updated. If any of those checks fail, the hook returns a structured followup_message instead of allowing the turn to complete. The README describes the model as unable to argue with this, because it is a state machine on disk rather than a request in a prompt.

Retries are capped. The README gives loop_limit: 3, and states that on exhaustion an incident is recorded and surfaced in the next session. That cap is the interesting design decision: enforcement is not an infinite nag loop, it is bounded, and the failure is escalated rather than silently retried forever.

Memory is the second mechanism. Every entry carries a correlation_id of the form <session_id>-<task_seq>, generated by the hooks at session start with a <unix-seconds><pid4> shape that the README describes as collision-safe across parallel sessions. The agent reads the active ID through a CLI and never writes the ID itself. The README's claim is that this makes the ordering between a state entry, a decision and a pattern from the same task provable from the hook's perspective rather than trusted to the model.

The third mechanism is supply chain. Everything runtime-shipped (agents/, hooks/, memory/, playbooks/ and the root docs) is hashed in MANIFEST.sha256, with CI configs and repo metadata excluded as pack-repo-only. upgrade.py sha-verifies each source before copying it into a project, and install_extras.py inherits the same guard for on-demand installs. The README's example is blunt: a tampered security-reviewer.md that approves everything is refused before it enters the project.

## Installing Harmonist and running a first gated turn

The README does not present Harmonist as a pip package. The repository layout shows a pack folder with agents/, hooks/, memory/, playbooks/, MANIFEST.sha256, integration-prompt.md, AGENTS.template.md and GUIDE_EN.md, and the top of the README tells an AI agent asked to install or integrate the pack to read integration-prompt.md and execute its steps. So the documented path is to point an assistant at that file and let it follow the steps, rather than to run a single installer command. The README does not document a rollback procedure for an integration, and it does not give a clone URL or a checksum command of its own, so there is no install snippet to copy here.

The one warning the README gives directly is about AGENTS.template.md: it should not be applied as a live rule inside the pack folder, because it is the template that becomes the user project's AGENTS.md during integration. That is a real footgun. If you point your assistant at the pack directory and let it treat the template as active, you have configured the pack, not your project.

After integration, the observable behaviour is the gate itself. You dispatch a subagent, the turn attempts to finish, and the stop hook either allows completion or returns a followup_message naming what was missing. The README does not document what the followup_message looks like verbatim, so treat the first run as a chance to read the actual payload your assistant surfaces.

## Where the enforcement model breaks down

The gate depends entirely on the assistant emitting the events the hooks read. The README lists Cursor, Claude Code, Copilot, Windsurf and Aider as targets, but hook surfaces differ between them, and the README's detailed example is the .cursor/hooks/ path. If your assistant does not fire a stop event, or fires it in a shape the hook does not parse, enforcement degrades to the polite-request model Harmonist exists to replace. The README does not publish a compatibility matrix of which hook events each assistant provides.

The second limit is scope. The gate is a state machine on disk next to your code, so it governs turns that go through the assistant. A developer editing files by hand, or running a separate script, is outside it. Nothing in the README describes sandboxing, resource limits or per-agent permissions, so this is a protocol-compliance tool, not a security boundary.

The third is the catalogue itself. The README calls the 193 specialists curated and describes them as covering 16 categories, but curated markdown is not the same as a vetted library. A specialist definition is a prompt with a role, and its quality varies by author. The supply-chain hashing tells you a file was not modified after packaging; it tells you nothing about whether the reviewer's instructions are good. Teams that read the count as a quality signal are reading the wrong number.

Finally, the retry cap cuts both ways. loop_limit: 3 means a genuinely stuck session ends in a recorded incident rather than an endless correction loop. That is the right default for cost, but it also means a legitimate but unusual change can be blocked by a reviewer that keeps failing, and the resolution path is a human reading the incident in the next session.

## How it differs from LangChain, CrewAI and AutoGen

The README places thin agent frameworks such as LangChain, CrewAI, AutoGen and MetaGPT on one side and heavy enterprise governance platforms on the other. The distinction it draws is where enforcement lives. In the thin frameworks, orchestration primitives are provided and the protocol stays in the prompt, so the model can override its own instructions. Harmonist moves that same protocol into IDE hook scripts that observe subagent dispatch, file edits and session stop, and can refuse to let a turn complete.

The practical difference is where you feel the failure. With a prompt-level framework, a skipped QA step shows up later as a bug or a review comment. With Harmonist, the turn does not finish and you get a followup_message. That is a stricter contract, and it comes with a dependency the other approach does not have: you must be inside an assistant that exposes the hook events. A LangChain pipeline runs headless in CI; Harmonist's gate is built around an interactive coding session. If your agents run as a service with no IDE in the loop, the enforcement mechanism has nothing to attach to.

## Maintenance, versions and the MIT licence

The latest release is v1.2.3, dated 2026-06-09, and the last push to the repository was on 2026-06-09. That is more than three months before today, so the project is not in a state you should describe as continuously shipping; check the release history before you plan around a fast cadence. The release sequence v1.1.0, v1.2.0, v1.2.3 all landed within about two days in June 2026, which reads as a concentrated push rather than a steady stream.

Upgrade cost is shaped by the manifest. upgrade.py sha-verifies each source before copying it into a project, so an upgrade is a verified copy, not a merge. The README does not document a rollback path, which means your own version control around the integrated files is the recovery mechanism. If you have edited agent definitions locally, expect the manifest check to be the thing that decides whether your edits survive.

The licence is MIT. That permits commercial use and modification, and it comes with no warranty. The README also points to SECURITY.md for vulnerability reporting. None of this is legal advice; if you redistribute the pack inside a product, read the LICENSE file and your own obligations rather than this summary.

## Conclusion

Adopt Harmonist if your team already works inside Cursor, Claude Code, Copilot, Windsurf or Aider and wants reviewer and memory steps to fail closed rather than depend on prompt compliance. Skip it if you run agents headless, need per-agent sandboxing, or expect the 193-agent catalogue to be a vetted library rather than curated markdown. Before rolling it into a shared repository, verify that your assistant emits the hook events the stop hook reads, that MANIFEST.sha256 covers the files you intend to ship, and that your team accepts the retry loop_limit of 3 before an incident is recorded.

## FAQ

### What is Harmonist?

It is a portable multi-agent orchestration pack for AI coding assistants, distributed as markdown, stdlib Python and bash. Its distinguishing feature is that protocol enforcement runs as IDE hooks that can refuse to let a code-changing turn complete.

### Which assistants does Harmonist work with?

The README lists Cursor, Claude Code, Copilot, Windsurf and Aider as targets. The detailed hook example it gives is the .cursor/hooks/ path, and it does not publish a matrix of which hook events each assistant emits.

### What happens when a required reviewer did not run?

The stop hook returns a structured followup_message instead of completing the turn. Retries are capped at loop_limit: 3, and on exhaustion an incident is recorded and surfaced in the next session.

## Sources

- [GammaLabTechnologies/harmonist on GitHub](https://github.com/GammaLabTechnologies/harmonist)
- [License: MIT](https://github.com/GammaLabTechnologies/harmonist/blob/main/LICENSE)
- [Project website](https://gammalab.ae)
- [README](https://github.com/GammaLabTechnologies/harmonist/blob/main/README.md)
- [Releases](https://github.com/GammaLabTechnologies/harmonist/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gammalabtechnologies-harmonist