Harmonist
An IDE-hooked multi-agent workflow that enforces review, memory, and integrity checks for AI-assisted coding.
Per-dimension scores and reasoning
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.
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.
What 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 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.pyHow 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.