HydraFlow

📄 Software Manufacturing — white paper — the operating model behind HydraFlow: treating software delivery as a manufacturing process, with stations, gates, throughput and yield.

📖 HydraFlow Architecture site — auto-generated, refreshed every 4h by the DiagramLoop and on every PR by the arch-regen CI guard.

Log an issue. Agents handle the rest - triaging, planning, implementing, reviewing, and merging every change.

HydraFlow is a delivery kernel for GitHub repositories: it accepts intent, compiles it through a staged pipeline, enforces quality gates, and produces merged software changes.

It scales your workflow, not just your output, turning your repository into a programmable delivery engine powered by your hooks and skills. This is Harness engineering at scale.

Project Status

HydraFlow began as an applied research effort with a single question: can a software delivery factory be operated rather than demonstrated — running continuously, under enforced quality gates, with an auditable record behind every change?

It can. Since February 2026 the system has carried 3,000+ pull requests from intent to merge under its own gates, producing 143 architecture decision records and a continuously regenerated architecture knowledge base along the way.

With that established, the project is entering the next stage of its life: ownership and stewardship of HydraFlow are transferring to 8th Light, moving it from exploration into supported, productised use under an organisation equipped to carry it long term.

Details of the transition — timelines, the project's future home, and support arrangements — will be published here as they are confirmed. Until then, this repository remains the reference implementation.

What Makes It Different

• Quality-gated pipeline, not "one-shot" agent code generation
• Explicit stage controls (triage, plan, implement, review) before merge
• CI checks and human-in-the-loop escalation when confidence drops
• Coverage policy target across stacks: enforce 50% minimum and drive toward 70%+ on critical paths
• Repeatable standards that keep output consistent as workload grows

Why Teams Use It

• Label-driven workflow from issue to merged PR
• Built-in planning, implementation, and review stages
• CI-aware automation with human-in-the-loop escalation
• Repo prep that scaffolds missing quality gates
• Live dashboard for visibility into work, agents, and queue state

How It Works

HydraFlow runs a staged pipeline:

1. Triage: validate issue readiness and queue it for planning.
2. Plan: read-only exploration and concrete implementation plan.
3. Implement: isolated worktree changes with tests.
4. Review: agent review + CI monitoring + merge decision.
5. Escalate when needed: failures and ambiguity route to hydraflow-hitl.

See the full product walkthrough and visuals at hydraflow.ai.

Prerequisites

• Python 3.11+
• uv
• GitHub CLI authenticated (gh auth login)
• Claude CLI and/or Codex CLI available on PATH
• Node.js 20.19+ or 22.12+ (dashboard only)
• Beads task decomposition uses each factory worktree's isolated .beads/issues.jsonl directly. The database-backed bd CLI and Dolt migration/sync commands are not part of the supported HydraFlow runtime.

Claude Authentication (Docker Mode)

Agents run inside Docker containers that cannot access the host keychain. Generate a long-lived token and add it to .env:

claude setup-token

Copy the printed token into your .env file:

CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...

This token is required for Docker mode. It can expire — re-run claude setup-token to refresh.

WhatsApp Notifications (Optional)

Get notified on your phone when Shape needs product direction input. Reply directly from WhatsApp — no computer needed.

Setup:

1. Create a Meta Developer account
2. Create an app, add the WhatsApp product, get a test phone number
3. Note the Phone number ID and Temporary access token from the WhatsApp settings
4. Choose a custom verify token (any string you pick)
5. Add to .env:

   HYDRAFLOW_WHATSAPP_ENABLED=true
   HYDRAFLOW_WHATSAPP_PHONE_ID=<phone number ID>
   HYDRAFLOW_WHATSAPP_TOKEN=<access token>
   HYDRAFLOW_WHATSAPP_VERIFY_TOKEN=<your custom verify string>
   HYDRAFLOW_WHATSAPP_RECIPIENT=<your phone, e.g. 27821234567>
   HYDRAFLOW_DASHBOARD_URL=<public URL of your dashboard>
   

6. Expose the webhook publicly (e.g. ngrok http 5555)
7. In Meta Developer Console → WhatsApp → Configuration:
   • Callback URL: https://<ngrok-url>/api/webhooks/whatsapp
   • Verify token: same string as HYDRAFLOW_WHATSAPP_VERIFY_TOKEN
   • Subscribe to messages

Quick Start

# in your project root
git submodule add https://github.com/T-rav/hydraflow.git hydraflow
git submodule update --init --recursive
cd hydraflow
git checkout v1.0.1   # pin to a stable release — see "Install a pinned release" below

# install deps + bootstrap target repo hooks/assets/labels
# (seeds .env from .env.sample and runs `gh auth login` if needed)
make setup

# REQUIRED: tell HydraFlow which repo to work on — without this the factory
# boots looking healthy and does nothing. Host mode needs no API keys beyond
# gh + your logged-in Claude CLI; Docker mode also needs CLAUDE_CODE_OAUTH_TOKEN
# (see "Claude Authentication"). The QUICK START block at the top of
# .env.sample maps every stage tool to the key it needs.
${EDITOR:-nano} .env   # set HYDRAFLOW_GITHUB_REPO=owner/repo

# scaffold quality gates in the target repo (CI/make/tests/lint where missing)
make prep

# run orchestrator + dashboard (http://localhost:5556)
make run

Install a pinned release

Downstream HydraFlow-format repos (anything bootstrapped with make stamp, or that vendors HydraFlow as a submodule — amplifier, harvestd, Signal Room) should build on a tagged release, not on main. main is the rolling integration tip: it advances every ~4h by RC promotion (ADR-0042) and is green at each promotion, but it is not a release and carries no compatibility promise between promotions. Stable tags (vX.Y.Z) are cut by hand on a promoted main SHA once the release milestone is clear. What a tag promises and how one is cut is in docs/wiki/patterns.md → Release policy; the changes in each release are in CHANGELOG.md.

# fresh clone, pinned to the release
git clone --branch v1.0.1 https://github.com/T-rav/hydraflow.git hydraflow
cd hydraflow && make setup

# or pin an existing submodule
git -C hydraflow fetch --tags origin
git -C hydraflow checkout v1.0.1
git add hydraflow && git commit -m "chore: pin hydraflow to v1.0.1"

# verify what you are on
git -C hydraflow describe --tags --exact-match   # → v1.0.1

To move to the next release, repeat the fetch --tags + checkout vX.Y.Z step and commit the new submodule pointer. Do not track main from a downstream repo.

uv pip install git+https://github.com/T-rav/[email protected] (or any later tag) installs the HydraFlow modules and the hydraflow console script into a venv — useful for importing HydraFlow as a library or smoke-testing a pinned release:

uv venv .venv-hydraflow
uv pip install --python .venv-hydraflow/bin/python git+https://github.com/T-rav/[email protected]
.venv-hydraflow/bin/hydraflow --version   # → hydraflow 1.0.0 (the v1.0.1 tag shipped an unbumped
                                          #   version string; tags after it report themselves correctly)

It is not a way to run the server. The wheel does not carry the dashboard templates, prompt files, static assets or the UI bundle (src/ui/dist), which the server locates relative to a checkout (#11589). Run HydraFlow from a checkout — the Makefile targets set PYTHONPATH=src.

Dashboard Mode (multi-repo)

The dashboard is on by default (dashboard_enabled is a config-file/settings-UI field, not an env var), so simply:

make run

The dashboard opens at http://localhost:5556. When running as a git submodule, the parent repo is auto-registered on startup.

To manually register additional repos:

curl -X POST "http://localhost:5556/api/repos/add?path=/path/to/repo"
curl -X POST "http://localhost:5556/api/runtimes/{slug}/start"

Core Commands

make              # command help
make setup        # bootstrap .env, hooks, labels, local assets
make ensure-hooks # (canary) re-point core.hooksPath at .githooks if hooks aren't firing
make prep         # repo audit + scaffold + hardening loop
make run          # start backend + dashboard
make dry-run      # print actions without executing
make smoke        # critical cross-system smoke tests
make quality-lite # lint + typecheck + security
make quality      # quality-lite + tests

Admin API

HydraFlow exposes first-class HTTP endpoints for operational tasks once make run is active:

• POST /api/admin/prep — sync lifecycle labels, run the prep audit, and seed manifests/memory.
• POST /api/admin/scaffold — scaffold CI/tests (dry-run friendly) and report coverage posture.
• POST /api/admin/clean — destroy all HydraFlow worktrees in the repo and reset local state.

The Make targets (make prep, make scaffold, make clean) invoke scripts/run_admin_task.py directly, so they work without a running server. When the server is active you can also hit the endpoints directly via the included helper:

# example: trigger prep via HTTP without leaving the terminal
PYTHONPATH=src python scripts/call_api.py POST /api/admin/prep
PYTHONPATH=src python scripts/call_api.py POST /api/admin/scaffold
PYTHONPATH=src python scripts/call_api.py POST /api/admin/clean

HydraFlow still writes prep logs, memory, manifests, and run artifacts to .hydraflow/ by default when you run make commands directly inside a repo. Set HYDRAFLOW_HOME=~/.hydraflow/<repo-slug> (or any preferred location) before starting the server if you want those artifacts stored outside the working tree.

Background Loops

Beyond the five pipeline stages, HydraFlow runs background loops for operational health:

• PR unsticker — recovers stale PRs stuck in review or CI
• Memory sync — compacts and syncs agent memory artifacts
• Metrics sync — collects pipeline and GitHub metrics
• Manifest refresh — keeps repo manifests current
• Epic monitor / sweeper — tracks epic progress and generates changelogs
• Verify monitor — confirms post-merge verification issues
• Worktree GC — prunes stale worktrees from merged PRs
• Runs GC — cleans up old run artifacts per retention policy
• ADR reviewer — council-based Architecture Decision Record reviews
• Report issue — processes bug reports with screenshot scanning

Each loop that dispatches an LLM call has its own HYDRAFLOW_*_MODEL env var for cost tuning (report_issue, adr_review, wiki_compilation, transcript_summary). See docs/wiki/architecture.md for the full table and the HYDRAFLOW_BACKGROUND_MODEL cascade behavior.

Self-improving harness

This repo includes a harnessed self-improvement loop (observation + session retro + memory candidate artifacts). See docs/wiki/architecture.md for imported skills and runtime behavior.

Issue Flow Labels

Pipeline lifecycle:

• hydraflow-find — triage queue
• hydraflow-plan — planning stage
• hydraflow-ready — ready for implementation
• hydraflow-review — PR under review
• hydraflow-hitl / hydraflow-hitl-active / hydraflow-hitl-autofix — human-in-the-loop escalation
• hydraflow-fixed — completed

Auxiliary labels:

• hydraflow-epic / hydraflow-epic-child — epic lifecycle management
• hydraflow-verify — post-merge verification tracking
• hydraflow-visual-required / hydraflow-visual-skip — visual validation controls
• hydraflow-dup — duplicate detection

All label names are overridable via .env (created from .env.sample during make setup).

Prep Output and Local Tracking

make prep stores local prep artifacts under:

• .hydraflow/prep/*.md for local prep issues
• .hydraflow/prep/runs/<run-id>/ for run logs/transcripts

When HYDRAFLOW_HOME is set, the same structure lives under ~/.hydraflow/<repo-slug>/prep/... so every repo can share a single machine-wide HydraFlow home.

Each prep run gets one locked run ID at start, and all logs for that run are written under the same run directory.

Dashboard

When make run is active:

• UI: http://localhost:5556
• Shows pipeline state, active workers, CI/review progress, and HITL queue

Development

make test
make lint
make lint-check
make lint-fix
make typecheck
make security
make quality-lite
make quality

Docker Execution Mode

HydraFlow can run agents inside Docker containers for isolation. This requires building the agent image and configuring authentication.

1. Build the agent image

docker build -f Dockerfile.agent -t ghcr.io/t-rav/hydraflow-agent:latest .

2. Enable Docker mode

Add to your .env:

HYDRAFLOW_EXECUTION_MODE=docker

3. Configure agent authentication

Agents running inside containers cannot access your host's OAuth session or macOS keychain. You must provide API credentials via environment variables.

Claude (subscription via Claude Max/Pro):

# Generate a headless auth token
claude setup-token

# Add the token to .env
CLAUDE_CODE_OAUTH_TOKEN=<token-from-setup-token>

Claude (API key):

ANTHROPIC_API_KEY=sk-ant-...

Codex:

Codex credentials are mounted automatically from ~/.codex/ on your host. No extra .env configuration is needed.

Other supported providers (set in .env as needed):

OPENAI_API_KEY, OPENROUTER_API_KEY, ZAI_API_KEY, ZAI_CODING_PLAN_KEY, GEMINI_API_KEY, XAI_API_KEY, DEEPSEEK_API_KEY, MISTRAL_API_KEY, TOGETHER_API_KEY, GROQ_API_KEY

4. Verify

make run
# Create a test issue — check logs for successful agent output instead of
# "authentication_failed" or empty transcripts.

EC2 Deployment

Running HydraFlow as a 24/7 EC2 service is supported out-of-the-box:

• deploy/ec2/deploy-hydraflow.sh bootstraps dependencies, syncs code, and restarts the orchestrator.
• deploy/ec2/deploy-hydraflow.sh doctor runs a readiness check (git repo present, .env seeded, log/home dirs created, required binaries installed) before your first deploy.
• deploy/ec2/hydraflow.service keeps the process alive under systemd; the install helper renders it with SERVICE_USER, SERVICE_GROUP, SERVICE_WORK_DIR, and SERVICE_LOG_FILE overrides so non-/opt installs work without manual edits.
• FastAPI exposes GET /healthz with a ready flag plus per-component checks (orchestrator/worker/dashboard) so load balancers or monitors can make decisions without extra parsing.
• deploy/ec2/deploy-hydraflow.sh health [URL] curls /healthz using the host/port from /etc/hydraflow.env (or your override) and exits non-zero when HEALTHCHECK_REQUIRE_READY=1 but ready=false, which makes it easy to wire into cron, ALB checks, or pager hooks.
• deploy/ec2/deploy-hydraflow.sh wait-ready (or HEALTHCHECK_WAIT_FOR_READY=1 deploy ... deploy) polls /healthz until ready=true; tune the gating with HEALTHCHECK_WAIT_TIMEOUT_SECONDS and HEALTHCHECK_WAIT_INTERVAL_SECONDS.
• /etc/hydraflow.env (override with RUNTIME_ENV_FILE) is sourced automatically so manual run commands and systemd share credentials/config.
• deploy/ec2/deploy-hydraflow.sh install copies the unit into /etc/systemd/system (or your custom SYSTEMD_DIR) and runs the required systemctl enable --now incantations.

See docs/wiki/architecture.md for the full playbook, including how to bind the dashboard to 0.0.0.0 using the new HYDRAFLOW_DASHBOARD_HOST config knob and how to scope your EC2 security group safely.

Contributing

• Fork it.
• Run HydraFlow on HydraFlow. (via make run in the repo)
• /gh-issue "thing to change"
• PR it back.
• See CLAUDE.md for project conventions and lifecycle labels.

License

Apache 2.0 © 2026 Travis Frisinger