Documentation
Hydra has three surfaces — a CLI, an interactive TUI cockpit, and a desktop app — sitting in front of every AI model on your machine. This covers all three, the tools it plugs into, and every command: what it does, how it works, and how to use it. The deep math lives on First Principles.
Overview discover → route → observe
Hydra discovers every head on your machine, routes each task to the cheapest one that clears the bar (with automatic fallback), and logs every dispatch. One provider-neutral control plane; no single vendor is privileged.
discover route execute + observe ┌───────────┐ ┌────────────────┐ ┌──────────────┐ │ PATH scan │─┐ │ policy gate │ │ CLI heads │ claude·codex·cursor │ env keys │─┼▶│ CapScore→tier │─▶ │ API heads │ openai·gemini·groq │ port scan │─┘ │ fallback chain │ │ local heads │ ollama·lm studio └───────────┘ └────────────────┘ └──────────────┘ │ │ ~1.1µs/decision cost.jsonl · calibration · trust
install one binary, no runtime
Pure Go, single static binary.
# Homebrew (recommended) brew install ankit373/hydra/hyctl # npm · or run once, no install: npx hyctl npm install -g hyctl # pip pip install hyctl # Standalone installer curl -fsSL https://raw.githubusercontent.com/ankit373/hydra/main/install.sh | sh # From source (Go 1.22+) git clone https://github.com/ankit373/hydra.git && cd hydra go build -o hyctl ./cmd/hydra
The CLI shipped the whole interface
Everything Hydra does runs through the single hyctl binary — dispatch, discovery, trust, graph, cost. Scriptable, CI-friendly, zero daemon.
prompt → STANDARD → T5 Primary: gemini pro score 82 Fallback: openrouter score 76 ← if primary rate-limits Local: ollama/qwen3 ← always available, $0 ✔ chain resolved · nothing dispatched (dry-run)
hyctl tui shipped interactive cockpit
A terminal cockpit you operate — type a task, press enter, watch it route. Tab cycles three views. Everything below is a real hyctl tui --snapshot frame.
❯ rotate the signing key in internal/auth/token.go prompt → CORE → T1 → agy · claude blast κ=3.1 ⚠ 12 dependents → confidence bar raised to 0.95 conf 0.98 / target 0.95 · SPRT accept ✔ done · saved $0.0149 vs all-frontier CODE · go ───────────────────────────── func RotateSigningKey(ctx context.Context) error { next, err := GenerateKey() ks.Stage(next) // new key live ks.Retire(ks.Active()) // old key out return ks.Commit(ctx) }
FLEET PULSE · heads agy · claude ● up T1 ▇▁▄▃▆▄▆▃▅▅▄▆ 0.94 gemini pro ● up T5 ▂▅▂▂▇▁█▅▆▆█▄ 0.80 gemini flash ● up T8 ▆▅▁█▂▁▅▇▆▇▄▃ 0.80 qwen · local ● up T10 ▃█▂▇▅▅▅▂▇▁▁▃ 0.74 SAVED vs all-frontier $0.0149 CONFIDENCE 0.98 / 0.95 GOVERNOR · claude_pct ███████████░░░░░░ 58% band compact
AGENT TREE · supervision ownership ─ A2A ┄ orchestrator T1 cortex · you · await · 0.71 ├─ design T3 agy · claude · returned · 0.93 ▸ ├─ token-rotation T3 agy · claude · running · 0.88 │ ├─ worker-1 T6 gemini pro · returned · 0.91 │ └─ worker-2 T8 gemini flash · running · 0.62 └─ docs T10 qwen · local · returned · 0.87 ┄┄▶ A2A token-rotation → tests (files resolved +1 · context compacted)
chat + code shows the live routing decision and streams a snippet as the chosen head "writes." dashboard shows per-head sparklines, cost saved vs your priciest head, confidence, and a band-colored governor gauge. agent tree is the recursive supervision tree with A2A handoffs and ↑/↓ node inspection.
hyctl tui # Tab cycle views · ↑/↓ select tree node · : commands · :q quit hyctl tui --snapshot --view 0|1|2 # render one static frame
The desktop app design preview point-and-click cockpit
The same cockpit as a native window. Click the sidebar — the views swap live. In design; not yet shipped. Here's the direction:
How discovery works no plugins, no config
Hydra finds every head on your machine across three channels in under two seconds, scores each with a CapScore, and routes across all of them. Provider-neutral: it routes away from expensive heads, never toward a favored vendor.
PATH scan
Finds installed coding agents & CLIs — Claude Code, Codex, Cursor, Gemini CLI, Copilot and more.
Env vars
Detects keys for the major API providers and registers each as a routable head.
Port scan
Queries Ollama (11434) and LM Studio (1234) and enumerates every installed local model.
Coding agents & CLIs discovered on $PATH
Whatever agent you drive Hydra with becomes the orchestrator; the rest are interchangeable heads. Hydra shells out to each through its native executor.
API providers discovered from env keys
Set a provider's API key and it becomes a routable head automatically — through the OpenAI-compatible or provider-native HTTP executor. No config file to touch.
export ANTHROPIC_API_KEY=sk-… # then: hyctl probe # it shows up as a scored head
Local runtimes the free floor
Local models are the terminal fallback — always available, always $0, and where PII-flagged prompts are pinned so sensitive data never leaves the machine.
hyctl init first-run wizard
Scans your machine, ranks every model, and walks you through picking a Cortex (orchestrator), a local model calibrated to your real free RAM, and whether you handle sensitive data. Writes ~/.hydra/config.toml.
hyctl init
hyctl probe discover every head
Runs the three discovery channels concurrently and lists every head with its CapScore and status.
hyctl probe
hyctl status live state
Heads, budget bars, and the rate-aware governor.
Models context usage as a drifting process and estimates the first-passage probability of crossing the ceiling before the task ends — escalating before a threshold is hit.
hyctl status
hyctl dispatch the router
Routes a prompt to the cheapest head that clears the bar, with automatic fallback. The core command.
1 · classify → enum/tier · 2 · policy gate (PII can block before any network call) · 3 · select highest-CapScore available head at/under tier · 4 · execute · 5 · on failure fall down the chain to local Qwen · 6 · log tokens + cost. ~1.1µs of decision overhead.
hyctl dispatch "refactor auth to JWT refresh" hyctl dispatch --enum SIMPLE "write a User DTO" hyctl dispatch --dry-run "add pagination" hyctl dispatch --local "write unit tests"
dispatch --swarm fan out, keep the best
race (first success), best (LLM judge), or all (ranked by CapScore), with a pre-flight cost guard.
hyctl dispatch --swarm --swarm-mode best "implement a rate limiter" --swarm-max-heads 5 --swarm-max-cost 0.05 --swarm-judge-tier 1
dispatch --confidence route to a P(correct)
Sample models adaptively until a target confidence is reached, then stop.
An SPRT accumulates the calibrated log-likelihood ratio across votes and stops at the boundary implied by your target. --file raises the bar by blast radius.
hyctl dispatch --confidence 0.95 "is this migration safe for prod?"
hyctl edit safe file edits
Scoped, validated, rollback-safe single-file edit through a head.
hyctl edit --file internal/foo.go --prompt "add a nil check"
hyctl review code review
Review / approve / reject / QA a change.
hyctl review --file internal/foo.gohyctl parallel fan independent tasks
Fan a set of independent tasks across heads. Optimal count follows n*=√((1−s)/k).
hyctl parallel --tasks tasks.txthyctl trust the confidence layer
Builds and inspects the calibration behind --confidence. Each source earns a measured reliability from real outcomes.
A Beta-Bernoulli posterior over sensitivity/specificity → a per-vote LLR and a diagnostic power D (KL divergence, nats). A coin-flip source has D≈0 and is ignored. The defect-cost model prices a wrong answer and sets the required confidence.
hyctl trust calibration # per-source se / sp / D hyctl trust record --source model:claude --domain go --said-correct --outcome correct hyctl trust defect --pii --production hyctl trust stats # samples saved vs fixed-N hyctl trust explain <hash> # the LLR ledger for a run hyctl trust benchmark # measured SPRT numbers
hyctl graph blast how dangerous is this file?
Reports a file's blast radius and the confidence a change to it demands.
From graph.json it counts transitive dependents and computes κ = ⟨k²⟩/⟨k⟩ (Molloy–Reed). κ ≥ 2 ⟹ cascade-capable core ⟹ higher confidence bar.
hyctl graph blast internal/auth/token.go
hyctl graph parallel how many agents?
Returns the optimal number of parallel agents for a set of files.
Amdahl + coordination cost: minimizing T(n)=s+(1−s)/n+kn gives n*=√((1−s)/k). Independent files → ~6; coupled → ~2.
hyctl graph parallel internal/a.go internal/b.go
hyctl context entropy signal, not length
Measures context density and tells you when to compact.
ρ = |gzip(C)|/|C| proxies the entropy rate; useful = L·ρ. Compact on falling ρ, not raw length.
hyctl context entropy internal/foo.go cat notes.md | hyctl context entropy -
hyctl mcp accountability ledger
A local, append-only ledger that records — and can gate — what every agent touches.
hyctl mcp check <tool> --agent A --resource R --action write hyctl mcp log --denied # what got blocked hyctl mcp report # allowed / denied by agent & tool
hyctl oracle verify tests as evidence
Turns a verifier (tests/compile/lint) into a high-D evidence source whose verdict can outweigh a model's opinion.
hyctl oracle verify go test ./... --source verifier:go-testhyctl cost spend, honestly labeled
Reads cost.jsonl; tokens_source marks real-vs-estimated, cost_source is always estimated.
hyctl cost
hyctl stats rollup
Cost rollup by model, tier, and day — your real savings.
hyctl stats
hyctl pricing live rates
Live OpenRouter rates, cached 24h, with a static YAML fallback offline.
hyctl pricing list [filter] [--json]
hyctl pricing refreshhyctl models runtime registry
Add a model at runtime — no rebuild. Merges into ~/.hydra/models.json.
hyctl models list hyctl models add kimi-k3 --provider moonshot --cap-score 85 hyctl models sync # import the OpenRouter catalog
Tiers & CapScore how routing decides
Every head gets a CapScore (0–100); tasks route through named tiers by score. Lower tier number = stronger.
| Tier | Score | Example heads |
|---|---|---|
| expert | 90–100 | Claude Opus, Claude Code |
| complex | 80–89 | Codex, GPT-class, Gemini Pro |
| standard | 70–79 | Gemini Flash, Claude Haiku |
| simple | 60–69 | Qwen3 8B, Qwen2.5-Coder 7B |
| local | 50–59 | Llama 3.2 3B, Phi-4 Mini |
Budget governor spend attention wisely
Static pressure bands downgrade tiers as usage climbs; a rate-aware first-passage model escalates before a threshold is crossed. The terminal fallback is always the free local head.
| claude_pct | Mode | Action |
|---|---|---|
| 0–49% | normal | full orchestration |
| 50–64% | compact | compact recommended |
| 65–69% | caution | compact urgently |
| 70–74% | warning | downgrade one tier |
| 75–79% | critical | routing only |
| 80%+ | emergency | route to local, warn |
PII / local-only enforced, not conventional
With local-only policy on, any prompt containing sensitive data is blocked from leaving your machine at the dispatch layer, before any network call.
SSNs, credit cards, emails, API keys/tokens, IPs, private-key material → re-routed to a local head.
A2A handoffs causal, conflict-aware
Work passed between agents carries a vector clock for causal ordering; concurrent handoffs touching overlapping files are flagged as conflicts. Saved to logs/last_handoff.json, replayed with --a2a.
The math why the router isn't vibes
Six results run the router: Wald's SPRT, calibration diagnostic power (KL), the Bayes defect-cost bar, Molloy–Reed percolation-κ, Amdahl optimal parallelism, and context entropy — each stated, derived, and interactive.
Open First Principles — six interactive proofs →