hyperloop

A reconciler that keeps code in sync with specs using AI agents. Specs are desired state. Code is actual state. Hyperloop continuously closes the gap.

Spec (desired) <-> Code (actual) = Gap
Gap -> Work -> PR -> Gate -> Merge -> Gap closed

You don't manage tasks -- you manage specs. Tasks are an internal implementation detail, like Kubernetes pods. Want to add a feature? Update the spec. Want to cancel it? Remove it from the spec.

Prerequisites

• Python 3.12+
• kustomize on PATH
• git
• gh CLI (for GitHub PR operations)
• An Anthropic API key, or Vertex AI / Bedrock credentials

Install

pip install hyperloop

Quickstart

mkdir my-project &&cd my-project && git init && git commit --allow-empty -m init
# Write a spec
cat > specs/auth.md << 'EOF'# User AuthenticationImplement JWT-based auth. POST /auth/login, POST /auth/register, GET /auth/me.Passwords hashed with bcrypt. JWTs expire after 24h.EOF# Initialize hyperloop structure
hyperloop init
# Run the orchestratorexport ANTHROPIC_API_KEY=your-key # or CLAUDE_CODE_USE_VERTEX=1
hyperloop run
# With GitHub PR support
hyperloop run --repo owner/repo

Reconciliation Cycle

Each cycle has four phases:

1. COLLECT -- reap finished workers, run cycle hooks (e.g. process-improver)
2. INTAKE -- detect spec gaps and failed tasks, invoke PM agent to propose new work
3. ADVANCE -- advance existing tasks through pipeline steps (gates, actions)
4. SPAWN -- decide which tasks need workers, compose prompts, spawn agents

The orchestrator halts when no gaps remain. Use hyperloop watch for continuous operation.

Pipeline Primitives

Work moves through a pipeline defined in process.yaml. Five primitives:

Primitive	What it does
agent: X	Spawn a worker agent with X's prompt template
gate: X	Block until an external signal (e.g. PR label, CI status)
action: X	Execute an operation with optional args: (e.g. merge PR, mark ready)
check: X	Evaluation step (mechanical or agent-backed) with optional args: and evaluator:
loop:	Wrap steps -- on fail restart from top, on pass continue

Example pipeline:

pipeline:
- loop:
- agent: implementer
- agent: verifier
- action: mark-pr-ready
- action: post-pr-commentargs:
body: "@coderabbit recheck"
- check: pr-reviewevaluator: pr-reviewerargs:
require_reviewers: ["coderabbitai"]
- action: merge-pr

Checks have three outcomes: PASS (advance), FAIL (restart loop), WAIT (stay, re-evaluate next cycle). When evaluator: is set, the check spawns an agent to evaluate after mechanical pre-conditions pass.

Framework-shipped actions and checks:

Step	Type	What it does	Config
merge-pr	action	Wait for mergeable, squash-merge	--
mark-pr-ready	action	Mark a draft PR as ready for review	--
post-pr-comment	action	Post a comment on the task's PR	args: {body: str}
pr-review	check	CI + reviewer pre-checks, then agent evaluates PR feedback	evaluator: pr-reviewer; args: {require_reviewers: [str]}

Project Structure

After hyperloop init:

my-project/
├── .hyperloop.yaml # orchestrator config
├── .hyperloop/
│ ├── agents/
│ │ ├── kustomization.yaml # composition point (base + process component)
│ │ └── process/
│ │ ├── kustomization.yaml # process-improver writes here
│ │ └── process.yaml # pipeline + gate/action/hook config
│ ├── state/
│ │ ├── tasks/ # task metadata (YAML frontmatter)
│ │ └── reviews/ # per-round review files
│ └── checks/ # executable check scripts
└── specs/
└── *.md # product specs (your domain)

specs/ is yours -- product specs only. .hyperloop/ is orchestrator-managed.

Prompt Composition

Three layers, resolved via kustomize build:

Layer	Source	What it provides
Base	hyperloop repo base/	Core agent prompts
Project overlay	gitops repo or in-repo patches	Project-specific guidelines
Process overlay	.hyperloop/agents/process/	Learned rules from process-improver

At compose time the orchestrator injects: prompt + guidelines + spec content + findings from prior rounds.

Configuration

All configuration lives in .hyperloop.yaml at the repo root. CLI flags override YAML values.

# .hyperloop.yamlrepo: owner/repo # GitHub repo (inferred from git remote if omitted)overlay: .hyperloop/agents/ # kustomize overlay directorybase_branch: main # base branch for PRs and rebasingruntime: local # local | ambientmax_workers: 6# parallel agent workerspoll_interval: 30# seconds between cyclesmax_task_rounds: 50# max implement-verify loops per taskmax_cycles: 200# max orchestrator cyclesmax_action_attempts: 3# action retries before looping backmerge:
auto_merge: true # auto-merge approved PRsstrategy: squash # squash | merge | rebasedelete_branch: true # delete branch after mergenotifications:
type: github-comment # github-comment | nullobservability:
log_format: console # console | jsonlog_level: info # debug | info | warning | errormatrix: # optional Matrix notificationshomeserver: https://matrix.example.comroom_id: "!abc123:matrix.example.com"token_env: MATRIX_ACCESS_TOKENotel: # optional OpenTelemetryendpoint: http://localhost:4317service_name: hyperloopdashboard:
enabled: false # enable activity dashboardevents_limit: 1000# max retained events

See docs/configuration.md for the full reference with all options, defaults, and environment variables.

CLI

hyperloop run [--path .] [--repo owner/repo] [--branch main] [--config .hyperloop.yaml] [--max-workers 6] [--dry-run]
hyperloop init [--path .] [--base-ref REF] [--overlay REF]
hyperloop dashboard [--path .] [--port 8787]

Custom Processes

Override the default pipeline in .hyperloop/agents/process/process.yaml:

apiVersion: hyperloop.io/v1kind: Processmetadata:
name: defaultpipeline:
- loop:
- agent: implementer
- agent: verifier
- action: mark-pr-ready
- gate: pr-require-label
- action: merge-prgates:
pr-require-label:
type: label # label (default: lgtm) | pr-approval | ci-status | allhooks:
after_reap:
- type: process-improver

Gates are pure queries with no side effects. PR lifecycle actions (marking ready, posting comments) are separate action: steps that you place wherever you need them in the pipeline.

Architecture

Hexagonal (ports and adapters). The domain is pure logic with no I/O. Ports define interfaces, adapters implement them. Seven concerns are separated:

Port	Purpose
SpecSource	Where to read desired state
StateStore	Where task/worker state lives
Runtime	Where agent sessions execute
GatePort	How gates are evaluated
ActionPort	How pipeline actions execute
NotificationPort	How humans are told to act
OrchestratorProbe	Domain observability

The default adapter set is git-native (git state store, git spec source, local worktrees for agent isolation), but the architecture is adapter-agnostic.

See specs/spec.md for the full specification.

Development

uv sync --all-extras
uv run pytest
uv run ruff check .&& uv run ruff format --check .
uv run pyright