{"id":51223006,"url":"https://github.com/AR6420/Hail_Hydra","last_synced_at":"2026-07-01T04:00:34.517Z","repository":{"id":339286693,"uuid":"1161273618","full_name":"AR6420/Hail_Hydra","owner":"AR6420","description":"🐉 Hail Hydra — Multi-headed speculative execution framework for Claude Code. 10 AI agents, 3x faster, ~70% cheaper. Inspired by speculative decoding.","archived":false,"fork":false,"pushed_at":"2026-05-17T07:10:31.000Z","size":593,"stargazers_count":42,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-17T07:22:10.732Z","etag":null,"topics":["ai-agent","ai-agents-framework","ai-framwork","anthropic","claude","claude-code","claude-code-agents","context-engineering","haiku","hail-hydra","hydra","meta-prompting","multi-agent","multi-agent-collaboration","opus","sonnet","speculative-decoding","speculative-execution"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/hail-hydra-cc","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AR6420.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-18T23:27:10.000Z","updated_at":"2026-05-17T07:10:33.000Z","dependencies_parsed_at":"2026-02-19T05:00:02.961Z","dependency_job_id":null,"html_url":"https://github.com/AR6420/Hail_Hydra","commit_stats":null,"previous_names":["ar6420/hail_hydra"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/AR6420/Hail_Hydra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AR6420%2FHail_Hydra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AR6420%2FHail_Hydra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AR6420%2FHail_Hydra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AR6420%2FHail_Hydra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AR6420","download_url":"https://codeload.github.com/AR6420/Hail_Hydra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AR6420%2FHail_Hydra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34992071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-agents-framework","ai-framwork","anthropic","claude","claude-code","claude-code-agents","context-engineering","haiku","hail-hydra","hydra","meta-prompting","multi-agent","multi-agent-collaboration","opus","sonnet","speculative-decoding","speculative-execution"],"created_at":"2026-06-28T09:00:31.116Z","updated_at":"2026-07-01T04:00:34.508Z","avatar_url":"https://github.com/AR6420.png","language":"JavaScript","funding_links":[],"categories":["Source Catalog"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/AR6420/Hail_Hydra\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/🐉-HAIL_HYDRA-darkred?style=for-the-badge\u0026labelColor=black\" alt=\"Hail Hydra\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e🐉 H Y D R A\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMulti-Headed Speculative Execution for Claude Code\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e\"Cut off one head, two more shall take its place.\"\u003c/em\u003e\u003cbr/\u003e\n  \u003cem\u003eExcept here — every head is doing your work faster and cheaper.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Opus-🧠_The_Body-7C3AED?style=flat-square\" alt=\"Opus\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Sonnet-🔵_Smart_Heads-3B82F6?style=flat-square\" alt=\"Sonnet\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Haiku-🟢_Fast_Heads-22C55E?style=flat-square\" alt=\"Haiku\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/hail-hydra-cc\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/hail-hydra-cc?style=flat-square\u0026logo=npm\u0026logoColor=white\u0026color=CB3837\" alt=\"npm version\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/hail-hydra-cc\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dt/hail-hydra-cc?style=flat-square\u0026logo=npm\u0026logoColor=white\u0026color=22C55E\u0026label=downloads\" alt=\"npm downloads\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Speed-2--3×_Faster-22C55E?style=flat-square\u0026logo=zap\u0026logoColor=white\" alt=\"Speed\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Cost-40--60%25_Per_Dispatch-3B82F6?style=flat-square\u0026logo=piggy-bank\u0026logoColor=white\" alt=\"Cost\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Quality-Zero_Loss-7C3AED?style=flat-square\u0026logo=shield-check\u0026logoColor=white\" alt=\"Quality\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e10 agents \u0026nbsp;·\u0026nbsp; 12 slash commands \u0026nbsp;·\u0026nbsp; 4 hooks \u0026nbsp;·\u0026nbsp; Codebase map \u0026nbsp;·\u0026nbsp; Real token tracking \u0026nbsp;·\u0026nbsp; Persistent memory\u003c/strong\u003e\n\u003c/p\u003e\n\n---\n\n## 🧬 What is Hydra?\n\n**Hydra** is a curated multi-agent toolkit for Claude Code. It ships 10 specialized agents pinned to cost-effective models (Haiku and Sonnet), 12 slash commands for direct invocation, and one automatic touchpoint that recommends integration verification after substantial code changes.\n\nEach agent runs on the smallest model that can do its job well. When invoked, Hydra typically reduces per-task cost by 40–60% compared to running the same work on the orchestrator alone — while maintaining output quality through verification.\n\n\u003e **Think of it this way:**\n\u003e\n\u003e Would you hire a $500/hr architect to carry bricks? No. You'd have them design the building and let the crew handle construction. That's the model Hydra follows when you invoke a specialized head.\n\n**New in v2.0.0:** Every agent has **persistent memory** — they learn your codebase patterns, conventions, and architectural decisions across sessions. The orchestrator (Opus) also maintains its own memory of fragile zones and routing decisions. The **hydra-sentinel** workflow catches integration breakage after substantial code changes — and code isn't presented to you until verification completes.\n\n**New in v2.1.0:** The **Codebase Map** gives every agent instant access to file dependencies, blast radius, risk scores, and test coverage — replacing slow grep-based scanning with instant JSON lookups. Sentinel is now 3–5× faster and 3–5× cheaper per scan.\n\n**New in v2.3.2 — Internal Compression:** Subagents now run with compressed **INTERNAL thinking**, not just compressed final output. The intermediate prose (\"Let me check…\", \"I'll examine…\", \"Now I'll trace…\") that no one ever reads is drastically reduced — ~40–60% fewer billed tokens per subagent dispatch, with no change to the final output Opus receives. The new `/hydra:stfu` skill extends this compression to ALL subagents in a session — Hydra's own, third-party, and Claude Code's built-in agents. Session-scoped, runtime-only, no file modifications. Activate via `/hydra:stfu`; deactivate via `/skills`.\n\n**New in v2.4.0 — Toolkit Repositioning:** SKILL.md refocused to the toolkit-with-touchpoints model. The hydra-auto-guard hook now injects a sentinel verification directive after substantial code changes (new files, MultiEdit batches, or edits affecting more than ~5 lines). Trivial edits stay silent. `/hydra:stats` shows actionable guidance when no Hydra dispatches occurred in the session instead of empty zeros.\n\n## When to Use Hydra Explicitly\n\nHydra's biggest cost savings come from explicit invocation in scenarios where specialized handling genuinely helps:\n\n| Scenario | How to Invoke | Why It Saves |\n|----------|---------------|-------------|\n| Broad codebase exploration | `/hydra:scout \u003ctopic\u003e` or \"use hydra-scout to find X\" | Haiku reads files faster and cheaper than Opus |\n| Multi-file changes | \"use hydra-coder to update X across these files\" | Parallel Sonnet dispatch beats sequential Opus |\n| Security review | `/hydra:guard` | Pattern matching is Haiku-cheap |\n| Environment validation | `/hydra:preflight` | Cross-references compatibility matrices on Sonnet |\n| Codebase architecture review | `/hydra:map` | Dependency graph stored locally |\n\nFor one-off questions, simple edits, or conversational work, Claude Code handles it directly. Hydra's only automatic intervention is the post-substantial-edit sentinel verification directive — see [Sentinel](#-sentinel--integration-integrity) below.\n\n---\n\n## 🚀 Installation\n\n\u003e **One command. Done.**\n\n```bash\nnpx hail-hydra-cc@latest\n```\n\n[OR]\n\n```bash\nnpm i hail-hydra-cc@latest\n```\n\nRuns the interactive installer — deploys 10 agents, 12 slash commands, 4 hooks, and registers\nthe statusline and update checker. Done in seconds.\n\n### Manual Install\n\n```bash\n# Clone the repo\ngit clone https://github.com/AR6420/Hail_Hydra.git\ncd hydra\n\n# Deploy heads globally (recommended — available in every project)\n./scripts/install.sh --user\n\n# 🐉 Hail Hydra! Framework active in all Claude Code sessions.\n# ✅ 10 agents  ✅ 12 commands  ✅ 4 hooks  ✅ StatusLine  ✅ VERSION\n```\n\n### Installation Options\n\n```bash\n# User-level — available in ALL your Claude Code projects\n./scripts/install.sh --user\n\n# Project-level — just this one project\n./scripts/install.sh --project\n\n# Both — maximum coverage\n./scripts/install.sh --both\n\n# Check what's deployed\n./scripts/install.sh --status\n\n# Remove everything\n./scripts/install.sh --uninstall\n```\n\n### What Gets Installed\n\n```\n~/.claude/\n├── agents/                      # 10 agent definitions (all with memory: project)\n│   ├── hydra-scout.md           # 🟢 Haiku — explore codebase\n│   ├── hydra-runner.md          # 🟢 Haiku — run tests/builds\n│   ├── hydra-scribe.md          # 🟢 Haiku — write documentation\n│   ├── hydra-guard.md           # 🟢 Haiku — security/quality gate\n│   ├── hydra-git.md             # 🟢 Haiku — git operations\n│   ├── hydra-sentinel-scan.md   # 🟢 Haiku — fast integration sweep\n│   ├── hydra-preflight.md       # 🟢 Haiku — environment preflight check\n│   ├── hydra-coder.md           # 🔵 Sonnet — write/edit code\n│   ├── hydra-analyst.md         # 🔵 Sonnet — debug/diagnose\n│   └── hydra-sentinel.md        # 🔵 Sonnet — deep integration analysis\n├── commands/hydra/              # 10 slash commands\n│   ├── help.md                  # /hydra:help\n│   ├── status.md                # /hydra:status\n│   ├── update.md                # /hydra:update\n│   ├── config.md                # /hydra:config\n│   ├── guard.md                 # /hydra:guard\n│   ├── quiet.md                 # /hydra:quiet\n│   ├── verbose.md               # /hydra:verbose\n│   ├── report.md                # /hydra:report\n│   ├── map.md                   # /hydra:map\n│   └── preflight.md             # /hydra:preflight\n├── hooks/                       # 4 lifecycle hooks\n│   ├── hydra-check-update.js    # SessionStart — version check (background)\n│   ├── hydra-statusline.js      # StatusLine — status bar display\n│   ├── hydra-auto-guard.js      # PostToolUse — file change tracker\n│   ├── hydra-notify.js          # Notification — task completion sound\n│   └── hydra-task-complete.wav  # Notification sound file\n└── skills/\n    └── hydra/                   # Skill (Claude Code discoverable)\n        ├── SKILL.md             # Orchestrator instructions\n        ├── VERSION              # Installed version number\n        ├── config/\n        │   └── hydra.config.md  # User configuration (created by --config)\n        └── references/\n            ├── model-capabilities.md\n            └── routing-guide.md\n\n\u003e **Note:** `settings.json` is at `~/.claude/settings.json` — hooks and statusLine are registered there.\n```\n\n\u003e **Project-level** (`--project`): same files written to `.claude/` in your working\n\u003e directory instead of `~/.claude/`. Project-level takes precedence when both exist.\n\n---\n\n## ⚡ Slash Commands\n\n| Command | Description |\n|---------|-------------|\n| `/hydra:help` | Show all commands and agents |\n| `/hydra:status` | Show installed agents, version, and update availability |\n| `/hydra:update` | Update Hydra to the latest version |\n| `/hydra:config` | Show current configuration |\n| `/hydra:guard [files]` | Run manual security \u0026 quality scan |\n| `/hydra:quiet` | Suppress dispatch logs for this session |\n| `/hydra:verbose` | Enable verbose dispatch logs with timing |\n| `/hydra:report` | Report a bug, request a feature, or share feedback |\n| `/hydra:map` | View codebase dependency map, query blast radius, rebuild |\n| `/hydra:preflight` | Two-phase environment and compatibility check before starting a new project build |\n| `/hydra:stats` | Show real token usage, delegation rate, and actual savings (parses Claude Code session JSONL — no AI estimation) |\n\n### `/hydra:preflight` — Environment Validation\n\nRun before starting any new project build. Catches broken GPU stacks, missing env\nvars, and incompatible dependency pairs before they cost you hours of debugging.\n\n```\n/hydra:preflight\n```\n\nHydra runs a two-phase check:\n1. **Detection** (Haiku): probes runtimes, CUDA stack, deps, env vars, services\n2. **Analysis** (Sonnet): cross-references against compatibility matrices, flags\n   ✅ COMPATIBLE / ⚠️ KNOWN RISK / ❌ CONFIRMED BREAK\n\n---\n\n## 🖥️ Status Line\n\nAfter installation, your Claude Code status bar shows real-time framework info:\n\n```\n🐉 │ Opus │ Ctx: 37% ████░░░░░░ │ $0.42 │ my-project\n```\n\n| Element | What It Shows |\n|---------|---------------|\n| 🐉 | Hydra is active |\n| Model | Current Claude model (Opus, Sonnet, Haiku) |\n| Ctx: XX% | Context window usage with visual bar |\n| $X.XX | Session API cost so far |\n| Directory | Current working directory |\n| ⚠ Warning | Compaction warning (only at 70%+ context usage) |\n\n**Context bar colors:**\n- 🟢 Green (0–49%) — plenty of room\n- 🟡 Yellow (50–79%) — getting full, consider `/compact`\n- 🔴 Red (80%+) — context nearly full, `/compact` or `/clear` recommended\n\n**Compaction warnings** (appended automatically at 70%+):\n```\n🐉 │ Opus │ Ctx: 73% ███████░░░ │ $1.87 │ my-project │ ⚠ Auto-compact at 85%\n🐉 │ Opus │ Ctx: 83% ████████░░ │ $3.14 │ my-project │ ⚠ Compacting soon!\n```\n- ⚠ **Auto-compact at 85%** (70–79%) — heads-up that compaction is approaching\n- ⚠ **Compacting soon!** (80%+) — compaction is imminent, consider `/compact` now\n\n\u003e **Note:** If you already have a custom `statusLine` configured, the installer\n\u003e keeps yours and prints instructions for switching to Hydra's.\n\n---\n\n## 🔔 Task Completion Sound\n\nHydra plays a short notification sound when Claude Code finishes a substantial task — so you know it's done even if you've tabbed away.\n\n- **Cross-platform** — macOS (`afplay`), Windows (PowerShell), Linux (`paplay`/`aplay`)\n- **Non-blocking** — the sound plays detached; it never delays Claude's response\n- **Smart triggers** — only fires on substantial tasks (\u003e~10 seconds), not quick replies\n- **Controllable** — `/hydra:quiet` suppresses it, `/hydra:verbose` re-enables it\n\nThe notification hook is registered automatically during installation.\n\n---\n\n## 🔄 Auto-Update Notifications\n\nHydra checks for updates once per session in the background (never blocks startup).\nWhen a new version is available, you'll see it in the status bar:\n\n```\n🐉 │ Opus │ Ctx: 37% ████░░░░░░ │ $0.42 │ my-project │ ⚡ v1.1.0 available\n```\n\nUpdate with:\n\n```bash\n# From within Claude Code:\n/hydra:update\n\n# Or from your terminal:\nnpx hail-hydra-cc@latest --global\n```\n\nAfter updating, restart Claude Code to load the new files.\n\n---\n\n## ✨ Features\n\n- **Ten specialized heads** — Haiku (fast) and Sonnet (capable) heads for every task type, including preflight detection for new projects\n- **Sentinel integration integrity** — Two-tier verification (fast scan + deep analysis) catches ~72% of integration bugs before runtime\n- **Persistent agent memory** — Every agent remembers your codebase patterns, conventions, and past decisions across sessions\n- **Orchestrator memory** — Opus maintains its own notes on fragile zones, routing patterns, and known issues via CLAUDE.md\n- **Quality-first pipeline** — Code changes block until sentinel + guard verification completes; nothing reaches you unchecked\n- **Auto-Guard** — hydra-guard (Haiku) automatically scans code changes for security issues after every hydra-coder run\n- **Configurable modes** — `conservative`, `balanced` (default), or `aggressive` delegation via `hydra.config.md`\n- **Slash commands** — `/hydra:help`, `/hydra:status`, `/hydra:update`, `/hydra:config`, `/hydra:guard`, `/hydra:quiet`, `/hydra:verbose`, `/hydra:report` for full session control\n- **Task completion sound** — plays a notification when Claude finishes substantial tasks\n- **Quick commands** — natural language shortcuts: `hydra status`, `hydra quiet`, `hydra verbose`\n- **Custom agent templates** — Add your own heads using `templates/custom-agent.md`\n- **Session indexing** — Codebase context persists across turns; no re-exploration on every prompt\n- **Speculative pre-dispatch** — hydra-scout launches in parallel with task classification, saving 2–3 seconds per task\n- **Dispatch log** — Transparent audit trail showing which agents ran, what model, and outcome\n- **Codebase Map** — Persistent dependency graph built by hydra-scout. Maps every file's imports, dependents, risk score, env vars, and test coverage. Enables instant blast-radius lookups for sentinel — no more grepping the entire codebase.\n- **Risk-Based Verification** — Files with more dependents get more thorough verification. Critical files always trigger deep sentinel analysis. Low-risk files get fast-tracked.\n- **`/hydra:map`** — Inspect the dependency map, query blast radius for any file, or force a rebuild\n- **🆕 Real Token Tracking** — `/hydra:stats` parses Claude Code session logs directly to show actual usage and savings. No AI estimation, no marketing fluff — just real numbers from Anthropic's API responses.\n- **🆕 Internal Compression** — Subagent output and orchestrator responses are now compressed for efficiency. Sub-agent output is heavily compressed (only Opus reads it). Orchestrator responses drop filler and pleasantries while keeping natural prose.\n\n---\n\n## 🛡️ Sentinel — Integration Integrity\n\nMost bugs don't come from bad code — they come from good code that **doesn't fit together**. A renamed export, a changed return type, a missing dependency after a refactor. These integration issues slip past linters, type-checkers, and even code review because no single file looks wrong.\n\n**hydra-sentinel** catches them automatically.\n\n### How It Works\n\n```\nCode change lands (hydra-coder finishes)\n    │\n    ▼\n┌──────────────────────────────────────┐\n│  🟢 hydra-sentinel-scan (Haiku)  │  ← Runs on EVERY code change (~1-2s)\n│  Fast sweep: imports, exports,       │\n│  signatures, dependencies            │\n└──────────────┬───────────────────────┘\n               │\n          Issues found?\n          ├── No:  ✅ Pass — code proceeds to guard\n          │\n          └── Yes: Escalate\n               │\n               ▼\n┌──────────────────────────────────────┐\n│  🔵 hydra-sentinel (Sonnet)      │  ← Only when scan flags issues (~20-30%)\n│  Deep analysis: confirms real issues, │\n│  dismisses false positives,          │\n│  proposes fixes                      │\n└──────────────┬───────────────────────┘\n               │\n          Fix decision:\n          ├── Trivial (import typo): Auto-fix\n          ├── Medium (signature mismatch): Offer fix to user\n          └── Complex (architectural): Report with context\n```\n\n### What Sentinel Catches\n\n| Check Type | Priority | Example |\n|:-----------|:---------|:--------|\n| **Import/export mismatches** | P0 | Importing a function that was renamed or removed |\n| **Function signature changes** | P0 | Caller passes 2 args, function now expects 3 |\n| **Type contract violations** | P1 | Function returns `string` but caller expects `number` |\n| **Missing dependency updates** | P1 | New import added but package not in `package.json` |\n| **Cross-file rename gaps** | P1 | Variable renamed in definition but not all call sites |\n| **Circular dependency introduction** | P2 | New import creates A → B → C → A cycle |\n| **Dead code from refactoring** | P2 | Exported function no longer imported anywhere |\n| **Environment/config mismatches** | P2 | Code references env var that isn't in `.env.example` |\n\n### Example Output\n\n```\n🛡️ Sentinel Report\n──────────────────────────────────────\n✖ P0: src/auth.js imports `validateToken` from src/utils.js\n       but src/utils.js now exports `verifyToken` (renamed in this session)\n       → Fix: Update import to `verifyToken` [auto-fixable]\n\n⚠ P1: src/api/routes.js calls createUser(name, email)\n       but src/models/user.js:createUser now expects (name, email, role)\n       → Missing required parameter `role` added in this change\n\n✔ 6 other integration points verified clean\n──────────────────────────────────────\n```\n\n### Expected Detection Rates\n\n| Category | Estimated Detection Rate | Notes |\n|:---------|:------------------------|:------|\n| Import/export mismatches | ~95% | Direct string matching |\n| Signature mismatches | ~80% | Requires type inference |\n| Type contract violations | ~60% | Limited without full type system |\n| Missing dependencies | ~90% | Package.json diffing |\n| Cross-file rename gaps | ~70% | Heuristic-based |\n| Circular dependencies | ~85% | Import graph traversal |\n| Dead code | ~50% | Conservative — flags only obvious cases |\n| Config mismatches | ~40% | Pattern matching on env references |\n| **Weighted average** | **~72%** | Based on typical issue distribution |\n\n\u003e **Memory makes it better over time.** Sentinel remembers past false positives and known fragile\n\u003e integration points in your project. The more you use it, the more accurate it gets.\n\n---\n\n## 🗺️ Codebase Map\n\n**New in v2.1.0** — Hydra builds a persistent dependency map of your codebase,\ngiving every agent instant access to file relationships without scanning.\n\n### How It Works\n\nhydra-scout builds the map on first run by extracting import statements\nfrom every source file using grep (no external parsers required). The map\nis stored at `.claude/hydra/codebase-map.json`.\n\n```\nSession 1: scout builds the full map (~10 seconds for 500 files)\nSession 2: scout checks git hash → nothing changed → skip rebuild (instant)\nSession 3: scout checks git hash → 3 files changed → update only those 3\n```\n\n### What the Map Contains\n\n| Data | How It's Used |\n|:-----|:-------------|\n| **File imports** | \"auth.ts imports user.ts and env.ts\" |\n| **Reverse imports** | \"auth.ts is imported by users.ts, admin.ts, middleware.ts\" |\n| **Risk score** | low (0-1 deps) → medium (2-3) → high (4-6) → critical (7+) |\n| **Env var index** | \"JWT_SECRET is used in auth.ts and middleware.ts\" |\n| **Test coverage** | covered / partial / untested per file |\n| **Git staleness** | Hash comparison for instant freshness check |\n\n### Why This Matters\n\n**Without map** — When auth.ts changes, sentinel greps the ENTIRE codebase\nlooking for files that import it. In a 500-file project, that's 500 file reads.\nTakes 5-15 seconds, costs 3,000-8,000 tokens.\n\n**With map** — Sentinel reads the JSON, looks up auth.ts's `imported_by` array,\ngets `[users.ts, admin.ts, middleware.ts]` instantly. Reads only those 3 files.\nTakes \u003c2 seconds, costs 500-1,500 tokens.\n\n**Savings: 3-5× faster, 3-5× fewer tokens per sentinel scan.**\n\n### Risk-Based Sentinel Triggering\n\nThe map's risk scores let Opus make smarter verification decisions:\n\n| Modified File Risk | What Happens |\n|:-------------------|:------------|\n| 🔴 Critical (7+ deps) | Sentinel-scan + deep analysis (always) |\n| 🟠 High (4-6 deps) | Sentinel-scan, escalate if issues found |\n| 🟡 Medium (2-3 deps) | Sentinel-scan, escalate only for P0 issues |\n| 🟢 Low (0-1 deps) | Sentinel-scan, auto-accept if clean |\n\nThis means Hydra spends more verification effort where it matters most\n(high-risk files) and less where it doesn't (isolated utilities).\n\n### Inspect the Map\n\n```bash\n/hydra:map                       # Show summary — risk distribution, coverage stats\n/hydra:map src/services/auth.ts  # Show blast radius for a specific file\n/hydra:map rebuild               # Force a complete rebuild\n```\n\n### Technical Notes\n\n- The map is built using grep + regex — no Tree-sitter, no AST parsing, no\n  external dependencies. Works with JS/TS, Python, Go, Java, Kotlin, Ruby, Rust.\n- Supports relative import resolution (e.g., `'./auth'` → `src/services/auth.ts`)\n- Falls back gracefully — if the map doesn't exist, all agents use their\n  original grep-based behavior. The map is an optimization, not a requirement.\n- Stored at `.claude/hydra/codebase-map.json` — add to `.gitignore` (machine-generated).\n\n---\n\n## 📊 Real Token Tracking\n\n**New in v2.3.0** — `/hydra:stats` shows actual token usage and savings for\nyour session. No AI estimation. The numbers are pulled directly from Claude\nCode's session log.\n\n```\n🐉 Hydra Stats\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nSession: 7c3a9e21.jsonl\nTurns:   38\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n🟢 Haiku  (24 turns):  142.3k in / 8.1k out  → $0.183\n🔵 Sonnet (9 turns):   67.4k in / 3.2k out   → $0.250\n🟣 Opus   (5 turns):   45.1k in / 2.8k out   → $0.296\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nDelegation rate:    87.0% (33/38 turns)\nActual cost:        $0.729\nAll-Opus baseline:  $1.502\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n💰 Saved:           $0.773 (51.5%)\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nReads Claude Code session JSONL directly.\nNo AI estimation. Numbers are real.\n```\n\nThe \"All-Opus baseline\" is the hypothetical cost if every Hydra agent had\nbeen Opus instead. The savings show what Hydra's model routing actually\nsaves you in this session. Implementation is pure Node.js — works on\nWindows, macOS, and Linux. Respects `CLAUDE_CONFIG_DIR` env override.\n\n---\n\n## 🧠 Agent Memory\n\nWithout memory, every session starts cold. Agents re-discover your conventions, re-learn your\nproject structure, and repeat the same questions. With memory, knowledge compounds.\n\n| Aspect | Without Memory | With Memory |\n|:-------|:---------------|:------------|\n| **First task** | Agent explores from scratch | Agent recalls project patterns |\n| **Conventions** | May use wrong style | Remembers your naming, structure, patterns |\n| **Known issues** | No awareness of past bugs | Recalls fragile areas and past fixes |\n| **Routing accuracy** | Generic classification | Improved by past dispatch outcomes |\n| **False positives** | Same false alarms repeat | Sentinel suppresses known non-issues |\n\n### How It Works\n\nEvery agent has `memory: project` in its frontmatter. Claude Code automatically manages a\nper-project memory directory (`.claude/memory/`) where agents store and retrieve learnings.\n\n| Agent | What It Remembers |\n|:------|:------------------|\n| **hydra-scout** | Project structure patterns, key file locations, search shortcuts |\n| **hydra-runner** | Test commands, common failure patterns, build quirks |\n| **hydra-scribe** | Documentation style, preferred formats, terminology |\n| **hydra-guard** | Known false positives, project-specific security patterns |\n| **hydra-git** | Commit conventions, branch naming, merge preferences |\n| **hydra-sentinel-scan** | Known fragile integration points, past false positives |\n| **hydra-coder** | Coding style, architecture patterns, preferred libraries |\n| **hydra-analyst** | Common bug patterns, performance hotspots, review focus areas |\n| **hydra-sentinel** | Integration history, confirmed vs dismissed findings |\n| **Orchestrator (Opus)** | Fragile zones, routing accuracy, escalation patterns (via CLAUDE.md Hydra Notes) |\n\n### Memory Properties\n\n- **Automatic** — agents read and write memory without any user action\n- **Project-scoped** — each project has its own memory; no cross-contamination\n- **Persistent** — survives across sessions; compounds over time\n- **Manageable** — stored as plain markdown in `.claude/memory/`; edit or delete anytime\n\n### The Compound Effect\n\nSession 1: Agents learn your project. Session 5: They know your conventions. Session 20: They\nanticipate your patterns. The framework gets more efficient the more you use it — not because\nthe models improve, but because context quality improves.\n\n---\n\n## 🤔 Why I Built This\n\nAfter Opus 4 dropped, I noticed something frustrating — code execution felt slowww. Reallyyy Slow. Not because the model was worse, but because I was feeding everything through one massive model. Every file read, every grep, every test run, every docstring — all burning through Opus-tier tokens. The result? Frequent context compaction, more hallucinations, and an API bill that made me wince.\n\nSo I started experimenting. I switched to Haiku for the simple stuff — running commands, tool calls, file exploration. Sonnet for code generation, refactoring, reviews. And kept Opus only for what it's actually good at: planning, architecture, and the hard decisions. The result surprised me. Same code quality. Sometimes better — because each model was operating within a focused context window instead of one overloaded one.\n\nFive agents. Five separate context windows. Each with a clearly defined job. They do the work, and only pass results back to the brain — Opus. The outcome:\n\n- Longer coding sessions (less compaction, less context blowup)\n- Drastically reduced API costs (Haiku is 5× cheaper than Opus)\n- Faster execution (Haiku responds ~10× faster)\n- Same or better code quality (focused context \u003e bloated context)\n- Zero manual model switching (this is the big one)\n\nBecause that was the real pain — manually switching between models for every task tier to save costs. Every. Single. Time. So I built a framework that does it for me. And honestly? It does it better than I did. That was hard to admit, but here we are.\n\nI also didn't want it to be boring. So I gave it teeth, heads, and a battle cry. If you prefer something more buttoned-up, the [`spec-exec`](../../tree/spec-exec) branch has the same framework with zero theatrics.\n\n*Hail Hydra. Have fun.*\n\n---\n\n## 💡 The Theory (for nerds)\n\nSpeculative decoding (Chen et al., 2023) accelerates LLM inference by having a small **draft model** propose tokens that a large **target model** verifies in parallel. Since verifying K tokens costs roughly the same as generating 1 token, you get 2–2.5× speedup with **zero quality loss**.\n\nHydra applies this at the **task level**:\n\n```\n                          ┌─────────────────────────────────┐\n                          │  SPECULATIVE DECODING (tokens)  │\n                          │                                 │\n                          │  Small model drafts K tokens    │\n                          │  Big model verifies in parallel │\n                          │  Accept or reject + resample    │\n                          │  Result: 2-2.5× speedup         │\n                          └─────────────────────────────────┘\n                                        │\n                                   Same idea,\n                                  bigger scale\n                                        │\n                                        ▼\n                          ┌─────────────────────────────────┐\n                          │  🐉 HYDRA (tasks)               │\n                          │                                 │\n                          │  Haiku/Sonnet drafts the task   │\n                          │  Opus verifies (quick glance)   │\n                          │  Accept or redo yourself        │\n                          │  Result: 2-3× speedup           │\n                          └─────────────────────────────────┘\n```\n\nThe math is simple: if 70% of tasks can be handled by Haiku (10× faster, 5× cheaper) and 20% by Sonnet (3× faster, ~1.7× cheaper), your effective speed and cost improve dramatically — even accounting for the occasional rejection.\n\n---\n\n## 🏗️ Architecture\n\n```\nUser Request\n    │\n    ├──────────────────────────────────────────────────────┐\n    │                                                      │\n    ▼                                                      ▼\n┌─────────────────────────────┐            ┌──────────────────────────────┐\n│  🧠 ORCHESTRATOR (Opus)     │            │  🟢 hydra-scout (Haiku)  │\n│  Classifies task            │            │  IMMEDIATE pre-dispatch:      │\n│  Plans waves                │            │  \"Find files relevant to      │\n│  Decides blocking / not     │            │   [user's request]\"           │\n└────────┬────────────────────┘            └──────────────┬───────────────┘\n         │         (unless Session Index already covers)  │\n         └──────────────────────┬──────────────────────────┘\n                                │ (scout + classification both ready)\n                      [Session Index updated]\n                                │\n    ════════════════════════════════════════════════════════\n    Wave N  (parallel dispatch, index context injected)\n    ┌───────────────────┬──────────────────────────────────┐\n    │  SEQUENTIAL       │  PARALLEL (wait for all)         │\n    ▼                   ▼                                  │\n [coder]            [scribe] ──────────────────────────────┘\n    │\n    ▼\n ALL agents complete (Opus waits for every dispatched agent)\n    │\n    ├── Raw data / clean pass? → AUTO-ACCEPT → (updates Session Index if scout)\n    └── Code / analysis / user-facing docs? → Orchestrator verifies\n         │\n         ▼\n   ┌─────────────────────────────────────────────────────┐\n   │  🛡️ QUALITY GATE (blocks until complete)            │\n   │                                                     │\n   │  🟢 sentinel-scan (Haiku) — fast integration sweep  │\n   │       └── issues? → 🔵 sentinel (Sonnet) — deep     │\n   │  🟢 guard (Haiku) — security/quality scan           │\n   │                                                     │\n   │  Both must pass before result reaches user           │\n   └──────────────────────┬──────────────────────────────┘\n                          │\n                          ▼\n   User gets result (single response, all agent outputs included)\n```\n\n---\n\n## 🐲 The Ten Heads\n\n| Head | Model | Speed | Role | Personality |\n|:-----|:------|:------|:-----|:------------|\n| **hydra-scout (Haiku)** | 🟢 Haiku | ⚡⚡⚡ | Codebase exploration, file search, reading | *\"I've already found it.\"* |\n| **hydra-runner (Haiku)** | 🟢 Haiku | ⚡⚡⚡ | Test execution, builds, linting, validation | *\"47 passed, 3 failed. Here's why.\"* |\n| **hydra-scribe (Haiku)** | 🟢 Haiku | ⚡⚡⚡ | Documentation, READMEs, comments | *\"Documented before you finished asking.\"* |\n| **hydra-guard (Haiku)** | 🟢 Haiku | ⚡⚡⚡ | Security/quality gate after code changes | *\"No secrets. No injection. You're clean.\"* |\n| **hydra-git (Haiku)** | 🟢 Haiku | ⚡⚡⚡ | Git: commit, branch, diff, stash, log | *\"Committed. Conventional message. Clean diff.\"* |\n| **hydra-sentinel-scan (Haiku)** | 🟢 Haiku | ⚡⚡⚡ | Fast integration sweep after code changes | *\"Imports check out. Signatures match. Clean.\"* |\n| **hydra-preflight (Haiku)** | 🟢 Haiku | ⚡⚡⚡ | Environment detection, version probing, dep inventory | *\"Your PyTorch/CUDA pair is broken. Pin torch==2.7.0.\"* |\n| **hydra-coder (Sonnet)** | 🔵 Sonnet | ⚡⚡ | Code implementation, refactoring, features | *\"Feature's done. Tests pass.\"* |\n| **hydra-analyst (Sonnet)** | 🔵 Sonnet | ⚡⚡ | Code review, debugging, analysis | *\"Found 2 critical bugs and an N+1 query.\"* |\n| **hydra-sentinel (Sonnet)** | 🔵 Sonnet | ⚡⚡ | Deep integration analysis (when scan flags issues) | *\"2 real issues confirmed. 1 false positive dismissed.\"* |\n\n### Task Routing Cheat Sheet\n\n```\nIs it read-only? ─── Yes ──→ Finding files?\n    │                           ├── Yes: hydra-scout (Haiku) 🟢\n    │                           └── No:  hydra-analyst (Sonnet) 🔵\n    │\n    No ──→ Is it a git operation? ─── Yes ──→ hydra-git (Haiku) 🟢\n    │\n    No ──→ Is it a security scan? ─── Yes ──→ hydra-guard (Haiku) 🟢\n    │\n    No ──→ Just running a command? ─── Yes ──→ hydra-runner (Haiku) 🟢\n    │\n    No ──→ Writing docs only? ─── Yes ──→ hydra-scribe (Haiku) 🟢\n    │\n    No ──→ Clear implementation approach? ─── Yes ──→ hydra-coder (Sonnet) 🔵\n    │\n    No ──→ Needs deep reasoning? ─── Yes ──→ 🧠 Opus (handle it yourself)\n\n    Code was just changed? ─── Yes ──→ hydra-sentinel-scan (Haiku) 🟢\n        │                                   │\n        │                              Issues found?\n        │                              ├── No:  Done ✅\n        │                              └── Yes: hydra-sentinel (Sonnet) 🔵\n```\n\n---\n\n## ⚙️ Configuration\n\nCustomize Hydra's behavior with an optional config file:\n\n```bash\n# Create a default config (user-level — applies to all projects)\n./scripts/install.sh --config\n```\n\nThen edit `~/.claude/skills/hydra/config/hydra.config.md`:\n\n```markdown\nmode: balanced          # conservative | balanced (default) | aggressive\ndispatch_log: on        # on (default) | off | verbose\nauto_guard: on          # on (default) | off\n```\n\n**Project-level config** (overrides user-level):\nPlace at `.claude/skills/hydra/config/hydra.config.md` in your project root.\n\nSee [`config/hydra.config.md`](config/hydra.config.md) for the full reference with all options.\n\n---\n\n## 🧩 Extending Hydra\n\nAdd your own specialized head in three steps:\n\n**1. Copy the template:**\n```bash\ncp templates/custom-agent.md agents/hydra-myspecialist.md\n```\n\n**2. Customize the agent** — edit the name, description, tools, and instructions.\n\n**3. Deploy it:**\n```bash\n./scripts/install.sh --user   # or --project\n```\n\nYour new head is now discoverable by Claude Code alongside the built-in ten.\nSee [`templates/custom-agent.md`](templates/custom-agent.md) for the full template with\ninstructions on writing effective agent descriptions, output formats, and collaboration protocols.\n\n---\n\n## 📂 Repository Structure\n\n```\nhydra/\n├── 📄 SKILL.md                          # Core framework instructions\n├── 🐲 agents/\n│   ├── hydra-scout.md                   # 🟢 Codebase explorer\n│   ├── hydra-runner.md                  # 🟢 Test \u0026 build executor\n│   ├── hydra-scribe.md                  # 🟢 Documentation writer\n│   ├── hydra-guard.md                   # 🟢 Security/quality gate\n│   ├── hydra-git.md                     # 🟢 Git operations\n│   ├── hydra-sentinel-scan.md           # 🟢 Fast integration sweep\n│   ├── hydra-preflight.md               # 🟢 Environment preflight check\n│   ├── hydra-coder.md                   # 🔵 Code implementer\n│   ├── hydra-analyst.md                 # 🔵 Code reviewer \u0026 debugger\n│   └── hydra-sentinel.md               # 🔵 Deep integration analysis\n├── 📚 references/\n│   ├── routing-guide.md                 # 30+ task classification examples\n│   └── model-capabilities.md            # What each model excels at\n├── ⚙️ config/\n│   └── hydra.config.md                  # User configuration template\n├── 📋 templates/\n│   └── custom-agent.md                  # Template for adding your own heads\n└── 🔧 scripts/\n    └── install.sh                       # One-command deployment\n```\n\n---\n\n## 📊 Expected Impact\n\n| Metric | Without Hydra | With Hydra | Improvement |\n|:-------|:-------------|:-----------|:------------|\n| **Task Speed (per dispatch)** | 1× (Opus for everything) | 2–3× faster | 🟢 Haiku heads respond ~10× faster |\n| **API Cost (per dispatch)** | 1× (Opus for everything) | ~0.5× per dispatch | 40–60% cheaper when invoked |\n| **Quality** | Opus-level | Opus-level | Zero degradation |\n| **User Experience** | Normal | Normal | Explicit invocation; one automatic touchpoint (post-substantial-edit verification) |\n| **Overhead per turn (Turn 2+)** | Full re-exploration each turn | Session index reused | 🟢 2-4s saved per turn |\n| **Scout/runner verification** | Opus reviews every output | Auto-accepted for factual data | 🟢 ~50-60% of outputs skip review |\n| **Integration bugs caught** | 0% (no verification) | ~72% caught before runtime | 🟢 Sentinel auto-verification |\n| **Session knowledge** | Starts cold every time | Compounds across sessions | 🟢 Persistent agent memory |\n| **Sentinel scan speed** | 5-15 seconds (grep) | \u003c2 seconds (map lookup) | 🟢 3-5× faster with codebase map |\n| **Sentinel scan tokens** | 3,000-8,000 per scan | 500-1,500 per scan | 🟢 3-5× fewer tokens per scan |\n\n### How the Savings Work\n\n| Task Type | % of Work | Model Used | Input Cost vs Opus | Output Cost vs Opus |\n|:----------|:----------|:-----------|:----------------------|:-----------------------|\n| Exploration, search, tests, docs | ~50% | 🟢 Haiku | 20% ($1 vs $5/MTok) | 20% ($5 vs $25/MTok) |\n| Implementation, review, debugging | ~30% | 🔵 Sonnet | 60% ($3 vs $5/MTok) | 60% ($15 vs $25/MTok) |\n| Architecture, hard problems | ~20% | 🧠 Opus | 100% (no change) | 100% (no change) |\n| Sentinel scan (fast) | Auto (every code change) | 🟢 Haiku | 20% | 20% |\n| Sentinel deep (conditional) | ~20-30% of code changes | 🔵 Sonnet | 60% | 60% |\n| **Blended effective cost** | | | **~48% of all-Opus** | **~48% of all-Opus** |\n\nNote: When Hydra is invoked across a representative mix of task types, blended input = (0.5×$1 + 0.3×$3 + 0.2×$5) / $5 = $2.40/$5 ≈ 48% of all-Opus.\nPer-dispatch savings of **40–60%** are typical for Hydra-invoked work. Session-level savings depend on how often Hydra is invoked — run `/hydra:stats` for real numbers from your session.\nSavings calculated against Opus ($5/$25 per MTok) as of February 2026.\n\n### Measure Your Savings\n\nThe most accurate way to measure Hydra's impact — no estimation, real numbers:\n\n1. Start a Claude Code session **without** Hydra installed\n2. Complete a representative coding task\n3. Note the session cost from Claude Code's cost display\n4. Start a **new** session **with** Hydra installed\n5. Complete a similar task\n6. Compare the two costs\n\nThat's it. Real data beats theoretical calculations every time.\n\n#### What to expect (based on February 2026 API pricing)\nWhen Hydra is actively invoked across a typical mix (50% Haiku, 30% Sonnet, 20% Opus):\n- **Input tokens**: ~52% cheaper per dispatch ($2.40 vs $5.00 per MTok)\n- **Output tokens**: ~52% cheaper per dispatch ($12.00 vs $25.00 per MTok)\n- **Per-dispatch blended**: 40–60% cost reduction on Hydra-invoked work\n- **Speed**: 2–3× faster on delegated tasks\n\nSession-level savings depend on invocation frequency. `/hydra:stats` reports real numbers from your Claude Code session JSONL — no estimation.\n\n\u003e Note: Savings calculated against Opus pricing ($5/$25 per MTok) as of February 2026.\n\u003e Savings would be significantly higher compared to older Opus versions ($15/$75 per MTok).\n\n### Additional Savings from Codebase Map (v2.1.0+)\n\nThe codebase map provides additional token savings on TOP of the model-routing\nsavings above:\n\n| Operation | Without Map | With Map | Savings |\n|:----------|:-----------|:---------|:--------|\n| Sentinel scan (per change) | 3,000-8,000 tokens | 500-1,500 tokens | ~3-5× |\n| Scout exploration (repeat session) | 5,000-15,000 tokens | 1,000-3,000 tokens | ~3-5× |\n| Blast radius computation | Grep entire codebase | JSON lookup | Instant |\n\nThese savings compound with every code change in a session. In a session with\n5 code changes, the map saves roughly 10,000-30,000 tokens on sentinel scans alone.\n\n---\n\n## 🎯 Design Principles\n\n### 🫥 Invisibility\n\u003e The user should **never** notice Hydra operating. No announcements, no permission requests, no process narration. If a head does the work, present the output as if Opus did it.\n\n### ⚡ Speed Over Ceremony\n\u003e Don't overthink classification. Quick mental check: \"Haiku? Sonnet? Me?\" and go. If you spend 10 seconds classifying a 5-second task, you've defeated the purpose.\n\n### 🔀 Parallel Heads\n\u003e Independent subtasks launch in parallel. \"Fix the bug AND add tests\" → two heads working simultaneously.\n\n### ⬆️ Escalate, Never Downgrade\n\u003e If a head's output isn't good enough, Opus does it directly. No retries at the same tier. This mirrors speculative decoding's rejection sampling — when a draft token is rejected, the target model samples directly.\n\n---\n\n## 🔬 The Speculative Decoding Connection\n\nFor those who want to go deeper, here's how Hydra maps to the original speculative decoding concepts:\n\n| Speculative Decoding Concept | Hydra Equivalent |\n|:-----------------------------|:-----------------|\n| Target model (large) | 🧠 Opus — the orchestrator |\n| Draft model (small) | 🟢 Haiku / 🔵 Sonnet heads |\n| Draft K tokens | Heads draft the full task output |\n| Parallel verification | Opus glances at the output |\n| Modified rejection sampling | Accept → ship it. Reject → Opus redoes it. |\n| Acceptance rate (~70-90%) | Target: 85%+ of delegated tasks accepted as-is |\n| Guaranteed ≥1 token per loop | Every task produces a result — Opus catches failures |\n| Temperature/nucleus compatibility | Works with any coding task type or domain |\n\n### Key Papers\n- [Accelerating Large Language Model Decoding with Speculative Sampling](https://arxiv.org/abs/2302.01318) — Chen et al., 2023 (DeepMind)\n- [Fast Inference from Transformers via Speculative Decoding](https://arxiv.org/abs/2211.17192) — Leviathan et al., 2022 (Google)\n\n---\n\n## 🤔 FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWill I notice any quality difference?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nNo. Hydra only delegates tasks that are within each model's capability band. If there's any doubt, the task stays with Opus. And Opus always verifies — if a head's output isn't up to standard, Opus redoes it before you ever see it.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eIs this actually speculative decoding?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nNot at the token level — that happens inside Anthropic's servers and we can't modify it. Hydra applies the same \u003cem\u003ephilosophy\u003c/em\u003e at the task level: draft with a fast model, verify with the powerful model, accept or reject. Same goals (speed + cost), same guarantees (zero quality loss), different granularity.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat if I'm not using Opus?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nHydra is designed for the Opus-as-orchestrator pattern, but the principles apply at any tier. If you're running Sonnet as your main model, you could adjust the heads to use Haiku for everything delegatable.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I customize which models the heads use?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nAbsolutely. Each head is a simple Markdown file with a \u003ccode\u003emodel:\u003c/code\u003e field in the frontmatter. Change \u003ccode\u003emodel: haiku\u003c/code\u003e to \u003ccode\u003emodel: sonnet\u003c/code\u003e (or any supported model) and you're done.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDo the heads work with subagents I already have?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nYes. Hydra heads coexist with any other subagents. Claude Code discovers all agents in the \u003ccode\u003e.claude/agents/\u003c/code\u003e directories. No conflicts.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow do I uninstall?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\nRemoves all agents, commands, hooks, and cache files. Deregisters hooks from\n`~/.claude/settings.json`. Your other Claude Code configuration is preserved.\n\n```bash\n./scripts/install.sh --uninstall\n# or: npx hail-hydra-cc --uninstall\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat is Sentinel and how does it work?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nSentinel is a two-tier integration verification system. After every code change, \u003cstrong\u003ehydra-sentinel-scan\u003c/strong\u003e (Haiku) runs a fast sweep (~1-2s) checking imports, exports, function signatures, and dependencies. If it finds potential issues, \u003cstrong\u003ehydra-sentinel\u003c/strong\u003e (Sonnet) performs deep analysis to confirm real problems and dismiss false positives. The result is ~72% of integration bugs caught before they reach you.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes Sentinel slow things down?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nThe fast scan adds ~1-2 seconds per code change. The deep analysis only triggers when the scan flags issues (~20-30% of changes), adding another ~3-5 seconds in those cases. For the ~70-80% of changes that are clean, you'll barely notice it. The time saved debugging integration issues far outweighs the scan overhead.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWill Sentinel auto-fix things without asking?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nOnly trivial fixes (like updating an import path after a rename). For medium-complexity fixes (signature mismatches), it offers the fix for your approval. For complex architectural issues, it reports the problem with context but doesn't attempt a fix. You stay in control.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCan I disable Sentinel?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nYes. Set \u003ccode\u003esentinel: off\u003c/code\u003e in your \u003ccode\u003ehydra.config.md\u003c/code\u003e. You can also set \u003ccode\u003esentinel: scan-only\u003c/code\u003e to keep the fast sweep but skip deep analysis. The default is \u003ccode\u003eon\u003c/code\u003e (both tiers).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes Agent Memory use extra tokens?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nMemory is loaded as part of each agent's context when it starts, so it does use some tokens — but agent memory files are small (typically a few hundred tokens each). The improved accuracy from having project context usually \u003cem\u003esaves\u003c/em\u003e tokens by reducing re-exploration and misclassification.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhere is agent memory stored?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nIn \u003ccode\u003e.claude/memory/\u003c/code\u003e within your project directory. Each agent stores its own memory as plain markdown files. You can read, edit, or delete them anytime. Memory is project-scoped — each project has its own memory, no cross-contamination.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes Opus (the orchestrator) also have memory?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nYes. Opus maintains a \"Hydra Notes\" section in your project's \u003ccode\u003eCLAUDE.md\u003c/code\u003e file. This includes fragile integration zones, routing accuracy observations, and known issues. Unlike agent memory (which is per-agent), orchestrator memory is visible to all agents and informs dispatch decisions.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat is the Codebase Map?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nA persistent JSON file that maps every file's imports, dependents, risk score,\nenv var references, and test coverage. Built by hydra-scout using grep (no external\nparsers). Stored at \u003ccode\u003e.claude/hydra/codebase-map.json\u003c/code\u003e. Enables instant\nblast-radius lookups for sentinel instead of scanning the entire codebase.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDo I need to build the map manually?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nNo. hydra-scout builds it automatically the first time it's dispatched for\nexploration. After that, it updates incrementally (only changed files) using\ngit hash comparison. You can force a rebuild with \u003ccode\u003e/hydra:map rebuild\u003c/code\u003e\nor inspect it with \u003ccode\u003e/hydra:map\u003c/code\u003e.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eDoes the map work with my language?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nThe map extracts imports using grep patterns for JavaScript, TypeScript, Python,\nGo, Java, Kotlin, Ruby, and Rust. If your language isn't supported, agents fall\nback to their original grep-based behavior — the map is an optimization, not\na requirement. More languages can be added in future versions.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow big is the map file?\u003c/strong\u003e\u003c/summary\u003e\n\u003cbr/\u003e\nFor a 500-file project, the map is typically 50-150KB. For a 5,000-file project,\nit's around 500KB-1.5MB. It's a single JSON file — no database, no external\nservices, nothing to maintain.\n\u003c/details\u003e\n\n---\n\n## 💬 Feedback\n\nFound a bug? Have a feature idea? Want to share feedback?\n\n**From within Claude Code:**\n```\n/hydra:report\n```\n\n**Or directly on GitHub:**\n- [Report a Bug](https://github.com/AR6420/Hail_Hydra/issues/new?template=bug_report.md)\n- [Request a Feature](https://github.com/AR6420/Hail_Hydra/issues/new?template=feature_request.md)\n- [Share Feedback](https://github.com/AR6420/Hail_Hydra/issues/new?template=feedback.md)\n\n---\n\n## 🤝 Contributing\n\nFound a task type that gets misclassified? Have an idea for a new head? Contributions are welcome!\n\n1. Fork it\n2. Create your branch (`git checkout -b feature/hydra-new-head`)\n3. Commit (`git commit -m 'Add hydra-optimizer head for perf tuning'`)\n4. Push (`git push origin feature/hydra-new-head`)\n5. Open a PR\n\n---\n\n## 📜 License\n\nMIT — Use it, fork it, deploy it. Just don't use it for world domination.\n\n*...unless it's code world domination. Then go ahead.*\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cbr/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/🐉-HAIL_HYDRA-darkred?style=for-the-badge\u0026labelColor=black\" alt=\"Hail Hydra\" /\u003e\n  \u003cbr/\u003e\u003cbr/\u003e\n  \u003cem\u003eBuilt with 🧠 by Claude Opus — ironically, the model this framework is designed to use less of.\u003c/em\u003e\n  \u003cbr/\u003e\n  \u003cem\u003ev2.0.4 — Now with memory, integration integrity, and task notifications.\u003c/em\u003e\n\u003c/p\u003e\n\n---\n\u003e Prefer a clean, technical version? See the [`spec-exec`](../../tree/spec-exec) branch — same framework, zero theatrics.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAR6420%2FHail_Hydra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAR6420%2FHail_Hydra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAR6420%2FHail_Hydra/lists"}