Hydra

Multi-Agent AI Orchestrator for Gemini, Codex, and Claude.

Status: Active development. APIs may change between releases.

   \\ | //
    \\|//
   _\\|//_
  |  \|/  |
  |  /|\  |
  \_/ | \_/
    |   |
    |___|

  H Y D R A

Hydra coordinates three AI coding agents — Gemini CLI, Codex CLI, and Claude Code — through a shared HTTP daemon with a task queue, intelligent routing, and structured multi-round deliberation.

Each AI coding agent has strengths: Claude is a strong architect, Gemini excels at analysis and critique, Codex is a fast implementer. Running them individually means choosing one perspective per task.

Hydra lets you use all three together:

• Route work to the right agent — a local heuristic classifies your prompt and picks the best agent (or pair, or all three) with zero extra API calls
• Run agents in parallel — headless workers claim tasks from a shared queue and execute concurrently in isolated git worktrees
• Multi-round deliberation — Claude proposes, Gemini critiques, Claude refines, Codex implements
• Self-improving pipelines — nightly automation scans your codebase for TODOs, issues, and improvements, then executes them autonomously with budget tracking and self-healing on failures

• Node.js 20+
• PowerShell 7+ (for Windows launchers; Linux/macOS can run the Node modules directly)
• At least one AI CLI installed: gemini, codex, or claude
• Optional: gh CLI for GitHub integration (PRs, issue scanning)
• Optional: @opentelemetry/api for distributed tracing

# Clone and install
git clone https://github.com/PrimeLocus/Hydra.git
cd Hydra
npm install

# Launch the operator console
node lib/hydra-operator.mjs

# Or on Windows with PowerShell launchers:
pwsh -File .\bin\install-hydra-cli.ps1   # one-time: adds 'hydra' command
hydra                                     # operator console
hydra --full                              # daemon + agent heads + operator

Once in the operator console, type a prompt and Hydra routes it automatically. Use :help to see all commands.

After installing Hydra, register its MCP server with your AI CLIs:

hydra setup

This detects installed CLIs (Claude Code, Gemini CLI, Codex CLI) and registers the Hydra MCP server globally. New CLI sessions will have access to Hydra coordination tools (hydra_ask, hydra_tasks_claim, hydra_status, etc.).

To make a project Hydra-aware (generates per-agent coordination instructions):

cd /path/to/your/project
hydra init

To remove the MCP registration:

hydra setup --uninstall

                    +-----------+
                    |  Operator |  (interactive REPL)
                    +-----+-----+
                          |
                 +--------+--------+
                 |                 |
           +-----v-----+    +------v----+
           | Concierge |    |  Workers  |
           | (chat AI) |    | (headless)|
           +-----+-----+    +------+----+
                 |                 |
                 +--------+--------+
                          |
                    +-----v-----+
                    |   Daemon  |  (HTTP state + events)
                    +--+--+--+--+
                       |  |  |
          +------------+  |  +-----------+
          v               v              v
     +---------+    +-----------+    +--------+
     | Gemini  |    |  OpenAI   |    | Claude |
     | (3 Pro) |    | (GPT-5.4) |    | (Opus) |
     +---------+    +-----------+    +--------+
       Analyst       Implementer      Architect

  Concierge: OpenAI → Anthropic → Google fallback chain
  Sub-agents: security-reviewer, test-writer, doc-generator,
              researcher, evolve-researcher (virtual → physical)

• Five orchestration modes: Auto (3-way routing), Council (multi-round deliberation with structured synthesis), Dispatch (headless pipeline), Smart (auto-tier per complexity), Chat (concierge conversation)
• Intelligent route classification: Local heuristic classifies prompts into single/tandem/council routes — zero agent CLI calls for routing
• Tandem dispatch: 2-agent lead-follow pairs (e.g., Claude analyzes, Codex implements)
• Affinity-based task routing: 10 task types across 3 agents with adaptive learning from outcomes
• Virtual sub-agents: Role-specialized agents (security-reviewer, test-writer, doc-generator, researcher) that resolve to physical agents

• Multi-provider front-end: Conversational AI (OpenAI → Anthropic → Google fallback) — answers questions directly, escalates to agents when real work is needed
• Situational awareness: "What's going on?" fetches real-time activity from daemon and agents
• Codebase knowledge: "How does dispatch work?" injects architecture context from docs and knowledge base
• Command-aware: Fuzzy matching catches typos before falling back to AI suggestions

• Per-agent model switching: Trade quality for speed/cost at runtime
• Interactive model picker: Type-to-filter browser with reasoning effort configuration
• Headless workers: Background agent execution with claim-execute-report loop
• Agent Forge: Multi-model agent creation pipeline — Gemini analyzes, Claude designs, Gemini critiques, Claude refines, optional live test

• Token usage monitoring: Three-tier budget tracking (weekly, daily, sliding window) with auto model-switching at critical levels
• Model recovery: Automatic fallback when a model is unavailable or rate-limited
• Rate limit resilience: Exponential backoff with jitter across all providers
• Failure doctor: Diagnoses pipeline failures, detects recurring patterns, auto-creates follow-up tasks
• Circuit breaker: Per-model failure tracking with automatic recovery after cool-down
• 5-line status bar: Persistent terminal footer with agent activity, token gauge, and event ticker

• Nightly runner: Scans TODO comments, docs/TODO.md, and GitHub issues → prioritizes → executes autonomously with budget tracking
• Evolve: 7-phase autonomous self-improvement with investigator self-healing and knowledge accumulation
• Tasks runner: Per-task branch isolation, council-lite review for complex tasks, JSON + Markdown reports
• AI discovery: Agent analyzes codebase and suggests improvement tasks
• Commit attribution: Automated commits include Originated-By: and Executed-By: git trailers

• Event-sourced daemon: HTTP state management with replay, snapshots, and dead-letter queue
• Git worktree isolation: Per-task isolated filesystems for parallel agent work
• MCP server: 11 tools, 5 resources, 3 prompts via official SDK (protocol 2025-03-26)
• Streaming middleware: Composable pipeline — rate limiting, circuit breaking, retry, telemetry
• OTel tracing: Optional distributed tracing with GenAI semantic conventions
• Heartbeat crash recovery: Daemon detects stale workers and requeues or dead-letters tasks

Hydra is configured via hydra.config.json in the project root. Key sections:

See docs/USAGE.md for full configuration reference.

• Installation Guide
• Usage & Commands
• Architecture
• Model Profiles
• Contributing

The HTTP daemon binds to 127.0.0.1 (localhost only) by default. It is designed for local, single-user use and does not include authentication. See SECURITY.md for vulnerability reporting.

MIT