OpenHydra

Lightweight, local-first multi-agent orchestration. One command, no Docker, no external services.

Quick Start

# 1) Install
pip install openhydra

# 2) Create a local config with safe defaults
openhydra onboard

# 3) Validate your setup
openhydra doctor

# 4) Run your first workflow
openhydra run "Build a Python CLI that converts CSV to JSON"

Need channel setup, provider configuration, advanced options, or source/developer install? See SETUP.md. For embedding OpenHydra into your own app via REST/WebSocket API + auth, see API and Auth Guide.

OpenHydra is best for work that needs:

• planning with dependencies, checks, and retries
• using multiple tools (code, tests, docs, browser/search, channels)
• selecting the right role, tools, and skills instead of one fixed script

Personal planning and assistant tasks:

• "Plan my Tokyo trip from May 12-20: flights from SFO, vegetarian options near Shinjuku, and a day-by-day itinerary under $3,500"
• "Build my next 6-week personal operating plan: gym 4x/week, finish two certifications, and keep Sundays blocked for family"
• "Organize my monthly admin stack: rent, taxes, insurance renewals, and reminders with due dates and fallback actions"

Research for you:

• "For our seed-stage B2B SaaS (ACV ~$8k), compare 6 competitors' pricing and positioning, then produce a differentiated GTM brief with sources"
• "Review our last 120 support tickets and 40 churn notes, cluster root causes, and propose the top 5 retention experiments by expected impact"
• "Prepare a launch-readiness compliance brief for our AI meeting assistant (US + EU): likely legal risks, mitigations, and questions for counsel"
• "Evaluate expansion options across Texas, Florida, and Ontario using market size, regulatory friction, and hiring costs; recommend one for Q3"
• "Compare open-source LLM eval frameworks for our RAG product, rank tradeoffs, and produce a recommendation memo with implementation implications"
• "Review open GitHub issues for our checkout service, cluster duplicate themes, and propose a prioritized 2-sprint stabilization plan"
• "Screen US large-cap stocks, liquid call options, and top Polymarket contracts for this week; recommend 3 risk-defined opportunities with thesis, catalysts, downside case, and confidence score"
• "Find the best recent papers on hierarchical reasoning for agentic products, rank the top 10 by practical relevance, and summarize what we can implement in our roadmap next sprint"

Build software products:

• "Define and deliver v1 team invites for our app: PRD, rollout plan, implementation, and validation tests"
• "Migrate our Flask billing API to FastAPI without breaking existing /v1 endpoints or auth behavior, then prove parity with tests"
• "Add Google and GitHub OAuth to our web app, preserve existing session behavior, and add integration coverage for login + callback flows"
• "Find and fix intermittent checkout timeouts seen in production logs, then add a regression test that reproduces the original failure"
• "Audit dependencies for known CVEs, patch low-risk updates, and publish a release-risk summary with test results"
• "Generate a weekly engineering readiness report for our team covering test health, dependency drift, incident carryover, and release blockers"

Talk to OpenHydra from any channel

OpenHydra runs one orchestration engine and lets you talk to it from multiple channels. You can submit work from Web, Slack, WhatsApp, or Discord, and get progress/final updates back in that channel.

Basic flow:

1. Enable the channels you want in .openhydra/openhydra.yaml
2. Start the server with uv run openhydra serve
3. Send your task from your preferred channel

Step-by-step channel setup guides:

• Slack setup
• WhatsApp setup
• Discord setup
• API and auth integration guide

Example channel config:

web:
  enabled: true
  host: "127.0.0.1"
  port: 7070

channels:
  slack:
    enabled: true
  whatsapp:
    enabled: true

How to talk to agents:

• Web: submit tasks via REST (POST /api/v1/workflows) and watch events on WebSocket (/api/v1/ws)
• Slack: send a DM to the bot or @mention it in a channel with your task text
• WhatsApp: send a normal message as the task text; control commands like approve, reject <reason>, pause, resume, cancel are supported. On first setup, openhydra serve prints the pairing QR in terminal.
• Discord: run /hydra with action=run and your task as argument

Planning on the fly

You do not need to write a plan first. Submit the outcome directly:

uv run openhydra run "Migrate this Flask API to FastAPI without breaking existing endpoints" --watch

OpenHydra then:

1. Uses the planner role to generate a JSON step graph (role_id, instructions, depends_on)
2. Persists workflow + steps to SQLite before running (for durability/recovery)
3. Executes ready steps based on dependencies (independent branches can run concurrently)
4. Applies role gates (quality/tests/approval) between steps
5. Reports progress/events and final output

For that FastAPI migration prompt, a typical generated plan could look like:

1. eng.init: inventory current Flask routes and migration constraints
2. eng.implement: port app structure and handlers to FastAPI
3. test.code: run/update tests and validate endpoint compatibility
4. pm.review: verify scope completion and release readiness

To inspect the generated plan and step-by-step progress:

uv run openhydra status <workflow_id>

Contributing

See CONTRIBUTING.md for the contributor workflow, checks, and PR requirements.

Learn More

• SETUP.md — complete setup and configuration reference.
• Advanced / Learn More — configuration model, architecture, custom channels, dynamic skills, and OpenClaw integration.
• Channel setup playbooks:
  • Slack
  • WhatsApp
  • Discord
• SPEC.md — architecture, protocols, and extension APIs.
• PLAN.md — implementation roadmap and phase status.
• CLAUDE.md — maintainer conventions and project notes.
• AGENTS.md — repository contribution and workflow guidelines.
• config/agents.yaml — default role catalog and gate configuration.

Status

Early development. See PLAN.md for current phase.