██╗  ██╗██╗   ██╗██████╗ ██████╗  █████╗ 
    ██║  ██║╚██╗ ██╔╝██╔══██╗██╔══██╗██╔══██╗
    ███████║ ╚████╔╝ ██║  ██║██████╔╝███████║
    ██╔══██║  ╚██╔╝  ██║  ██║██╔══██╗██╔══██║
    ██║  ██║   ██║   ██████╔╝██║  ██║██║  ██║
    ╚═╝  ╚═╝   ╚═╝   ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝

The Trust Control Plane for AI Development

Route to a confidence of correctness, not just the cheapest model. One command. Every model. Provable trust.

Website · Docs · Roadmap · Issues

---

What is Hydra?

You have Claude Code for complex problems, Codex for code generation, Ollama running local models, API keys for half a dozen providers. Every prompt goes to the most expensive model because routing is manual. Sensitive data flows through third-party APIs because there is no enforcement layer. You have no idea what you're spending across all of them.

Hydra is the control plane that sits in front of all of it.

It discovers every AI model on your machine, assigns each a capability score, routes tasks to the right model by complexity and cost, enforces PII policy so sensitive data never leaves your machine, and logs every dispatch with token counts and cost — without any manual configuration.

And it's growing into a Trust Control Plane: route not just to the cheapest model, but to a target confidence of correctness — sampling models adaptively and stopping the moment you're sure enough (see Confidence Routing under Features).

brew install ankit373/hydra/hyctl && hyctl init

Pure Go, single binary. Hydra is one hyctl CLI — the legacy shell layer is gone. Everything below runs through hyctl <command>.

---

Works With

Hydra discovers and routes to all of these automatically — no plugins, no manual config:

Coding Agents & CLIs

API Providers

Local Runtimes

---

Architecture

  ┌───────────────────────────────────────────────────────────────────────┐
  │   hyctl dispatch  [--local | --swarm | --confidence 0.95]               │
  └───────────────────────────────────┬─────────────────────────────────────┘
                                       │
                     ┌─────────────────▼─────────────────┐
                     │  Policy Engine                     │  PII detection
                     │  (blocks before any network call)  │  cost ceiling · local-only
                     └─────────────────┬─────────────────┘
                                       │
                     ┌─────────────────▼─────────────────┐
                     │  Router                            │  CapScore → tier
                     │  score → tier → fallback chain     │  ~1.1 µs/dispatch
                     └───┬───────────────┬───────────────┬─┘
             single      │        swarm  │    confidence │  (SPRT)
          ┌──────────────▼┐  ┌───────────▼──┐  ┌──────────▼───────────┐
          │ best available│  │ race/best/all│  │ Trust Control Plane   │
          │ head + fallbk │  │ + LLM judge  │  │ calibration → LLR/D    │
          └──────┬────────┘  └──────┬───────┘  │ SPRT optimal-stopping  │
                 │                  │          │ defect-cost model      │
                 │                  │          └──────────┬────────────┘
                 └──────────────────┴─────────────────────┘
                                       │
              ┌────────────────────────┼────────────────────────┐
       ┌──────▼──────┐          ┌──────▼──────┐          ┌───────▼─────┐
       │  CLI Heads  │          │  API Heads  │          │ Local Heads │
       │ Claude Code │          │   OpenAI    │          │   Ollama    │
       │   Codex     │          │  Anthropic  │          │  LM Studio  │
       │  Cursor …   │          │  Groq … +12 │          │             │
       └─────────────┘          └─────────────┘          └─────────────┘
         score 60–95              score 70–95              score 50–72
                                       │
                     ┌─────────────────▼─────────────────┐
                     │  Observability                     │  cost.jsonl (est/actual)
                     │  cost + calibration + trust ledgers│  calibration.jsonl · trust.jsonl
                     └────────────────────────────────────┘

Every executor is native Go — agy, Ollama, per-provider HTTP (OpenAI-compatible + Anthropic/Gemini/Cohere/Azure/Bedrock/Replicate), and generic CLI. No shell scripts in the hot path.

---

By the Numbers

Metric	Value	How it's measured
Routing overhead	~1,130 ns / dispatch	go test -bench=BenchmarkRoutingPath (Apple M1): policy eval + head selection + budget check
Cost vs all-frontier	75–85% lower	typical coding session where most tasks are SIMPLE/STANDARD; see hyctl stats for your own numbers
Machine discovery	< 2 s for 13+ CLIs, 14 API providers, 2 local runtimes	concurrent PATH + env + port scan (hyctl probe)
Calibration convergence	a 90%-reliable source → D ≈ 1.76 nats diagnostic power	internal/trust table tests; a coin-flip source → D ≈ 0 (contributes nothing)
SPRT — easy tasks	2.6 samples, −49% vs fixed-5, 98.8% accuracy	20k seeded synthetic trials, TestSPRT_Law3
SPRT — blended workload	3.8 samples, −24% vs fixed-5, 98.2% accuracy	same suite; 71% easy / 29% hard task mix
SPRT — hard tasks	6.8 samples (adaptively more than 5), 96.7% accuracy	fixed-N ensembles can't do this — SPRT spends where accuracy demands it
Optimal parallelism	6 agents for independent work → 2 for same-subgraph edits	n* = √((1−s)/k), Law 4; k from graph coupling (internal/optimal)
Context signal density	useful tokens = length × ρ; a dense 100k window beats a noisy 1M	Law 5; ρ via gzip-ratio proxy (internal/entropy) — compact on falling ρ
Output capture	bounded at 33 MB per subprocess	internal/util.Accumulator — no unbounded buffers

Methodology & honesty. Routing overhead, discovery, calibration, and SPRT figures are measured — reproduce the SPRT numbers yourself with hyctl trust benchmark (deterministic for a fixed seed; race-clean in CI). The SPRT numbers come from synthetic trials with known ground truth, not production traffic — they validate the algorithm (Wald sequential test), and land above the continuous theoretical E[N] (easy 1.33 / blended 2.48) because real evidence arrives in discrete steps. Cost-savings ranges are workload-dependent estimates; hyctl stats reports your actual spend. As production trust.jsonl accumulates, hyctl trust stats graduates these from modeled to observed.

---

The Math

Hydra's routing decisions are not heuristics with a confident tone — each one is a named result you can check. Every equation below is either a theorem we apply or a quantity we measure, tagged so you always know which:

⊢ proven — an established theorem · ▣ measured — computed in-repo, reproducible · ◈ synthetic — seeded benchmark, known ground truth · ○ modeled — an estimate or proxy

1 · Confidence routing — Wald's Sequential Probability Ratio Test

Instead of always polling a fixed number of models, Hydra accumulates the log-likelihood ratio across votes $x_1,\dots,x_n$ and stops the instant the evidence is conclusive:

$$\Lambda_n = \sum_{i=1}^{n} \ln \frac{P(x_i \mid \text{correct})}{P(x_i \mid \text{incorrect})}, \qquad \text{accept if } \Lambda_n \ge A,\ \ \text{reject if } \Lambda_n \le B$$

$$A = \ln\frac{1-\beta}{\alpha}, \qquad B = \ln\frac{\beta}{1-\alpha}$$

for target error rates $\alpha,\beta$. Wald proved this minimizes the expected number of samples $E[N]$ among all tests with the same error bounds.

Analogy — a doctor ordering one test at a time and stopping the moment the diagnosis is certain, instead of always running the full panel. ⊢ Wald (1945), optimality proven · ◈ −24% (blended) / −49% (easy) samples vs fixed-5 at ≥98% accuracy — reproduce with hyctl trust benchmark · source: internal/trust

2 · Calibration — diagnostic power D

Every source (model or verifier) earns a sensitivity $se=P(\text{says correct}\mid\text{correct})$ and specificity $sp=P(\text{says incorrect}\mid\text{incorrect})$ from real outcomes (a Beta-Bernoulli posterior). A single vote is worth an LLR of $\ln\frac{se}{1-sp}$ (a "correct" vote) or $\ln\frac{1-se}{sp}$ (an "incorrect" vote). Its diagnostic power is the expected evidence per vote — the KL divergence between the vote distributions under the two hypotheses, in nats:

$$D = se,\ln\frac{se}{1-sp} + (1-se),\ln\frac{1-se}{sp}$$

A perfectly reliable source has large $D$; a coin-flip source ($se=sp=0.5$) has $D=0$ and contributes nothing no matter how often it votes. A 90%-reliable source gives $D\approx 1.76$ nats.

Analogy — a witness's credibility, measured in nats. A coin-flip witness tells you nothing however many times they testify. ⊢ information theory (KL divergence) · ▣ measured — the 90% → 1.76-nat figure is a table test in internal/trust

3 · When to stop — the defect-cost bar

Confidence isn't free and defects aren't equal, so the required bar is a Bayes-risk decision. The expected loss of shipping an answer believed correct with confidence $c$ is $(1-c),C_{\text{defect}}$; ship only when that clears a loss tolerance $\tau$:

$$c^\star = 1 - \frac{\tau}{C_{\text{defect}}}$$

A costlier defect ⟹ a higher confidence bar ⟹ SPRT samples more before it stops. Blast radius (§4) feeds $C_{\text{defect}}$.

Analogy — you demand far more certainty before heart surgery than before a haircut. ⊢ Bayes decision theory · ○ $C_{\text{defect}}$ is a modeled estimate (hyctl trust defect) · source: internal/trust

4 · Blast radius — Molloy–Reed percolation

Treat the code as a graph with degree mean $\langle k\rangle$ and second moment $\langle k^2\rangle$. A giant connected component — a cascade-capable core where one change can ripple everywhere — exists precisely when the Molloy–Reed criterion holds:

$$\kappa = \frac{\langle k^2 \rangle}{\langle k \rangle} \ge 2$$

Files inside a high-$\kappa$ core get their confidence bar raised: an edit to a hub everything imports must be far surer than an edit to a leaf helper.

Analogy — the epidemic threshold $R_0$: below it a change stays local; above it, one edit can infect the whole graph. ⊢ Molloy–Reed (1995), proven · ▣ computed from graph.json in internal/graph — see hyctl graph blast

5 · Optimal parallelism — Amdahl + coordination

Fanning work across $n$ agents speeds the parallel part but adds coordination cost that grows with $n$. With serial fraction $s$ and per-agent coupling $k$, wall-clock time is

$$T(n) = s + \frac{1-s}{n} + k,n \quad\xrightarrow{\ \frac{dT}{dn}=0\ }\quad n^\star = \sqrt{\frac{1-s}{k}}$$

Independent files (small $k$) → fan out to ~6 agents; tightly-coupled edits to the same subgraph (large $k$) → ~2. More is slower.

Analogy — adding cooks to a kitchen: past $n^\star$ they spend more time coordinating than cooking. ⊢ Amdahl (1967) + coordination term · ▣ $k$ derived from graph coupling in internal/optimal — see hyctl graph parallel

6 · Context governor — signal density, not length

A context window's value is its information density, not its token count. Hydra proxies the entropy rate with a compression ratio $\rho\in(0,1]$ and counts only the useful tokens:

$$\rho = \frac{\lvert \text{gzip}(C) \rvert}{\lvert C \rvert}, \qquad \text{useful tokens} = L \cdot \rho$$

Highly compressible context (repetitive, stale) has low $\rho$ and few useful tokens — so Hydra compacts on falling $\rho$, not on raw length. A dense 100k window beats a noisy 1M one.

Analogy — signal-to-noise: a short, sharp briefing beats a rambling transcript ten times its length. ⊢ Shannon source-coding (entropy rate) · ○ gzip is a proxy, not a proof — a heuristic · source: internal/entropy — see hyctl context entropy

See it move. The interactive derivations — the SPRT log-odds walk hitting its boundaries, the percolation phase transition at $\kappa=2$, the Amdahl curve with its $n^\star$ marker, and the KL overlap that is D — live on the First Principles page.

---

Features

🔍 Zero-Config Discovery

Hydra scans your machine in under two seconds. No config files to edit, no plugins to install.

$ hyctl probe

  Heads discovered (6)                           2.1s

  › claude              Claude Code         score:95  cli    ✓ ready
    codex               OpenAI Codex        score:88  cli    ✓ ready
    openai              OpenAI (API)        score:88  env    ✓ key found
    ollama/qwen3:8b     Qwen3 8B            score:66  port   ✓ running
    ollama/phi4-mini    Phi-4 Mini          score:64  port   ✓ running
    anthropic           Anthropic (API)     score:95  env    ✓ key found

Scanning happens across three channels simultaneously:

Channel	What it finds
PATH scan	13+ CLI tools — Claude Code, Codex, Cursor, Kiro, Windsurf, Gemini, Copilot, Cody, Amp, Continue, Ollama binary
Port scan	Ollama (11434), LM Studio (1234) — queries each server and lists every installed model individually
Env vars	14 API providers — Anthropic, OpenAI, Google, xAI, Groq, Together, Fireworks, Mistral, DeepSeek, Bedrock, Azure, Perplexity, Cohere, Replicate

🧠 Hardware-Aware Local Model Selection

When you have Ollama, Hydra picks the best model for your actual available memory — not your total RAM. It reads 7 days of memory usage history and uses the 75th-percentile free memory reading so the recommendation reflects how your machine actually runs under typical load, not a lucky snapshot.

  Detected: Apple Silicon · 16GB total · memory fully occupied (1.2GB free)
  ⚠  Memory tight — close other apps to run local models

  Recommended alternatives (free tiers available):

  ✓ Claude Code   Free tier via claude.ai — npm install -g @anthropic-ai/claude-code
  ✓ OpenAI Codex  Free tier — npm install -g @openai/codex
  ✓ Cursor        Free tier IDE — cursor.com

  Detected: Apple Silicon · 32GB total · 18.4GB free for models
  Based on 14 samples over 6 days · typical free: 17.8GB avg, 16.2GB p75

  ✓ Qwen2.5-Coder 32B   32B   uses ~20GB · 0.4GB left (very tight)
  ✓ Qwen3 14B           14B   uses ~10GB · 6.2GB left free
  ✓ Qwen2.5-Coder 14B   14B   uses ~10GB · 6.2GB left free
  ✓ Qwen3 8B             8B   uses ~6GB  · 10.2GB left free  ← recommended
  ✓ Qwen2.5-Coder 7B     7B   uses ~5GB  · 11.2GB left free

🔒 PII-Aware Routing (Enforced, Not Conventional)

Enable local-only policy in hyctl init and any prompt containing sensitive data is blocked from leaving your machine — at the dispatch layer, before any network call is made.

Detected patterns: Social Security Numbers, credit card numbers, email addresses, API keys and tokens, IP addresses, private key material.

$ hyctl dispatch "process payment for card 4111-1111-1111-1111"

  Policy violation: prompt contains PII (credit card pattern)
  Action: routing to local-only head

  Dispatching → ollama/qwen3:8b  [local, no API call made]

💰 Full Cost Visibility

Every dispatch is logged to ~/.hydra/cost.jsonl with model, tier, token counts, estimated cost, and fallback chain. Costs are honestly labeled: tokens_source marks whether a provider reported real usage or Hydra estimated it, and cost_source is always estimated (pricing × tokens, never a billed figure). Run hyctl cost or hyctl stats to see where your budget is going.

$ hyctl cost

  Cost — last 30 days

  Model                 Dispatches   Tokens       Est. Cost
  claude                12           48,200        $0.72
  openai                4            12,100        $0.18
  ollama/qwen3:8b       89           341,000       $0.00  (local, free)
  ─────────────────────────────────────────────────────────
  Total                 105          401,300       $0.90

  Saved vs all-Claude: ~$6.03  (87%)
  Local model share:   85%

⚡ Tier-Based Dispatch with Automatic Fallbacks

Tasks route through named tiers by capability score. If a head is unavailable, Hydra falls back automatically.

Tier	Score range	Example heads
expert	90–100	Claude Code, Claude Opus
complex	80–89	Codex, GPT-4.1, Gemini Pro
standard	70–79	Gemini Flash, Claude Haiku
simple	60–69	Qwen3 8B, Qwen2.5-Coder 7B (local)
local	50–59	Llama 3.2 3B, Phi-4 Mini

# Let Hydra pick the best available model
hyctl dispatch "refactor auth middleware to use JWT refresh tokens"

# Preview the full fallback chain before dispatching
hyctl dispatch --dry-run "write a SQL migration"
#
#   Primary:   claude (score: 95)
#   Fallback:  codex  (score: 88)  ← if claude unavailable
#   Fallback:  openai (score: 88)  ← if codex unavailable
#   Local:     ollama/qwen3:8b     ← always available

# Force local — no API calls regardless of policy
hyctl dispatch --local "write unit tests for this function"

🐝 Swarm Dispatch

Fan a single prompt out to multiple heads at once, then keep the best answer:

hyctl dispatch --swarm --swarm-mode race "prompt"   # first success wins (latency)
hyctl dispatch --swarm --swarm-mode best "prompt"   # LLM judge picks the best answer
hyctl dispatch --swarm --swarm-mode all  "prompt"   # every answer, ranked by CapScore

--swarm-max-heads, --swarm-max-cost (pre-flight cost guard), and --swarm-heads id1,id2 give you fine control over fan-out.

🧭 Confidence Routing (Trust Control Plane)

Most routers optimize cost. Hydra is growing a second axis: verified correctness. Instead of always firing a fixed number of models, --confidence runs a sequential probability ratio test (SPRT) — it samples models adaptively, in most-diagnostic-per-dollar order, and stops the moment the calibrated log-odds cross the target confidence.

hyctl dispatch --confidence 0.95 "is this migration safe to run in prod?"

It leans on per-source calibration you build from real outcomes — each model/verifier earns a measured sensitivity, specificity, and diagnostic power D. A coin-flip source (D≈0) contributes nothing; a proven one lets a single vote go a long way.

hyctl trust record --source model:claude-sonnet --domain go --said-correct --outcome correct
hyctl trust calibration          # per-source se / sp / D table
hyctl trust defect --pii --production   # modeled $ cost of shipping a wrong answer
hyctl trust stats                # samples saved vs fixed-N, achieved vs target confidence
hyctl trust explain <task_hash>  # the full LLR ledger for a past run — why it stopped

Blast-radius aware. Point Hydra at a dependency graph (graph.json from Graphify or any tree-sitter indexer) and the confidence bar scales with how much code an edit could break — a fix to a hub everything imports demands far more certainty than a leaf helper:

hyctl graph blast internal/auth/token.go        # 3 transitive dependents → demands 96.7%
hyctl dispatch --confidence 0.90 --file internal/auth/token.go "rotate the signing key"
#   graph: blast radius 3.00 → demands confidence ≥ 96.7%  (raises the 0.90 floor)

In synthetic benchmarks this cuts model calls ~49% on easy tasks and ~24% on a blended workload at ≥98% accuracy — while deliberately sampling more than a fixed swarm on genuinely hard tasks, which a fixed-N ensemble cannot do. Calibration is cold-start conservative: with no history, sources are treated as uninformative and Hydra falls back to sampling broadly.

The SPRT ensemble, calibration engine, defect-cost model, graph-aware (blast-radius) routing, the local MCP accountability ledger, and verification oracles have all shipped. A central security agent and a web dashboard are on the roadmap.

---

Comparison

	Hydra	Manual routing	LiteLLM	RouteLLM
Auto-discovers tools on your machine	✅	❌	❌	❌
Hardware-aware local model selection	✅	❌	❌	❌
PII detection + local enforcement	✅	❌	❌	❌
Fallback chains	✅	❌	✅	✅
Per-dispatch cost logging (est. vs actual labeled)	✅	❌	✅	❌
Works with CLI tools (not just APIs)	✅	✅	❌	❌
Zero config to start	✅	✅	❌	❌
Swarm dispatch (race / best / all)	✅	❌	❌	❌
Route to a confidence of correctness (SPRT)	✅	❌	❌	❌
Per-source calibration (sensitivity / specificity / D)	✅	❌	❌	❌
MCP accountability ledger	✅	❌	❌	❌
Central security agent (roadmap)	🔨	❌	❌	❌

---

Getting Started

The CLI binary is hyctl (the product is Hydra). Pick whichever fits your stack — every method installs the same prebuilt binary and verifies its checksum.

Homebrew (macOS/Linux):

brew install ankit373/hydra/hyctl

npm — or run once with no install via npx:

npm install -g hyctl      # global install
npx hyctl init            # run without installing

pip (Python 3.8+):

pip install hyctl

Standalone installer (curl):

curl -fsSL https://raw.githubusercontent.com/ankit373/hydra/main/install.sh | sh

Prebuilt binaries — download from github.com/ankit373/hydra/releases.

From source (Go 1.22+):

git clone https://github.com/ankit373/hydra.git
cd hydra
go build -o hyctl ./cmd/hydra && mv hyctl /usr/local/bin/

Not to be confused with the unrelated hydra/hydra-cli npm packages (pnxtech microservice libs) or homebrew-core's hydra (THC password cracker) — this project's CLI is hyctl.

First Run

hyctl init

The wizard scans your machine, ranks every model it finds, walks you through picking a Cortex (your main model), lets you choose a local Ollama model calibrated to your actual hardware, and asks whether you work with sensitive data that should never leave your machine. Takes about 60 seconds.

Core Commands

# Discovery & state
hyctl init                              # first-run wizard
hyctl probe                             # scan and display all available models
hyctl status                            # live system state (heads, budget bars, burn-rate risk)
hyctl tui                               # interactive cockpit — chat+code / dashboard / agent-tree (Tab cycles)

# Model registry (add a new model at runtime — no rebuild)
hyctl models list                       # built-in + your models, by capability score
hyctl models add kimi-k3 --provider moonshot --cap-score 85   # upsert into your overlay
hyctl models remove kimi-k3             # remove one of your additions
hyctl models sync                       # import the OpenRouter catalog (provisional scores)

# Dispatch
hyctl dispatch "..."           # route a prompt to the best model
hyctl dispatch --dry-run "..." # preview routing without executing
hyctl dispatch --local "..."   # local models only, no API calls
hyctl dispatch --swarm --swarm-mode best "..."   # fan out to many heads, judge best
hyctl dispatch --confidence 0.95 "..."  # SPRT: sample until this P(correct) is reached

# Cost & pricing
hyctl cost                              # spend summary (est. vs actual labeled)
hyctl stats                             # rollup by model / tier / day
hyctl pricing list                      # live $/1M-token rates (OpenRouter + fallback)

# Trust Control Plane
hyctl trust calibration                 # per-source sensitivity / specificity / D
hyctl trust record ...                  # feed an outcome to train calibration
hyctl trust defect ...                  # modeled cost of shipping a wrong answer
hyctl trust stats                       # samples saved, achieved vs target confidence
hyctl trust explain <task_hash>         # the LLR ledger for a past SPRT run
hyctl trust benchmark                   # measured SPRT numbers (samples saved, accuracy)
hyctl graph blast <file>                # a file's blast radius + the confidence it demands
hyctl graph parallel <files...>         # optimal number of parallel agents (Law 4)
hyctl context entropy <file|->          # signal density + useful tokens + compact hint

# Verification & accountability
hyctl oracle verify go test ./... --source verifier:go-test  # verifier as evidence + its LLR
hyctl mcp check <tool> --agent A --resource R --action write  # gate + record an access
hyctl mcp log --denied                  # what got blocked
hyctl mcp report                        # allowed/denied by agent and tool

# Editing & batch
hyctl edit --file ... --prompt "..."    # scoped, validated, rollback-safe file edit
hyctl review ...                        # code review / approve / reject / QA
hyctl parallel ...                      # fan independent tasks across heads

---

Configuration

~/.hydra/config.toml — written by hyctl init, editable by hand:

cortex = "claude"

[[tiers]]
name    = "expert"
heads   = ["claude", "codex"]

[[tiers]]
name    = "simple"
heads   = ["ollama/qwen3:8b"]

[[tiers]]
name    = "local"
heads   = ["ollama/phi4-mini"]

[policies.pii]
action  = "local-only"

---

Adding a Model

At runtime — no rebuild. Add any model to your local registry and Hydra picks it up on the next probe/dispatch. Additions live in an overlay at ~/.hydra/models.json and merge over the built-ins:

hyctl models add kimi-k3 --name "Kimi K3" --provider moonshot --cap-score 85
hyctl models list                 # confirm it shows up, tagged "user"
hyctl models remove kimi-k3       # remove it (built-ins can be overridden, not removed)

Built-in defaults live in internal/capabilities/data.json. To contribute a model as a shipped default, add one JSON entry — no Go code required:

{
  "id": "your-model-id",
  "name": "Your Model Name",
  "provider": "your-provider",
  "capScore": 82
}

For Ollama models, add a family pattern:

{
  "id": "family-prefix",
  "name": "Model Family Name",
  "provider": "ollama",
  "capScore": 70,
  "ollamaFamily": true
}

---

Roadmap

Feature	Status
Auto-discovery: CLI, API keys, local ports	✅ Shipped
Hardware-aware Ollama model selection	✅ Shipped
PII detection + local-only enforcement	✅ Shipped
Tier routing with automatic fallback chains	✅ Shipped
First-run TUI wizard (hyctl init)	✅ Shipped
hyctl cost / hyctl stats — spend breakdown, est. vs actual	✅ Shipped
Dynamic live pricing (OpenRouter + 24h cache)	✅ Shipped
Swarm dispatch — race / best / all + LLM judge	✅ Shipped
Per-source calibration (Beta-Bernoulli → LLR / D)	✅ Shipped
Defect-cost model (hyctl trust defect)	✅ Shipped
SPRT confidence routing (hyctl dispatch --confidence)	✅ Shipped
Graph-aware routing — blast-radius → defect cost → confidence	✅ Shipped
Optimal parallelism — n* = √((1−s)/k) from graph coupling (Law 4)	✅ Shipped
Causal A2A handoffs — vector clocks, concurrent-edit conflict detection	✅ Shipped
Context-entropy governor — compact on falling signal density, not length	✅ Shipped
MCP accountability ledger — record + gate what every agent touches	✅ Shipped
Verification oracles — tests/compile/lint as first-class evidence	✅ Shipped
Runtime model registry — hyctl models add merges a ~/.hydra/models.json overlay, no rebuild	✅ Shipped
Percolation-κ blast radius — Molloy–Reed core detection weights hub files higher	✅ Shipped
Rate-aware budget governor — first-passage-time risk on claude_pct, escalates before a threshold	✅ Shipped
MCP server registry + central security agent	📋 #9/#10
Web UI + real-time cost dashboard	📋 #11/#12

See the full Hydra Roadmap project board.

---

Project Structure

hydra/
├── cmd/hydra/                   # CLI entry point (Cobra) — every subcommand
├── internal/
│   ├── capabilities/            # Capability scoring — embedded data.json ⊕ runtime ~/.hydra/models.json overlay
│   ├── config/                  # TOML config at ~/.hydra/config.toml
│   ├── dispatch/                # Tier routing + fallback chains + policy + cost logging
│   ├── executor/                # Native executors: agy · Ollama · per-provider HTTP · CLI
│   ├── provider/                # Discovery providers (self-register via init())
│   │   ├── cli/                 # PATH scanner (13+ tools)
│   │   ├── env/                 # API key scanner (14 providers)
│   │   ├── port/                # Local server scanner (Ollama, LM Studio)
│   │   └── agy/                 # Antigravity tier registry
│   ├── probe/                   # Concurrent multi-provider discovery
│   ├── policy/                  # PII detection + local-only enforcement
│   ├── swarm/                   # Fan-out dispatch: race / best (LLM judge) / all + SPRT adapter
│   ├── trust/                   # Trust Control Plane: calibration · defect-cost · SPRT ensemble
│   ├── pricing/                 # Live cost DB (OpenRouter fetch + 24h cache + YAML fallback)
│   ├── cost/                    # cost.jsonl reader + spend summaries + source labeling
│   ├── budget/                  # Token-budget governor: 6 static pressure modes + rate-aware first-passage risk on claude_pct
│   ├── rank/                    # Deduplication + CapScore ranking
│   ├── editor/                  # Scoped, validated, rollback-safe file edits
│   ├── parallel/                # Independent multi-task fan-out
│   ├── review/                  # Code review / approve / reject / QA
│   ├── util/                    # Shared utilities (bounded Accumulator, 33 MB cap)
│   ├── sysinfo/                 # Hardware detection + 7-day memory history
│   ├── build/ · update/         # Version stamping + startup update check
│   └── tui/                     # Bubbletea init wizard + install guide
├── registry/                    # routing.yaml (the enum) · models · domains · pricing · policy
├── docs/                        # GitHub Pages (hydra.uvansa.com) — index.html, llms.txt
└── Formula/hydra.rb             # Homebrew formula (auto-updated by GoReleaser)

---

Contributing

Issues and pull requests are welcome. A few entry points:

• Add a model — at runtime, hyctl models add <id> --provider <p> --cap-score <n> (no rebuild). To ship it as a built-in default, add one entry to internal/capabilities/data.json. No Go required.
• Add a discovery provider — implement the Provider interface and call provider.Register() in an init() function.
• Add an executor — add a row to cliTemplates in internal/executor/cli.go or extend the HTTP executor for a new API schema.

See CONTRIBUTING.md for the full guide.

---

License

MIT — see LICENSE.

---

Built with Go · Bubbletea · Cobra · Lipgloss

hydra.uvansa.com