Most AI coding frameworks trust the language model to follow the
rules. Harmonist refuses to let it skip them. Every code-changing
turn is gated by hooks that check whether the required reviewers ran,
whether memory was updated, and whether the supply chain of every
shipped file is intact. If the checks fail, the turn doesn't complete —
no matter how confidently the model claims it's done.
This is the first open-source agent framework where .
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
AI coding assistants have a structural problem that prompt engineering
alone cannot fix.
The problem: every serious engineering workflow has non-negotiable
rules — "no floating-point for money", "run QA before merging", "every
external call retries with idempotency keys", "security review before
touching auth code". An LLM can be told to follow them, but there is
no mechanism forcing it to. It can agree, move on, and silently skip
the step. On a good day you notice. On a bad day the bug ships.
The current landscape is split between two imperfect answers:
Thin agent frameworks (LangChain, CrewAI, AutoGen, MetaGPT and
many others) give you orchestration primitives but leave enforcement
to the prompt. The model can always override its own protocol.
Heavy enterprise platforms promise governance through separate
runtimes, databases, and vendor lock-in — but need infrastructure to
install, don't work on a solo developer's laptop, and can't be
audited file-by-file.
Harmonist takes a different stance. Protocol enforcement is
implemented as IDE-level hooks — concrete shell and Python scripts that
observe every subagent dispatch, every file edit, every session stop.
When the rules the project declared aren't met, the stop hook
returns a followup_message to the AI and refuses to allow the turn
to complete. The model can't argue with that; it's a state machine on
disk.
No runtime. No database. No vendor lock-in. Just markdown, stdlib
Python, and bash — sitting next to your code, doing one job
correctly.
What makes it different
Seven concrete, checkable properties — each one addresses a gap that
other open-source agent frameworks leave open.
1. Mechanical protocol enforcement via IDE hooks
The stop hook in .cursor/hooks/ parses subagent dispatch markers
from the session, checks whether qa-verifier ran, whether any
required reviewer was missing, whether session-handoff.md was
updated, and returns a structured followup_message if the turn
is incomplete. loop_limit: 3 caps retries. On exhaustion, an
incident is recorded and surfaced in the next session. The AI
literally cannot ship a code change that skipped review.
2. Supply-chain verification of agent definitions
Every shipped file is hashed in MANIFEST.sha256. upgrade.py
sha-verifies each source before copying into a project. A tampered
security-reviewer.md (say, one that returns approve for
everything) is REFUSED — it never enters the project. install_extras.py
inherits the same guard for on-demand specialist installs. This is
the first OSS agent catalogue with paranoid-level supply-chain
posture.
3. Memory correlation IDs that the LLM cannot forge
Every memory entry has a correlation_id of the form
<session_id>-<task_seq> generated by the hooks at session start
(<unix-seconds><pid4> — collision-safe across parallel sessions).
The LLM reads the active ID via CLI; it never writes the ID itself.
This means the linkage between a state entry, a decision, and a
pattern from the same task is cryptographically ordered from
the hook's perspective — not trusted to the model.
4. Schema-validated memory with secret-pattern scanning
memory.py append is the only supported write path. It validates
every entry against a YAML schema (memory/SCHEMA.md), rejects
duplicates, and scans the body for ~30 classes of secrets: AWS
access keys, GitHub PATs, Stripe tokens, Slack webhooks, GCP service
accounts, Azure connection strings, Telegram bot tokens, Discord
tokens, Heroku/Postmark UUIDs (context-scoped), generic high-entropy
tokens with secret: prefixes, and DB connection strings with
embedded credentials. Placeholder fences (${VAR}, <NAME>) suppress
the scan so your templates still write cleanly.
5. 186 curated domain specialists, not one generic "coder"
Harmonist's catalogue is not a handful of roles. It's 186 curated
specialists across 16 categories: blockchain-security-auditor for
Solidity audits, zk-steward for zero-knowledge circuits, visionos-
spatial-engineer for Apple Vision Pro, wechat-mini-program-developer
and xiaohongshu-specialist for the China market, laravel-livewire-
specialist for PHP, roblox-systems-scripter for Roblox Luau, 30+
marketing agents from SEO to Douyin, finance / sales / product /
support / academic coverage. The orchestrator picks by
domains × roles × tags, not by hard-coded slug lists.
6. Integration-as-a-prompt
There is no installer binary. Integration happens by pasting
integration-prompt.md into a Cursor Agent-mode session. The AI
reads the prompt, analyzes the project, asks the user which roles
will be active (engineering / design / product / marketing / sales /
support / finance / testing / academic), selects the right
specialists from agents/index.json, and wires everything up —
including writing a project-specific AGENTS.md with domain-tailored
invariants. The AI integrates itself.
7. Zero runtime dependencies, cross-platform parity
No npm, no Docker, no LangChain, no vector database. Pure Python
stdlib + bash. The enforcement runtime has two implementations —
POSIX .sh scripts for macOS / Linux / WSL, and a pure-Python
hook_runner.py for native Windows — and both paths are exercised
against identical test scenarios. 430+ test assertions in CI keep
them bit-for-bit compatible.
Requirements
Python 3.9+ — every script ships with a version guard; older
interpreters exit with a per-OS install hint.
Bash 3.2+ for POSIX shell paths (macOS default works). On native
Windows, the pure-Python hook_runner.py takes over; no WSL or Git
Bash required.
Git for version tracking.
An AI coding assistant that supports subagent dispatch — Cursor
is the primary integration; Claude Code, Copilot, Windsurf, Aider,
Kimi, Qwen, Gemini CLI, OpenCode, OpenClaw, and Antigravity are all
supported via adapters.
No third-party Python dependencies — stdlib only. No npm, no
Docker, no LangChain, no vector database.
Quick start
Option 1 — Integrate via Cursor (recommended)
# 1. Clone into the root of your project
cd your-project/
git clone https://github.com/GammaLabTechnologies/harmonist.git
# 2. Open the project in Cursor, switch to Agent mode
# 3. Paste the contents of harmonist/integration-prompt.md
# 4. Follow the AI's walkthrough — it will ask about your
# project's domain and roles, then wire everything up.
# 5. Start a NEW chat when integration is done.
That's it. The AI reads harmonist/agents/index.json, picks the
right specialists for your stack, writes a domain-specific
AGENTS.md, bootstraps .cursor/memory/, installs the enforcement
hooks, and records the integration state in
.cursor/pack-version.json.
A Claude Code plugin that automatically captures everything Claude does during your coding sessions, compresses it with AI (using Claude's agent-sdk), and injects relevant context back into future sessions.
