Hydra connects native Codex tasks to delegated GitHub work: specification, implementation, verification, code and security review, protected merge and follow-up. Codex selects work, proposes improvements, executes and asks questions. Hydra provides deterministic tools; GitHub holds the product's durable records and delivery evidence.
Product repositories own goals, specifications, Issues, branches, PRs and CI. Hydra has no operational repository, SQLite database, state branch, JSON journal or web console. One active host admits one native assignment or supervised CLI worker at a time.
Use the Hydra plugin with one SDLC skill and five local MCP tools:
hydra_status, hydra_begin, hydra_checkpoint, hydra_verify and hydra_deliver.
See native setup and recovery for the pinned installation,
host settings and task contract. An MCP call never starts another model worker.
flowchart LR
U[Human: goals and important decisions] <--> C[Codex: native tasks and questions]
C -->|bounded tool calls| H[Hydra: GitHub and workspace operations]
H <--> G[Product GitHub: Issues, specs, PRs, CI]
H --> W[Host: owned workspace and verification]
G -->|current evidence and findings| C
Questions stay in native Codex tasks. Record the publishable decision in the Issue before resuming its exact attempt. Chat answers do not replace protected GitHub reviews. Enable a native heartbeat after actual task, delivery and recovery qualification; source installation alone does not establish unattended operation.
When only an unanswered decision remains, pause that goal's recurring wake after independent preparation and external monitoring are exhausted. Keep the original question and task; a real answer re-enters its authority and ownership checks. The operating continuity contract separates this wait from progressing CI and unconfirmed native assignments.
The macOS operations app shows host/project admission separately from
execution. Start/Resume permit eligible new work; Pause/Stop block it. Individual
project restrictions survive global Resume, and unknown execution or schedule
coverage can prevent Quit. Inspect the selected installation with
hydra identity --config /absolute/host.toml; version and source/configuration
digests are observations, not proof of native control or unattended operation.
Install Python 3.14+ with the optional pinned Codex SDK into an isolated environment:
python3.14 -m pip install '.[codex]'
hydra status --repos owner/product
hydra run --issue https://github.com/owner/product/issues/12 \
--workspace-root /absolute/owned/workspaces --host-alias development-mac
hydra serve --repos owner/product owner/another-product \
--workspace-root /absolute/owned/workspaces --host-alias development-macPackage installation and direct source imports require Python 3.14 or newer. When upgrading an existing installation, prepare a separate 3.14+ environment and qualify its dependencies and runtime identity before changing the service configuration. Updating source does not migrate or restart an installed service.
The first runtime selects the existing openboa GitHub CLI account per operation
and the existing ChatGPT subscription or available account credits. It neither buys credits nor switches
to a paid model API. Configure the project's reviewed .hydra.toml on its protected
default branch and delegate a ready Issue using the registration guide.
The host supplies owned workspace and storage prerequisites. Managed workspaces
require their registered lifecycle and storage providers; Hydra refuses an internal
disk fallback. Foreground and login-service execution use the same serve command.
Enable a login service only after actual delivery and recovery qualification.
New host admission is stopped by default. After configuring the same host lock
and repository allowlist for the CLI and native tools, use
hydra control start --config /absolute/host.toml --all to permit eligible work.
This does not start native tasks or activate external schedules.
flowchart LR
I[Ready product Issue] --> S[Specification and independent review]
S --> C[Codex implementation]
C --> V[Verification and independent review]
V --> P[One coherent PR]
P --> G[Current CI and code/security reviews]
G --> M[Exact-head protected merge]
M --> O[Main checks and Issue completion]
G -->|Findings| C
A decision or CI wait releases capacity for another repository. Active external waits are checked every 60 seconds; idle intake every five minutes. Unchanged state does not trigger a model turn or repeated output.
Native ready, paused and decision labels control delegated work; hydra:active
keeps unfinished work and interrupted completion cleanup discoverable. Open intake
and closed active recovery are queried separately, without scanning closed history.
Labels do not establish successful checks, reviews or merge.
not_delegated blocks Hydra execution; it does not erase an already delegated goal.
The native operating task may continue read-only research, public-safe Issue preparation
or work in an already designated private planning area, but it must not create a Hydra
attempt, worktree, branch or product edit before the Issue is formally delegated.
Read-only status may return resume_hint=decision_resolved or replan_ready when an
exact current authorized marker exists and no stronger intake or policy wait applies.
The hint requests a fresh reconciliation through hydra_begin; it never authorizes a
repeated external effect.
A decision marker is valid only after an authorized, non-empty companion comment of
the form hydra: decision <attempt-id> context followed by its public-safe summary.
The exact hydra: decision <attempt-id> resolved marker must be a later comment.
One service-authored Issue comment records attempts, revisions, checkpoint, pending action and next step. This directs recovery; actual branch/PR/CI/provider facts authorize delivery. Restart reconciles effects before retry and never creates a replacement PR because a response was lost. Unknown executions and foreign-host attempts require confirmed shutdown, not heartbeat expiry. Unpushed work cannot be recovered after host loss. See the implementation contract.
The existing OS lock retains a boot identity and one unresolved launch nonce. It blocks restart after an uncertain execution even if its wrapper has disappeared; confirmed cleanup clears it. Native assignments add a fixed scope digest to bind their repository, Issue, attempt, head and policy. The ticket contains no workflow history or result. Native tickets survive reboot until explicit stopped reconciliation. Write results are committed and recorded as restartable checkpoints before retirement. Native included permission or explicit credit availability with spend permission permits a turn attempt; Codex accepts or rejects execution. Unknown usage and workspace denials hold without purchases or billing fallback. Credit attempts currently require availability in every selected quota bucket, so an additional bucket without credit information conservatively waits.
The GitHub-native implementation replaces the earlier SQLite prototype. Deterministic tests and authenticated runtime qualification are recorded in the verification record. These are separate from actual two-project delivery, host handover and background activation. The repository does not claim unattended operation merely because the CLI exists.
python3 -m unittest discover -s tests -vSee CONTRIBUTING.md for Hydra development. Product-agent evaluation criteria stay in each product; Hydra does not lower them to report successful work.