hyperloop 0.4.0

Orchestrator that walks tasks through composable process pipelines using AI agents

hyperloop

Walks tasks through composable process pipelines using AI agents. You write specs, it creates tasks, implements them, verifies the work, and merges the results.

Prerequisites

• Python 3.12+
• Claude Code CLI (claude on PATH)
• git
• gh CLI (optional, for GitHub PR operations)

Install

From PyPI (once published):

pip install hyperloop

From source (for development or testing):

git clone [e-mail]:jsell-rh/hyperloop.git
cd hyperloop
uv sync --all-extras

Quickstart

1. Create a repo with a spec:

mkdir -p my-project/specs
cd my-project
git init && git commit --allow-empty -m "init"

2. Write a spec. This is what you want built. Be specific about acceptance criteria:

<!-- specs/auth.md -->
# User Authentication

Implement JWT-based authentication for the API.

## Acceptance Criteria

- POST /auth/login accepts email + password, returns JWT
- POST /auth/register creates a new user account
- GET /auth/me returns the current user (requires valid JWT)
- Passwords are hashed with bcrypt, never stored in plaintext
- JWTs expire after 24 hours

3. Run against the local repo:

# From inside the repo
uv run hyperloop run

# Or point to a repo elsewhere
uv run hyperloop run --path ~/code/my-project

# With GitHub PR support (draft PRs, lgtm gates, squash-merge)
uv run hyperloop run --repo owner/repo

# Dry run (show config, don't execute)
uv run hyperloop run --dry-run

When --repo is not set, completed work is merged locally into the base branch via git merge. When --repo is set, the orchestrator creates draft PRs, polls for lgtm labels on gates, and squash-merges via GitHub.

Configuration

Create .hyperloop.yaml in your repo root:

target:
  base_branch: main

runtime:
  max_workers: 4

merge:
  auto_merge: true
  strategy: squash

Then run from the repo directory (or use --path):

hyperloop run
hyperloop run --path ~/code/my-project

All settings have sensible defaults. --repo is only needed for GitHub PR operations.

Customizing Agent Behavior

Hyperloop ships with base agent definitions (implementer, verifier, etc.) that work out of the box. To customize them for your project, overlay with patches.

In-repo overlay

For single-repo projects. Agent patches live in the repo itself:

# .hyperloop.yaml
overlay: .hyperloop/agents/

your-repo/
├── .hyperloop.yaml
├── .hyperloop/
│   └── agents/
│       ├── implementer-patch.yaml
│       └── process-patch.yaml
└── specs/

An implementer patch injects your project's persona:

# .hyperloop/agents/implementer-patch.yaml
kind: Agent
name: implementer
annotations:
  ambient.io/persona: |
    You work on a Go API service.
    Build: make build. Test: make test. Lint: make lint.
    Follow Clean Architecture. Use dependency injection.

Shared overlay via gitops repo

For teams with multiple repos sharing agent definitions. The overlay lives in a central gitops repo and references the hyperloop base as a kustomize remote resource:

# .hyperloop.yaml
overlay: [e-mail]:your-org/agent-gitops//overlays/api

# your-org/agent-gitops/overlays/api/kustomization.yaml
resources:
  - github.com/org/hyperloop//base?ref=v1.0.0

patches:
  - path: implementer-patch.yaml
    target:
      kind: Agent
      name: implementer
  - path: process-patch.yaml
    target:
      kind: Process
      name: default

This pins the base version and lets you upgrade across all repos by bumping the ref.

Custom Processes

The default pipeline is: implement, verify, merge. Override it by patching the process:

# process-patch.yaml
kind: Process
name: default

pipeline:
  - loop:
      - loop:
          - role: implementer
          - role: verifier
      - role: security-reviewer
  - gate: human-pr-approval
  - action: merge-pr

Four primitives:

Primitive	What it does
role: X	Spawn an agent. Fail restarts the enclosing loop.
gate: X	Block until external signal (v1: lgtm label on PR).
loop	Wrap steps. Retry from top on failure.
action: X	Terminal operation (merge-pr, mark-pr-ready).

Loops nest. Inner loops retry independently of outer loops.

What it creates in your repo

The orchestrator writes to specs/ in your repo:

specs/
├── tasks/       # task files with status, findings, spec references
├── reviews/     # review artifacts from verifier (on branches)
└── prompts/     # process improvements (learned over time)

All task state is tracked in git. Every commit includes Spec-Ref and Task-Ref trailers for traceability. PRs are created as drafts and labeled by spec and task.

Configuration Reference

# .hyperloop.yaml

overlay: .hyperloop/agents/    # local path or git URL to kustomization dir

target:
  repo: owner/repo                 # GitHub repo (default: inferred from git remote)
  base_branch: main                # trunk branch
  specs_dir: specs                 # where specs live

runtime:
  default: local                   # local (v1) | ambient (planned)
  max_workers: 6                   # max parallel task workers

merge:
  auto_merge: true                 # squash-merge on review pass
  strategy: squash                 # squash | merge
  delete_branch: true              # delete worker branch after merge

poll_interval: 30                  # seconds between orchestrator cycles
max_rounds: 50                     # max retry rounds per task before failure
max_rebase_attempts: 3             # max rebase retries before full loop retry

Development

uv sync --all-extras
uv run pytest                    # run tests (280 tests)
uv run ruff check .              # lint
uv run ruff format --check .     # format check
uv run pyright                   # type check
uv run hyperloop --help          # CLI help