An agent framework that treats LLMs like untrusted executables

What it does

Harmonist is a drop-in framework for AI coding assistants—Cursor, Claude Code, Copilot, Windsurf, Aider, and others—that turns project rules into mechanical gates. It sits next to your code as stdlib Python and bash scripts, using IDE hooks to inspect every subagent dispatch, file edit, and session end. If a required reviewer did not run, memory was not updated, or a file’s hash does not match the manifest, the hook returns a structured follow-up message and the turn simply does not complete. The LLM can claim compliance all it wants; the state machine on disk does not care.

The interesting bit

The framework treats the LLM as an untrusted actor rather than a cooperative partner. Correlation IDs linking memory entries are generated by hooks at session start using Unix seconds and PID fragments, so the model can read them but never forge them. Even the 186 agent definitions are supply-chain guarded: upgrade.py SHA-256 verifies every file against MANIFEST.sha256 before installation, rejecting a tampered security-reviewer.md outright.

Key highlights

• Mechanical protocol enforcement via IDE stop hooks with a retry cap of three loops; exhausted loops surface as recorded incidents.
• 186 curated domain specialists across 16 categories, routed by domains × roles × tags rather than hard-coded slugs.
• Zero runtime dependencies beyond Python 3.9+ stdlib and bash; a pure-Python hook_runner.py provides native Windows parity without WSL.
• Schema-validated memory writes with duplicate rejection and secret-pattern scanning for roughly 30 token classes.
• Integration-by-prompt: paste integration-prompt.md into Cursor Agent mode and the AI bootstraps its own governance.

Caveats

• Cursor is the primary integration; other assistants (Claude Code, Copilot, Windsurf, etc.) are supported via adapters, so your mileage may vary.
• Enforcement relies on the IDE supporting subagent dispatch hooks; if the assistant’s runtime does not expose those phases, the mechanical gates have nothing to latch onto.

Verdict

Worth a look if you treat AI-generated code as a compliance risk rather than a convenience. Skip it if your workflow does not use an assistant with subagent dispatch hooks.