🛡️ Harmony Framework

A self-improving AI dev framework for Claude Code, Cursor & more

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

╔═══════════════════════════════════════════════════════════════════════════════╗
║                      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

🚀 Quick Start

# Install (requires jq + yq)
npx harmony-ai --full

# Start coding
/go                    # Session kickoff
/harmony               # Interactive menu (30 commands)
/harmony sentinel      # Error memory dashboard

30 seconds to install. A lifetime of saved debugging time.

📖 Full installation guide → · All 30 commands →

🤖 The Self-Improving Loop

╔═══════════════════════════════════════════════════════════════════════════════╗
║                    🔄 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

📊 What Makes Us Different

| 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 |

🔌 Works Everywhere

| 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 →

🛡️ Security Guards

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 →

📋 Prerequisites

| 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 →

📚 Documentation

| 📖 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) |

💬 What We Experienced Dogfooding Harmony

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.

🤝 Community

Report bugs · Ideas & help

📄 License

Released under the MIT License — SPDX: MIT.

© 2025 Harmony AI Team. Use it anywhere — contribute back if you can.

🏢 Enterprise & AI Consulting

Need production deployment with data security as top priority? Secure multi-env integration, LLM cost optimization, custom agents, data-security hardening. 📬 Details & contact →

🛡️ Stop repeating bugs. Start building right.

Get Started • How it works • Docs

⭐ Star us if Harmony saves you time!