{"id":"5afc3910-1dac-4c0a-afb1-9a89e9bda8ec","slug":"hydra","kind":"skill","name":"hydra","summary":"Multi-perspective code review council for Claude Code. 3 advisors by default, 10 agents in deep mode (Opus + Codex). Evidence chains, adversarial self-test, dual-path verdict. Based on Karpathy's LLM","owner":"Zandereins","repoUrl":"https://github.com/Zandereins/hydra","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-03-31T14:35:21.000Z","addedAt":"2026-10-14T06:30:04.012Z","logoUrl":"https://avatars.githubusercontent.com/u/71465649?u=193fc46ba7bcb1bc66766c6855bc0cc14f86db06&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":["ai-code-review","architecture-review","claude-code","code-review","codex","cross-model","llm-council","multi-agent"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T23:21:08.284Z","sample":false,"url":"https://conduits.dev/tools/hydra","language":"Python","transports":["stdio"],"install":{"pypi":"hydra-core"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Hydra\n\n**Your code review has blind spots. Use more eyes.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-D97757)](https://docs.anthropic.com/en/docs/claude-code/skills)\n[![Agents](https://img.shields.io/badge/Agents-5_to_10-blue)](#modes)\n\nThree engineers reviewed this code. Hydra caught what they missed -- twice, from two models that never talked to each other.\n\nFour advisors review your code by default (standard mode). Escalate to deep mode\nfor six specialists, three cross-examining reviewers, and cross-model diversity.\nInspired by [Karpathy's LLM Council](https://github.com/karpathy/llm-council) --\nsame principle (independent perspectives, cross-examination, synthesis), adapted\nfor specialist code review with cross-model diversity (Claude Opus + OpenAI Codex).\n\n---\n\n## What You Get\n\n```\n## Hydra Verdict: auth-middleware-refactor\n\n**Solid refactor with one critical gap in token refresh handling.**\n**Confidence:** 82% (HIGH)\n\nThe middleware correctly centralizes auth checks, but the refresh token\nflow has a race condition under concurrent requests -- Cassandra and\nSentinel (cross-model consensus) both flagged this independently.\nMies+ identified two abstraction layers that can be collapsed.\n\n**Top Actions:**\n1. [C-1, S-3] Add mutex around token refresh in auth/middleware.ts:47-62 [effort: small]\n2. [M-1] Remove SessionValidatorFactory -- inline the 3-line check (auth/validators.ts) [effort: trivial]\n3. [C-2] Add integration test for concurrent refresh scenario [effort: medium]\n\n**Key Tensions:**\n- Navigator vs Mies+ on separating auth/authz modules. Ruling: keep combined\n  until a second consumer exists.\n\nFull report: .hydra/reports/hydra-20260331T144523-auth-middleware-refactor.md\n```\n\n**Best for:** Architecture decisions, security-critical code, refactoring tradeoffs,\npre-merge deep reviews.\n**Just ask Claude for:** Syntax fixes, factual lookups, code generation, style questions.\n\n---\n\n## How It Works\n\n```mermaid\ngraph TD\n    A[User Code + Question] --> B[Pre-flight + Context Enrichment]\n    B --> C[Frame Question]\n\n    C --> D1[Cassandra -- Opus]\n    C --> D2[\"Mies+ -- Opus (standard) / Codex (deep)\"]\n    C --> D3[\"Sentinel -- Opus (standard) / Codex (deep)\"]\n    C --> D4[Echo -- Opus]\n    C --> D5[Navigator -- Opus]\n    C --> D6[Volta -- Opus]\n\n    subgraph standard[\"Standard mode (default) -- 4 advisors, all Opus, parallel\"]\n        direction LR\n        D1\n        D2\n        D3\n        D4\n    end\n\n    subgraph deep[\"Deep mode adds -- Navigator + Volta; Mies+ & Sentinel move to Codex (sequential)\"]\n        direction LR\n        D5\n        D6\n    end\n\n    D1 & D2 & D3 & D4 & D5 & D6 --> E[All Advisor Outputs]\n\n    E --> R1[Cross-Examiner -- Opus]\n    E --> R2[Effort-Risk Ranker -- Opus]\n    E --> R3[Devil's Advocate -- Opus]\n    E -. \"--no-review\" .-> F\n\n    subgraph review[\"Cross-Examination -- standard and deep, skipped only under --no-review; each reviewer sees ALL outputs\"]\n        R1\n        R2\n        R3\n    end\n\n    R1 & R2 & R3 --> F[Chairman -- Opus]\n    F --> G[Verdict + Report]\n    G -. hydra iterate .-> B\n```\n\nIn standard mode (default), four advisors (Cassandra, Mies+, Sentinel, Echo) analyze independently on Opus, then three reviewers cross-examine all of their outputs, then a chairman synthesizes the verdict -- add `--no-review` for the fast advisors-plus-chairman path. In deep mode, six advisors run (four Opus in parallel, plus Mies+ and Sentinel on Codex sequentially) before the same three-reviewer cross-examination and chairman synthesis, adding two specialists and cross-model diversity. No advisor sees another's work, but every reviewer sees everything. After fixes, `hydra iterate` re-enters the pipeline in standard mode, producing a delta of what changed. Costs and agent counts are summarised in the [Modes](#modes) table below.\n\n---\n\n## Quick Start\n\n```bash\n# Install\ngit clone https://github.com/Zandereins/hydra.git ~/.claude/skills/hydra\n\n# Review\nhydra this: [paste code or describe decision]\n\n# Fix issues, then iterate\nhydra iterate\n```\n\nHydra asks for cost confirmation before running. Auto-detects Codex; falls back to\nOpus-only if unavailable. Iterations default to standard mode and show a\ndelta: what's fixed, what remains, what's new.\n\n**Requirements:** [Claude Code](https://claude.ai/code) (required) |\n[Codex CLI plugin](https://github.com/openai/codex-plugin-cc) (optional -- enables\ncross-model analysis, runs sequentially alongside Opus advisors)\n\n### Install as a plugin\n\nPrefer a Claude Code plugin over a skills-dir clone? Build a clean, self-contained\nplugin from the skill surface -- offline, reproducible, no dev tooling shipped:\n\n```bash\n# from a clone of this repo:\nbash scripts/build-plugin.sh                # assembles dist/hydra-plugin/ (8 files)\nclaude plugin validate dist/hydra-plugin    # offline manifest check\nclaude --plugin-dir dist/hydra-plugin       # load it into a session\n```\n\nThe build ships only `SKILL.md` + `references/` + `README`/`LICENSE` (never the dev\npackage, bench, or tests) and stamps the current commit into the plugin version.\nFree-text triggers (`hydra this`, `hydra review`, ...) fire exactly as with the\nskills-dir install.\n\n---\n\n## The Advisors\n\nStandard mode uses 4 advisors (Cassandra, Mies+, Sentinel, Echo), all on Claude Opus.\nDeep mode adds Navigator and Volta for the full 6 and runs two of them (Mies+, Sentinel)\non OpenAI Codex -- different model, different blind spots. When Opus and Codex\nindependently agree, that's the strongest signal. When they disagree, that's the\nhighest-value finding.\n\nEach finding gets a unique ID (e.g., C-1 for Cassandra's first finding, M-2 for\nMies+'s second). Top Actions reference these IDs so you can trace any recommendation\nback to the advisor who raised it.\n\n| # | Name | Model | Core Question |\n|---|------|-------|---------------|\n| 1 | Cassandra | Opus | \"How does this break at 3am?\" -- compound failures, unguarded assumptions |\n| 2 | Mies+ | Opus / Codex | \"What can be removed, and can a stranger follow it?\" -- dead code, over-engineering, readability |\n| 3 | Navigator | Opus | \"What depends on what?\" -- coupling, boundary violations |\n| 4 | Volta | Opus | \"What does this cost at 10x load?\" -- N+1 queries, invisible costs |\n| 5 | Sentinel | Opus / Codex | \"How do I break this on purpose?\" -- auth gaps, injection, race conditions |\n| 6 | Echo | Opus | \"What did the AI get wrong?\" -- phantom code, fake tests, plan-vs-diff drift |\n\nMies+ uses a few-shot prompt format for Codex compatibility (deep mode). Top Actions\ninclude effort tags (`[effort: trivial]`, `[effort: small]`, `[effort: medium]`,\n`[effort: large]`) ranked by the Effort-Risk Ranker reviewer.\n\nAdvisors run in parallel (Opus) and sequentially (Codex), then 3 peer reviewers\ncross-examine their work (all Opus), then a chairman (Opus) synthesizes the final\nverdict.\n\n---\n\n## Modes\n\n<!-- These figures mirror SKILL.md, which is authoritative -- update it first, then here.\n     Both sides are pinned by tests/unit/test_prompt_surface.py, which also forbids a bare `$`\n     before a digit (the skill loader would expand it as a positional argument). -->\n\n| Mode | CLI | Agents | Est. Cost |\n|------|-----|--------|-----------|\n| **standard** *(default)* | -- | 8 (4 advisors + 3 reviewers + chairman) | around USD 0.70-1.20 |\n| **standard --no-review** | `--no-review` | 5 (4 advisors + chairman) | around USD 0.35-0.65 |\n| **deep** | `--mode deep` | 10 (6 advisors + 3 reviewers + chairman) | around USD 1.50-2.50 |\n\n**Modifiers** (combinable with either mode):\n- `--no-codex` -- Codex advisors run on Opus instead\n- `--no-review` -- skip peer review (standard: 8 to 5 agents, the fast path around USD 0.35-0.65; deep: 10 to 7 agents, around USD 1.00)\n- `--transcript` -- save raw agent outputs separately\n\n**Focus flags:** `--focus security|perf|readability|architecture|reliability` -- includes the mapped advisor and prioritizes matching files in the diff budget (not a word-budget or weighting multiplier). Mapping: security to Sentinel, perf to Volta, readability to Mies+, architecture to Navigator, reliability to Cassandra. Flags for `perf` and `architecture` auto-escalate to deep mode (those advisors only exist in deep).\n\nCosts are API calls to Claude and Codex, charged to your own accounts. Hydra always\nshows the estimate and asks before running.\n\n---\n\n## Auto-Mode\n\nLet Hydra analyze your question and recommend the right mode:\n\n```\nhydra ?    # analyze your question, recommend a mode\nhydra auto # same\n```\n\n---\n\n## Post-Review Actions\n\nAfter a Hydra verdict, act on findings directly:\n\n```\nfix #1       # implement Top Action #1 directly\nfix #2       # implement Top Action #2\nhydra iterate # re-review after fixes\n```\n\n---\n\n## Branch Review\n\nReview all changes on the current branch compared to main:\n\n```\nhydra branch   # review current branch vs main\n```\n\n---\n\n## PR Review\n\nLike `hydra branch`, but Hydra also ingests the pull request's title and description --\nso Echo can check the diff against the PR's stated intent (plan-vs-diff drift, scope creep):\n\n```\nhydra pr   # review branch diff + the PR's title/description\n```\n\nHydra reads the PR via `gh pr view` (read-only). The title and body are **untrusted data** --\nsecrets-scanned and treated as content, never as instructions; an injected directive in a PR\nbody becomes a finding, not a command. If `gh` is unavailable, unauthenticated, or no PR is\nassociated with the branch, Hydra falls back to `hydra branch` and Echo's plan-vs-diff checks\nstay inactive (normal, not an error).\n\n---\n\n## Iterate\n\nHydra reviews aren't one-shot. Fix the issues, then run `hydra iterate` to verify:\n\n```\n## Hydra Delta: auth-middleware-refactor\n\n**Progress: 2/3 previous actions addressed**\n\n**Fixed:** Mutex added around token refresh. SessionValidatorFactory removed.\n**Remaining:** Integration test for concurrent refresh not yet added.\n**New Issues:** None.\n\n**Next Step:** Add test in auth/__tests__/refresh.test.ts\n```\n\nIterations auto-detect the last report, diff only what changed, and default to\nstandard mode. Run as many cycles as needed (see the [Modes](#modes) table for cost).\n\nTriggers: `hydra iterate`, `hydra re-review`, `hydra follow-up`, `check my fixes`.\n\n---\n\n## Privacy\n\nIn deep mode, your code is sent to both Anthropic (Claude Opus) and OpenAI\n(Codex GPT-5.4); standard mode is Opus-only (Anthropic only). Use `--no-codex` to\nkeep deep mode Anthropic-only as well. Hydra shows which providers receive your code\nand asks for confirmation before any agents run.\n\nWithout the Codex plugin, Hydra runs all advisors on Opus. In standard mode that is\n4 advisors + 3 reviewers + chairman (8 agents). In deep mode, all 6 advisors + 3 reviewers\n+ chairman (10 agents). Same perspectives -- just without cross-model diversity.\n\n---\n\n## When NOT to Use Hydra\n\nHydra spawns 5-10 agents. Use it for decisions that benefit from multiple\nperspectives -- not everything.\n\n**Just ask Claude directly for:** syntax fixes, single-file refactors, code generation,\nfactual lookups, style questions, simple bug fixes with obvious root causes.\n\n**Use Hydra for:** architecture decisions with real tradeoffs, security-critical code,\ncomplex refactoring, pre-merge reviews, \"I've been staring at this for hours\" situations,\ncode where mistakes have high cost (payments, auth, data migration).\n\n**Rule of thumb:** If you can describe the change in one sentence and the approach is\nobvious, you don't need Hydra.\n\n---\n\n## Troubleshooting\n\n**\"Codex script not found\"** -- Hydra auto-switches to Opus-only. All 6 perspectives\nstill run. Install the [Codex CLI plugin](https://github.com/openai/codex-plugin-cc)\nfor cross-model analysis.\n\n**Codex advisors timing out** -- Fixed. Codex tasks now run sequentially\n(the codex-companion CLI allows only one active task per workspace). If Codex\nstill fails, Hydra auto-switches to Opus-only. Use `--no-codex` to skip Codex entirely.\n\n**\"Codex circuit breaker open\"** -- Hydra detected 2+ consecutive Codex failures\nand switched to Opus-only for the rest of the session. This is automatic --\nyour review continues without interruption.\n\n**\"ABORTED: 0/N advisors responded\"** -- API key or network issue. Verify Claude access\nworks outside Hydra.\n\n**Unexpected activation** -- Type `n` at the cost confirmation. Hydra always asks before\nspawning agents.\n\n---\n\n## FAQ\n\n**How much does it cost?** Standard: around USD 0.70-1.20 (the fast `--no-review` path is around\nUSD 0.35-0.65). Deep: around USD 1.50-2.50. These are API costs charged to your accounts. Hydra shows\nestimates before running.\n\n**Where are reports?** `.hydra/reports/` in your project root (gitignored). Run\n`hydra history` to list past reviews.\n\n**Without Codex?** All 6 advisors run on Opus (10 agents total with 3 reviewers).\nSame perspectives, no cross-model signal. Use `--no-codex` to keep code Anthropic-only.\n\n**How do iterations work?** Fix issues, run `hydra iterate`. Hydra diffs what changed,\ndefaults to standard mode, shows a delta: fixed / remaining / new.\n\n**How many reviewers?** 3 reviewers (Cross-Examiner, Effort-Risk Ranker,\nDevil's Advocate), all running on Opus.\n\n---\n\n## License\n\nMIT\n"}