Harmonist
An IDE-hooked multi-agent workflow that enforces review, memory, and integrity checks for AI-assisted coding.
- Source repo
- GammaLabTechnologies/harmonist
- Stars
- ★ 2.2k
- Last updated
- 4mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 78/100 · Good
At a glance
- How it runs
- Works with
- Portable with changesClaude Code (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A Cursor-based team changing payment or authentication code that wants QA and review dispatch to be required before the coding turn can finish.
- Not a fit if
- Teams not using an AI coding assistant with subagent dispatch
- Teams wanting a standalone runtime rather than a project subfolder pack
- Teams unwilling to run review gates and handoff docs on every code change
- Source review
- 78/100 · Good
What does this agent do, and when should you use it?
Harmonist is a project-local workflow pack for AI-assisted software development, rather than an application runtime for building agentic products. It provides a catalogue of 193 specialists with structured metadata and routes work through agents/index.json using domains, roles, and tags. Its Cursor integration installs hooks under .cursor/hooks/ to observe subagent dispatch, file edits, memory updates, and session completion; the stop hook checks review activity, qa-verifier, and session-handoff.md updates after code changes. The pack also includes schema-validated local memory, SHA-256 supply-chain verification, upgrade and rollback tooling, and repomap.py for a local code map. Cursor is its primary integration; adapters are documented for Claude Code, GitHub Copilot, Windsurf, Aider, Gemini CLI, and others, with convention-and-validation fallbacks outside Cursor.
agents/scripts/integrate.py reads the pack and target project, selects specialists from agents/index.json, and creates project-level AGENTS.md, .cursor/agents/, .cursor/rules/, .cursor/memory/, and hook configuration. The sessionStart, afterFileEdit, subagentStart, subagentStop, beforeShellExecution, and stop hooks record execution state; after file changes, stop checks for a review-category agent, qa-verifier, and an updated .cursor/memory/session-handoff.md. memory.py append generates IDs, obtains the hook-generated correlation_id, validates entries against memory/SCHEMA.md, and scans for secret patterns; it also exposes search, latest, and rotate operations. upgrade.py verifies MANIFEST.sha256 before copying pack files, supports snapshots and rollback, while repomap.py can build, explore, search, impact, affected, and refresh a local symbol and import-graph index.
- A Cursor-based team changing payment or authentication code that wants QA and review dispatch to be required before the coding turn can finish.
- A product team spanning several engineering domains that needs task routing from a 193-role catalogue based on declared domains, roles, and task tags.
- A team that wants local, validated, searchable session state and architectural decisions while rejecting memory entries that match documented secret patterns.
- A security-conscious team that wants manifest verification before agent definitions are integrated, installed as extras, or upgraded.
- A developer joining an unfamiliar repository who needs repomap.py to query symbols, dependents, change impact, and potentially affected tests.
How do you install or deploy this agent?
Requirements are Python 3.9+, Git, and an AI coding assistant that supports subagent dispatch. No API credentials or other credentials are documented. Clone the repository as a subfolder of the target project, then run:
cd your-project/
git clone https://github.com/GammaLabTechnologies/harmonist.gitpython3 harmonist/agents/scripts/integrate.py --pack harmonist --project .
On native Windows:
py -3 harmonist\agents\scripts\integrate.py --pack harmonist --project .
For the documented interactive route, paste the contents of integration-prompt.md into Cursor Agent mode.
How do you use this agent?
After integration, use the generated project AGENTS.md to dispatch work in a supported coding assistant. For code-changing turns, the hooks track state and the stop gate requires the required reviews, qa-verifier, and an updated .cursor/memory/session-handoff.md. Example checks and queries:
python3 .cursor/memory/memory.py latest --file session-handoff --n 5
python3 .cursor/repomap/repomap.py explore "<question / symbol names>"To generate and install artifacts for another documented tool:
python3 agents/scripts/convert.py --tool <name>
python3 agents/scripts/install.pyWhat are this agent's strengths and limitations?
- It places completion conditions in lifecycle and stop hooks: missing QA, review, or handoff memory can return a followup_message instead of relying on prompt compliance.
- Its specialist catalogue uses one Schema v2 metadata format and routes via domains × roles × tags in agents/index.json rather than a fixed role list.
- MANIFEST.sha256, upgrade.py, and install_extras.py verify source files before copying, while .cursor/pack-manifest.json supports installed-file drift checks.
- The documented tooling is Python-stdlib based, including a native-Windows pure-Python hook path, with no Docker, npm, or third-party Python packages required.
- Mechanical enforcement is strongest with Cursor; the repository explicitly describes other tool integrations as convention-plus-validation fallbacks.
- The gate adds workflow overhead to code changes: required reviewers, qa-verifier, and session-handoff.md must be completed, and failed checks can trigger up to three follow-up loops.
- Adoption requires integrating the pack as a project subfolder and adding generated .cursor/ agents, rules, memory, and local state to the host workflow.
- It requires Python 3.9+, Git, and a coding assistant with subagent dispatch; Bash remains optional but is used for POSIX conveniences and shell test harnesses.
How does this agent compare with similar options?
Harmonist positions itself as a project-local governance layer for AI-assisted coding, not as a replacement for LangChain, CrewAI, AutoGen, or MetaGPT. The repository describes those projects as orchestration primitives for building agentic applications, while Harmonist uses IDE hooks to govern review, memory, and completion behavior in the coding workflow; the two approaches can coexist.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Harmonist This agent | 78 · Good | CLIFree + model costs | ★ 2.2k | 4mo ago | Python | — |
| OpenCode Swarm | 74 · Some gaps | Agent plugin / skillFree + model costs | ★ 518 | today | TypeScript | — |
| MCO | 73 · Some gaps | CLIFree + model costs | ★ 550 | 1mo ago | Python | Codex · Claude Code |
| Fusion Software Factory | 71 · Some gaps | CLIFree + model costs | ★ 1.3k | 5d ago | TypeScript | Codex · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: capability scoping via readonly field and concurrent subagent cap; beforeShellExecution hook provides human confirmation for dangerous commands; data flow transparent via hook state files and memory CLI; memory CLI scans ~30 secret patterns and rejects leaks; zero third-party dependencies, MANIFEST.sha256 verifies supply chain; external effects limited to project file writes and command execution with HITL gate; sha verification before upgrade, memory rotate for rollback; publisher identity unverified, maintenance responsibility inferred from README and SECURITY.md. Deductions: publisher unverified, source attribution only self-reported; user confirmation only for dangerous commands, not all external actions; rollback limited to memory files, not full system.
Evidence shows: README claims 193 agents consistent with badge, but description mentions 186, minor inconsistency; dependencies only Python 3.9+ and optional Bash, common environments; failure messages explicit in hook tests (e.g., followup_message, EXHAUSTED). Deductions: agent count inconsistency in self-description; failure message completeness not verified in real IDE environment.
Evidence shows: targets multiple AI coding assistants (Cursor, Claude Code, etc.), broad scenarios; capability boundaries defined via protocol types (strict/persona) and readonly restrictions; triggers precisely controlled via hook phases and AGENT markers; environment fit includes Windows/macOS/Linux, pure Python implementation. Deductions: capability boundaries rely on agent metadata, not verified for all agents; trigger precision relies on IDE hook support, not tested in real IDE.
Evidence shows: clear information architecture with TOC, architecture diagram, doc links; detailed install instructions (three options); naming stability (version numbers, agent slugs); examples and FAQ sections; known limitations not explicitly listed; MIT license clear; CHANGELOG and version file present; maintenance responsibility by GammaLab, but unverified. Deductions: known limitations section missing; maintenance responsibility only self-reported.
Evidence shows: output is structured memory entries and hook messages, directly usable; high marginal value, provides mechanical protocol enforcement and supply-chain verification; low cost, zero dependencies, simple install. Deductions: output usability not verified in real IDE; marginal value based on self-description, not independently tested.
Evidence shows: README claims (e.g., agent count, test count) supported by corresponding files (index.json, CI config); multiple test scripts (hooks/tests, memory/tests) provide cross-validation; facts and inferences mostly separated in README, but some promotional language (e.g., 'paranoid-level') is inference. Deductions: claims not independently verified; cross-validation only within repository.
- Publisher identity unverified; source attribution only self-reported, treat with caution.
- Agent count inconsistency in description (186 vs 193), needs verification.
- Known limitations not explicitly listed, potential issues may be hidden.
- All claims based on static source, not verified in real IDE environment.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.2.3 Harmonist v1.2.3
Release notes excerpt
Patch release: the final native-Windows determinism fix. With v1.2.1 (stdout glyphs) and v1.2.2 (catalog file reads), this makes the native-Windows CI job pass end to end for the first time — both the Linux and Windows jobs are green. Fixed - Deterministic index.json across operating systems. build_index.py wrote each agent's path field with str(Path(...)), producing backslashes on Windows, so build_index.py --check flagged the committed (forward-slash) index as stale on the Windows runner. It now uses .as_posix(), matching …View on GitHub ↗ -
v1.2.0 Harmonist v1.2.0
Release notes excerpt
Maintenance release: install-UX overhaul plus reliability hardening across hooks, memory, and the catalog. Headline fix — dropping the pack into a workspace no longer risks Cursor treating the orchestrator template as a live rule and demanding enforcement machinery that isn't installed yet. Install UX - AGENTS.md (pack root) renamed to AGENTS.template.md with an unmissable preamble: it is a TEMPLATE, not an active rule for the pack folder; AI agents asked to "install" must follow integration-prompt.md instead. The file generated in the USER's project keeps the name …View on GitHub ↗ -
v1.1.0 Harmonist v1.1.0
Release notes excerpt
Harmonist v1.1.0 — native Windows, 193 agents, hardened fail-closed enforcement. Highlights Cross-platform / native Windows - Pure-Python hook runtime (hook_runner.py) is the active path on macOS, Linux, WSL and native Windows (no bash required); upgrade.py renders hooks.json with a Python launcher that exists on the host. convert.py / install.py port the shell tooling; CI gains a native-Windows job. Catalogue (186 → 193 agents) - Model pinned to claude-opus-4-8 across the pool. …View on GitHub ↗