Repository navigation
Architecture
Ankit Jha edited this page May 29, 2026
·
1 revision
Hydra is structured into three physical layers:
┌─────────────────────────────────────────────────────┐
│ BRAIN — Tier 1 │
│ Claude Code CLI │
│ Classifies tasks, orchestrates heads, writes files │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ ROUTING LAYER │
│ dispatch/route.sh + dispatch/decide.sh │
│ Resolves enum → tier, checks pools, runs fallbacks │
└──────────────────────┬──────────────────────────────┘
│
┌─────────────────┼─────────────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────────┐ ┌─────────────────┐
│ Expert │ │ Standard │ │ Grunt │
│ T2 – T3 │ │ T4 – T8 │ │ T9 – T10 │
│ Claude │ │ Gemini │ │ Flash + Qwen │
│ Thinking│ │ │ │ (local Ollama) │
└─────────┘ └─────────────┘ └─────────────────┘
Read registry/domains.yaml to identify the domain and task type, then look up the enum key. Check registry/routing.yaml to resolve it to a tier number.
dispatch/route.sh --statusclaude_pct |
Action |
|---|---|
| ≥ 75% | Freeze escalations. Do not route new work to Tier 1. |
| ≥ 80% | Emergency mode — warn user, route only, no generation. |
dispatch/route.sh --enum SIMPLE --prompt "<task>" [--context <file>] [--a2a logs/last_handoff.json]route.sh handles all fallbacks automatically.
Read the output. Ask: does this compile? match conventions? solve the task?
- No → escalate one tier
- Yes → apply to disk, continue.
For output from Tiers 2–3 (Claude family), run rubber duck review using a different model family to avoid shared blind spots:
dispatch/route.sh --tier 4 --prompt "Review this for tradeoffs and blind spots:\n<output>"Skip if claude_pct ≥ 75.
cat > /tmp/hydra_handoff.json <<HEOF
{
"from": "claude-orchestrator",
"task": "<what was asked>",
"files": ["src/foo.ts"],
"context": "<key context>",
"prior_output": "<what was already done>"
}
HEOF
dispatch/route.sh --tier 6 --prompt "<next task>" --a2a /tmp/hydra_handoff.json| File | Role |
|---|---|
CLAUDE.md |
Master instructions for the Brain (Claude Code) |
AGENTS.md |
Instructions for delegated Antigravity heads |
dispatch/route.sh |
Core router — resolves enum → model, runs fallbacks |
dispatch/decide.sh |
Policy evaluator — determines edit mode and parameters |
dispatch/edit.sh |
Atomic file writer with backup and rollback |
registry/routing.yaml |
The enum file — change tier assignments here only |
registry/domains.yaml |
Domain → enum key mapping (used in Step 1) |