Smart agent routing · Error memory · Verifiable quality gates
🚀 Quick Start • 🧠 How It Works • 📚 Docs • 🧩 Patterns
🌐 Language: English · Français
Harmony is an AI development framework that makes your AI assistant route the right agent, remember every bug it has seen, and prove quality instead of assuming it — across Claude Code, Cursor, Windsurf and more. It lives inside your project and adapts to your code: load only what's needed, when it's needed.
"Other frameworks help you build fast. Harmony helps you build right."
╔═══════════════════════════════════════════════════════════════════════════════╗
║ THE THREE PILLARS OF HARMONY ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ 🔒 GUARDIAN 🛡️ SENTINEL ✅ HQVF ║
║ ───────────── ─────────── ────────── ║
║ Intent Detection Error Memory Quality Gates ║
║ Agent Routing Circuit Breaker Use Case Verifiables ║
║ Workflow Protection Pattern Learning Triple Validation ║
║ ║
║ "Right agent, "Never repeat "Quality you can ║
║ right time" the same bug" prove, not assume" ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
…but Harmony is more than three pillars: 50+ specialized agents, domain specialties, tech-stack profiles, multi-IDE support, security guards and JIT context loading. 👉 See the full picture → docs/how-it-works.md
# Install (requires jq + yq)
npx harmony-ai --full
# Start coding
/go # Session kickoff
/harmony # Interactive menu (30 commands)
/harmony sentinel # Error memory dashboard30 seconds to install. A lifetime of saved debugging time.
📖 Full installation guide → · All 30 commands →
╔═══════════════════════════════════════════════════════════════════════════════╗
║ 🔄 THE SELF-IMPROVING LOOP ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║ ║
║ ┌─────────┐ ┌─────────┐ ┌─────────┐ ║
║ │ AI │ ──────► │ HARMONY │ ──────► │ AI │ ║
║ │ Makes │ │ Learns │ │ Better │ ║
║ │ Mistake │ │ Pattern │ │ Next │ ║
║ └─────────┘ └─────────┘ └─────────┘ ║
║ ║
║ 💡 Feed the framework with errors → It feeds you with solutions ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════════╝
Harmony lives in your project, learns your patterns, adapts to your style. The contribution cycle, zero-context-loss across sessions (UCVs), and JIT context loading are all detailed here 👉 docs/how-it-works.md
| Feature | 🏛️ Traditional | 🛡️ Harmony |
|---|---|---|
| 🧠 Error Memory | ❌ Start fresh every time | ✅ Learns from mistakes |
| 🔄 Circuit Breaker | ❌ Repeat failures endlessly | ✅ Stops after 3 failures |
| 🎯 Intent Detection | ❌ Manual agent selection | ✅ Auto-routing |
| ✅ Quality Gates | ❌ "It works" = done | ✅ Triple validation (DEV+TEST+QA) |
| 💾 Context Persistence | ❌ Lost between sessions | ✅ 3-tier memory |
| 📈 Pattern Learning | ❌ No learning | ✅ Gets smarter over time |
| 🛡️ Security Guards | ❌ Blind trust | ✅ Supply-chain + injection filtering |
| Any IDE | Any Stack | Any Team Size |
|---|---|---|
| Claude Code 🟢 · Cursor · Windsurf · Continue · Cody | TypeScript · Python · Go · Rust · React · Node · Django | Solo → Enterprise (500+) |
🎯 Auto-detection: profiles & specialties activate from your project context — and they're portable (not tied to Harmony, not IDE-locked). 👉 IDE support, profiles & specialties →
Guards that screen what runs, what enters, and what gets installed — and say so out loud when they fire:
| Guard | Default | Protects against |
|---|---|---|
| rules-enforcer | ✅ on | Destructive commands (rm -rf /, DROP DATABASE, fork bombs), shell-injection (curl | bash), secrets written to files |
| supply-chain-guard | ✅ on | Vulnerable / typosquatted packages, unpinned MCP servers, cooling-period packages, missing lock files |
| llm-output-sanitizer | ✅ on | Prompt injection, data exfiltration, hidden Unicode, leaked secrets in external content |
Each pass prints visible proof (🛡️ Rules: clean — no interdiction); a block stops
the action with its reason. Silence it anytime with HARMONY_HOOK_UI=off.
/hf:security:guards status # See current state
/hf:security:guards off # Disable supply-chain + sanitizer (zero perf impact)
⚠️ Defense-in-depth, not a silver bullet. Pattern-based detection — keep it updated and always combine with human review. 📖 Security Guards docs →
| Tool | Version | Required? |
|---|---|---|
| Node.js | v18+ | ✅ Runtime (npx) |
| Bash | 4.0+ | ✅ (macOS: brew install bash) |
| jq | 1.6+ | ✅ JSON processing |
| yq | v4+ (mikefarah) | ✅ YAML processing |
| Bun / Python 3.8+ | latest / 3.8+ | ⚪ Optional (speed / Prompt Monitor) |
📖 Detailed setup & verification →
| 📖 Guide | Description |
|---|---|
| 🚀 Getting Started | 5-minute tutorial |
| 🧠 How It Works | The full picture — diagrams, flows, JIT, UCVs |
| 💡 Core Concepts | The three pillars explained |
| 🏗️ Architecture | Technical deep-dive |
| ⌨️ Commands | All 30 commands |
| 🤖 Agents | The agent ecosystem |
| 📈 Impact & ROI | Estimated gains (from real experience) |
These are our own observations building Harmony with Harmony — your mileage will vary.
- Recurring bugs dropped sharply once Sentinel started remembering past errors.
- Debug time on known issues went from ~10 min to under a minute.
- "Works on my machine" stopped being a thing thanks to triple validation (DEV+TEST+QA).
- Agent confusion disappeared with Guardian auto-routing.
📈 Detailed estimates (token savings, time/cost projections) — clearly labeled as experience-based estimates — live in docs/enterprise.md.
Released under the MIT License — SPDX: MIT.
© 2025 Harmony AI Team. Use it anywhere — contribute back if you can.
Need production deployment with data security as top priority? Secure multi-env integration, LLM cost optimization, custom agents, data-security hardening. 📬 Details & contact →
Get Started • How it works • Docs
⭐ Star us if Harmony saves you time!