🐉 H Y D R A

Multi-Headed Speculative Execution for AI Coding CLIs
_{Claude Code  ·  Gemini CLI  ·  Codex CLI}

"Cut off one head, two more shall take its place."
Except here — every head is doing your work faster and cheaper.

10 agents  ·  10 commands  ·  6 hooks  ·  3 host CLIs  ·  Codebase map  ·  Real token tracking  ·  Persistent memory

---

🧬 What is Hydra?

Hydra is a curated multi-agent toolkit for AI coding CLIs — Claude Code, Gemini CLI, and Codex CLI. It ships 10 specialized agents pinned to each host's cost-effective models (Haiku/Sonnet on Claude Code, Flash tiers on Gemini, Luna/Terra on Codex), 10 commands for direct invocation, and one automatic touchpoint that recommends integration verification after substantial code changes.

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

Think of it this way:

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.

New in v2.5.0 — Multi-Host: One canonical source (content/) now generates a native payload per host. Gemini CLI and Codex CLI join Claude Code as first-class hosts — same 10 agents and 10 commands, pinned to each host's own model tiers, with per-host hooks and real token tracking. Invoke with /hydra:* on Claude Code and Gemini CLI, or $hydra-* skills on Codex CLI.

Everything else Hydra is known for is still here: persistent agent memory, the codebase map with blast-radius lookups, the sentinel verification touchpoint after substantial edits, internal-thinking compression (/hydra:stfu), and real token tracking with /hydra:stats. Full version history lives in the CHANGELOG.

When to Use Hydra Explicitly

Hydra's biggest cost savings come from explicit invocation in scenarios where specialized handling genuinely helps:

Scenario	How to Invoke	Why It Saves
Broad codebase exploration	"use hydra-scout to find X"	Haiku reads files faster and cheaper than Opus
Multi-file changes	"use hydra-coder to update X across these files"	Parallel Sonnet dispatch beats sequential Opus
Security review	/hydra:guard	Pattern matching is Haiku-cheap
Environment validation	/hydra:preflight	Cross-references compatibility matrices on Sonnet
Codebase architecture review	/hydra:map	Dependency graph stored locally

For 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 below.

---

🚀 Installation

One command. Done.

npx hail-hydra-cc@latest

Runs the interactive installer — pick your CLI(s) (Claude Code, Gemini CLI, Codex CLI) and scope, and it deploys the agents, commands, hooks, and per-host wiring. Done in seconds.

Installation Options

# Claude Code, all projects — no prompts (v2-compatible default)
npx hail-hydra-cc --global

# Pick your agent(s) explicitly
npx hail-hydra-cc --agent=claude --global
npx hail-hydra-cc --gemini --global
npx hail-hydra-cc --codex --global
npx hail-hydra-cc --agent=claude,gemini,codex --global

# Every detected agent, fully non-interactive
npx hail-hydra-cc --all --global --yes

# This project only / both scopes
npx hail-hydra-cc --claude --local
npx hail-hydra-cc --claude --both

# Preview what would be written (writes nothing)
npx hail-hydra-cc --dry-run --all

# Check what's deployed
npx hail-hydra-cc --status

# Remove everything
npx hail-hydra-cc --uninstall

All flags: --agent=<list> (claude,gemini,codex) or the aliases --claude / --gemini / --codex / --all (every detected agent) · scope --global / --local / --both · --yes non-interactive (requires an agent selection) · --dry-run · --config-dir <path> config-dir override (single agent only) · --status · --uninstall.

Per-Host Invocation

Host	Commands	Notes
Claude Code	/hydra:help, /hydra:stats, …	StatusLine + hooks registered in ~/.claude/settings.json
Gemini CLI	/hydra:help, /hydra:stats, …	Restart Gemini CLI (or run /commands reload) to pick up the new commands
Codex CLI	$hydra-help, $hydra-stats, … (skills with a $ trigger)	Required once: run /hooks inside Codex to review and trust the Hydra hooks — they stay inert until then

What Gets Installed

Claude Code — ~/.claude/ (or ./.claude/ with --local):

~/.claude/
├── agents/                      # 10 agent definitions (Haiku/Sonnet pinned, memory: project)
├── commands/hydra/              # 11 slash commands (/hydra:*)
├── hooks/                       # 6 hook scripts + notification sound
│   ├── hydra-check-update.js    # SessionStart — version check (background)
│   ├── hydra-statusline.js      # StatusLine — status bar display
│   ├── hydra-token-math.js      # Token parsing + savings math (shared library)
│   ├── hydra-auto-guard.js      # PostToolUse — file change tracker
│   ├── hydra-notify.js          # Notification — task completion sound
│   ├── hydra-sentinel-done.js   # Sentinel tracking cleanup
│   └── hydra-task-complete.wav  # Notification sound file
└── skills/
    ├── hydra/                   # SKILL.md + VERSION + references/
    └── stfu-agents/             # SKILL.md

Hooks and the statusLine are registered in ~/.claude/settings.json — existing entries are preserved, and a custom statusLine is never overwritten.

Gemini CLI — ~/.gemini/ (or ./.gemini/ with --local):

~/.gemini/
├── agents/                      # 10 agent definitions (Flash-tier pinned)
├── commands/hydra/              # 11 TOML commands (/hydra:*)
├── hydra/                       # SKILL.md, VERSION, references/, hooks/
└── GEMINI.md                    # Hydra marker block (appended, reversible)

Hooks (AfterTool, SessionStart, Notification) are registered in ~/.gemini/settings.json.

Codex CLI — ~/.codex/ (or ./.codex/ with --local):

~/.codex/
├── agents/                      # 10 agent definitions (*.toml, Luna/Terra pinned)
├── hydra/                       # VERSION, references/, hooks/
├── hooks.json                   # Hook registrations — trust once via /hooks
├── config.toml                  # [features] hooks + notify chain (marker blocks, reversible)
└── AGENTS.md                    # Hydra marker block (appended, reversible)
~/.agents/skills/                # Skills: $hydra-help, $hydra-stats, $hydra-guard, …

Local scope (--local): the per-project payload goes to ./.claude/, ./.gemini/, or ./.codex/ in your working directory. Hooks and host wiring (settings/hooks registration, context files, Codex skills) always stay user-level.

---

⚡ Slash Commands

Codex CLI: the same commands ship as skills invoked with a $ trigger — $hydra-help, $hydra-stats, $hydra-guard, … The /hydra:* form below is for Claude Code and Gemini CLI.

Command	Description
/hydra:help	Show all commands and agents
/hydra:status	Show installed agents, version, and update availability
/hydra:update	Update Hydra to the latest version
/hydra:guard [files]	Run manual security & quality scan
/hydra:quiet	Suppress dispatch logs for this session
/hydra:report	Report a bug, request a feature, or share feedback
/hydra:stfu	Compress internal thinking for every subagent in the session
/hydra:map	View codebase dependency map, query blast radius, rebuild
/hydra:preflight	Two-phase environment and compatibility check before starting a new project build
/hydra:stats	Show real token usage, delegation rate, and actual savings (parses the host CLI's own session logs — no AI estimation)

/hydra:preflight — Environment Validation

Run before starting any new project build. Catches broken GPU stacks, missing env vars, and incompatible dependency pairs before they cost you hours of debugging.

/hydra:preflight

Hydra runs a two-phase check:

1. Detection (Haiku): probes runtimes, CUDA stack, deps, env vars, services
2. Analysis (Sonnet): cross-references against compatibility matrices, flags ✅ COMPATIBLE / ⚠️ KNOWN RISK / ❌ CONFIRMED BREAK

---

🖥️ Status Line

Claude Code only — Gemini CLI and Codex CLI have no statusline; use /hydra:stats (or $hydra-stats) there instead.

After installation, your Claude Code status bar shows real-time framework info:

🐉 │ Opus │ Ctx: 37% ████░░░░░░ │ $0.42 │ my-project

Element	What It Shows
🐉	Hydra is active
Model	Current Claude model (Opus, Sonnet, Haiku)
Ctx: XX%	Context window usage with visual bar
$X.XX	Session API cost so far
Directory	Current working directory
⚠ Warning	Compaction warning (only at 70%+ context usage)

Context bar colors:

• 🟢 Green (0–49%) — plenty of room
• 🟡 Yellow (50–79%) — getting full, consider /compact
• 🔴 Red (80%+) — context nearly full, /compact or /clear recommended

Compaction warnings (appended automatically at 70%+):

🐉 │ Opus │ Ctx: 73% ███████░░░ │ $1.87 │ my-project │ ⚠ Auto-compact at 85%
🐉 │ Opus │ Ctx: 83% ████████░░ │ $3.14 │ my-project │ ⚠ Compacting soon!

• ⚠ Auto-compact at 85% (70–79%) — heads-up that compaction is approaching
• ⚠ Compacting soon! (80%+) — compaction is imminent, consider /compact now

Note: If you already have a custom statusLine configured, the installer keeps yours and prints instructions for switching to Hydra's.

---

🔔 Task Completion Sound

Hydra plays a short notification sound when the CLI finishes responding — so you know it's done even if you've tabbed away.

• Cross-platform — macOS (afplay), Windows (PowerShell), Linux (paplay/aplay)
• Non-blocking — the sound plays detached; it never delays the response
• Host-native and fully event-driven — Claude Code Stop hook, Gemini Notification hook, Codex notify chain that preserves your existing notifier; no prompt-level calls, so the model can't forget it

The notification hook is registered automatically during installation.

---

🔄 Auto-Update Notifications

Hydra checks for updates once per session in the background (never blocks startup). When a new version is available, you'll see it in the status bar:

🐉 │ Opus │ Ctx: 37% ████░░░░░░ │ $0.42 │ my-project │ ⚡ v2.6.0 available

Update with:

# From within Claude Code:
/hydra:update

# Or from your terminal:
npx hail-hydra-cc@latest --global

After updating, restart Claude Code to load the new files.

---

✨ Features

• Ten specialized heads — Haiku (fast) and Sonnet (capable) heads for every task type, including preflight detection for new projects
• Sentinel integration integrity — Two-tier verification (fast scan + deep analysis) catches ~72% of integration bugs before runtime
• Persistent agent memory — Every agent remembers your codebase patterns, conventions, and past decisions across sessions
• Orchestrator memory — Opus maintains its own notes on fragile zones, routing patterns, and known issues via CLAUDE.md
• Verification touchpoint — after substantial code changes, the auto-guard hook injects a directive recommending a sentinel + guard verification wave before results are presented; trivial edits stay silent
• Auto-Guard — a PostToolUse hook tracks every file edit; hydra-guard (Haiku) scans the tracked files for security issues on demand (/hydra:guard) or as part of the sentinel wave
• Configurable modes — conservative, balanced (default), or aggressive delegation via hydra.config.md
• Slash commands — /hydra:help, /hydra:status, /hydra:update, /hydra:guard, /hydra:quiet, /hydra:report for full session control
• Task completion sound — plays a notification when Claude finishes substantial tasks
• Quick commands — natural language shortcuts: hydra status, hydra quiet, hydra map
• Custom agent templates — Add your own heads using templates/custom-agent.md
• Session indexing — Codebase context persists across turns; no re-exploration on every prompt
• Speculative pre-dispatch — hydra-scout launches in parallel with task classification, saving 2–3 seconds per task
• Dispatch log — Transparent audit trail showing which agents ran, what model, and outcome
• 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.
• Risk-Based Verification — Files with more dependents get more thorough verification. Critical files always trigger deep sentinel analysis. Low-risk files get fast-tracked.
• /hydra:map — Inspect the dependency map, query blast radius for any file, or force a rebuild
• 🆕 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.
• 🆕 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.

---

🛡️ Sentinel — Integration Integrity

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

hydra-sentinel catches them — the auto-guard touchpoint recommends a scan after every substantial edit, and the scan escalates to deep analysis only when it finds something.

How It Works

Code change lands (hydra-coder finishes)
    │
    ▼
┌──────────────────────────────────────┐
│  🟢 hydra-sentinel-scan (Haiku)  │  ← Runs on EVERY code change (~1-2s)
│  Fast sweep: imports, exports,       │
│  signatures, dependencies            │
└──────────────┬───────────────────────┘
               │
          Issues found?
          ├── No:  ✅ Pass — code proceeds to guard
          │
          └── Yes: Escalate
               │
               ▼
┌──────────────────────────────────────┐
│  🔵 hydra-sentinel (Sonnet)      │  ← Only when scan flags issues (~20-30%)
│  Deep analysis: confirms real issues, │
│  dismisses false positives,          │
│  proposes fixes                      │
└──────────────┬───────────────────────┘
               │
          Fix decision:
          ├── Trivial (import typo): Auto-fix
          ├── Medium (signature mismatch): Offer fix to user
          └── Complex (architectural): Report with context

What Sentinel Catches

Check Type	Priority	Example
Import/export mismatches	P0	Importing a function that was renamed or removed
Function signature changes	P0	Caller passes 2 args, function now expects 3
Type contract violations	P1	Function returns string but caller expects number
Missing dependency updates	P1	New import added but package not in package.json
Cross-file rename gaps	P1	Variable renamed in definition but not all call sites
Circular dependency introduction	P2	New import creates A → B → C → A cycle
Dead code from refactoring	P2	Exported function no longer imported anywhere
Environment/config mismatches	P2	Code references env var that isn't in .env.example

Example Output

🛡️ Sentinel Report
──────────────────────────────────────
✖ P0: src/auth.js imports `validateToken` from src/utils.js
       but src/utils.js now exports `verifyToken` (renamed in this session)
       → Fix: Update import to `verifyToken` [auto-fixable]

⚠ P1: src/api/routes.js calls createUser(name, email)
       but src/models/user.js:createUser now expects (name, email, role)
       → Missing required parameter `role` added in this change

✔ 6 other integration points verified clean
──────────────────────────────────────

Across the check types above, the estimated weighted detection rate is ~72% of integration bugs caught before runtime — highest for import/export and dependency mismatches (direct matching), lower for type contracts and config drift (heuristic).

Memory makes it better over time. Sentinel remembers past false positives and known fragile integration points in your project. The more you use it, the more accurate it gets.

---

🗺️ Codebase Map

Hydra builds a persistent dependency map of your codebase, giving every agent instant access to file relationships without scanning.

How It Works

hydra-scout builds the map on first run by extracting import statements from every source file using grep (no external parsers required). The map is stored at .claude/hydra/codebase-map.json.

Session 1: scout builds the full map (~10 seconds for 500 files)
Session 2: scout checks git hash → nothing changed → skip rebuild (instant)
Session 3: scout checks git hash → 3 files changed → update only those 3

What the Map Contains

Data	How It's Used
File imports	"auth.ts imports user.ts and env.ts"
Reverse imports	"auth.ts is imported by users.ts, admin.ts, middleware.ts"
Risk score	low (0-1 deps) → medium (2-3) → high (4-6) → critical (7+)
Env var index	"JWT_SECRET is used in auth.ts and middleware.ts"
Test coverage	covered / partial / untested per file
Git staleness	Hash comparison for instant freshness check

Why This Matters

Without map — When auth.ts changes, sentinel greps the ENTIRE codebase looking for files that import it. In a 500-file project, that's 500 file reads. Takes 5-15 seconds, costs 3,000-8,000 tokens.

With map — Sentinel reads the JSON, looks up auth.ts's imported_by array, gets [users.ts, admin.ts, middleware.ts] instantly. Reads only those 3 files. Takes <2 seconds, costs 500-1,500 tokens.

Savings: 3-5× faster, 3-5× fewer tokens per sentinel scan.

Risk-Based Sentinel Triggering

The map's risk scores let Opus make smarter verification decisions:

Modified File Risk	What Happens
🔴 Critical (7+ deps)	Sentinel-scan + deep analysis (always)
🟠 High (4-6 deps)	Sentinel-scan, escalate if issues found
🟡 Medium (2-3 deps)	Sentinel-scan, escalate only for P0 issues
🟢 Low (0-1 deps)	Sentinel-scan, auto-accept if clean

This means Hydra spends more verification effort where it matters most (high-risk files) and less where it doesn't (isolated utilities).

Inspect the Map

/hydra:map                       # Show summary — risk distribution, coverage stats
/hydra:map src/services/auth.ts  # Show blast radius for a specific file
/hydra:map rebuild               # Force a complete rebuild

Technical Notes

• The map is built using grep + regex — no Tree-sitter, no AST parsing, no external dependencies. Works with JS/TS, Python, Go, Java, Kotlin, Ruby, Rust.
• Supports relative import resolution (e.g., './auth' → src/services/auth.ts)
• Falls back gracefully — if the map doesn't exist, all agents use their original grep-based behavior. The map is an optimization, not a requirement.
• Stored at .claude/hydra/codebase-map.json — add to .gitignore (machine-generated).

---

📊 Real Token Tracking

/hydra:stats shows actual token usage and savings for your session. No AI estimation. The numbers are pulled directly from the host CLI's own session logs — Claude Code JSONL, Gemini CLI chat records, or Codex CLI rollout files.

🐉 Hydra Stats
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session: 7c3a9e21.jsonl
Turns:   38
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🟢 Haiku  (24 turns):  142.3k in / 8.1k out  → $0.183
🔵 Sonnet (9 turns):   67.4k in / 3.2k out   → $0.250
🟣 Opus   (5 turns):   45.1k in / 2.8k out   → $0.296
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Delegation rate:    87.0% (33/38 turns)
Actual cost:        $0.729
All-Opus baseline:  $1.502
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💰 Saved:           $0.773 (51.5%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Reads the host CLI's session logs directly.
No AI estimation. Numbers are real.

The "All-Opus baseline" is the hypothetical cost if every Hydra agent had been Opus instead. The savings show what Hydra's model routing actually saves you in this session. Implementation is pure Node.js — works on Windows, macOS, and Linux. Respects CLAUDE_CONFIG_DIR env override.

---

🧠 Agent Memory

Without memory, every session starts cold. Agents re-discover your conventions, re-learn your project structure, and repeat the same questions. With memory, knowledge compounds.

Aspect	Without Memory	With Memory
First task	Agent explores from scratch	Agent recalls project patterns
Conventions	May use wrong style	Remembers your naming, structure, patterns
Known issues	No awareness of past bugs	Recalls fragile areas and past fixes
Routing accuracy	Generic classification	Improved by past dispatch outcomes
False positives	Same false alarms repeat	Sentinel suppresses known non-issues

How It Works

Every agent has memory: project in its frontmatter. Claude Code automatically manages a per-project memory directory (.claude/memory/) where agents store and retrieve learnings.

Agent memory is a Claude Code feature — Gemini CLI and Codex CLI have no equivalent, so the generator drops the