loopy

A library of reusable automation loops that software teams import into their repositories. A "loop" is a recurring, semi-autonomous task that keeps some part of a codebase healthy with little manual effort — for example, keeping documentation in sync with the code.

Loopy is built for teams that want agentic maintenance without handing an agent unbounded repo access: every loop has deterministic detection, explicit output, and guardrails that make the result reviewable before anything lands.

Review first

If you are evaluating this repo, start with:

1. The loop contract — the safety model every loop must follow.
2. Loops — the catalog of maintenance/product workflows currently implemented.
3. Proof it works — real dogfood artifacts generated by the runner.
4. 1-click import — how a consuming repo gets a ready-to-run GitHub workflow.

Current proof: npm run build, npm test, and the dogfood workflow validate the loop catalog through the real CLI/dry-run path, including PR/comment outputs and long-horizon gated loops.

The loop contract

Every loop follows one contract, regardless of how smart its internals are:

trigger → detect → act → output → guardrails

• trigger — cron schedule, repo event, or manual run
• detect — decide whether there is work to do (cheap/deterministic)
• act — do the work; an AI/agent step, deterministic code, or both
• output — a reviewable pull request (safe, reversible), or an advisory comment
• guardrails — path allowlist, max-files cap, idempotency, approvals

The runner is loop-agnostic and fails safe: on any error (including a guardrail violation) it produces no output and never partially applies changes.

Loops

Loop	What it does	act	Output
auto-docs	Updates docs when the code surface drifts	AI	PR
dep-updates	One grouped PR bumping non-major dependency updates	deterministic	PR
changelog	A changelog entry from unreleased commits	deterministic	PR
pr-review	An advisory automated review comment on a PR	AI	comment
test-coverage	Backfills tests for uncovered changed lines (self-validating)	AI	PR
security-remediation	Human-gated fixes for security findings above a threshold	hybrid	PR
kb-gap	Drafts KB articles for recurring support topics (self-heal docs)	AI	PR
metric-anomaly	Z-score anomaly briefs over your metrics	deterministic	PR
incident-followup	Overdue postmortem action items + recurring root causes	deterministic	PR
flake-quarantine	Score flaky tests across runs (stateful) and quarantine the worst	deterministic + state	PR
release-train	Rolling Release PR (version + changelog) from conventional commits	deterministic	PR
license-sbom-drift	Flag dependency licenses outside the allowlist	deterministic	PR
prompt-eval-gate	Regression-gate prompts vs a baseline (stateful); gated promotion	AI + state	comment / PR
test-impact-budget	Flag tests whose runtime grew past a rolling EWMA baseline	deterministic + state	PR
data-contract-guard	Block breaking schema changes vs an approved baseline (human-gated)	deterministic + state + gate	comment / PR
cost-guardrail	Track idle cloud resources across runs; human-gated remediation	deterministic + state + gate	comment / PR
eval-set-drift	Surface production categories missing from the eval set (stateful)	deterministic + state	PR

Plus three long-horizon loops on the longrun primitives (durable state, approval gates, resumable advancement): the Experiment Lifecycle Orchestrator, the Codemod Campaign (throttled cross-PR migration with a ledger + pilot gate), the Model-Upgrade Migration (golden-set diff → human-gated model switch), the API Deprecation Rollout (announce → grace-period wait → caller-drain → human-gated removal), and the Dependency Major Migration (verify build → human-gated approval → emit the major bump).

🌐 Project site · See the roadmap for the backlog and the research catalog for the full survey.

Proof it works — demo gallery

Want to see what each loop actually produces? The demo gallery holds the real artifacts every loop generates — the report markdown, PR file changes, advisory comments, and long-horizon lifecycle transcripts — each from a realistic example input. They're not hand-written: the dogfood harness runs all 26 loops end-to-end and emits them.

npm run build && npm run dogfood            # run all loops, assert each works (28/28)
npm run build && npm run dogfood -- --emit demos   # regenerate the demo artifacts

The harness drives CLI loops through the real loopy run --dry-run path with injected/fixture boundaries, gated loops through block→approve→PR, and the export-only long-horizon loops through their full advance() lifecycles. CI runs it on every push (see .github/workflows/dogfood.yml).

Project layout

src/core/                  loop contract, runner, guardrails, manifest loader
src/core/longrun/          long-horizon primitives: durable state, approval gates, resumable plans
src/adapters/github-action GitHub Action adapter + REST client + PR publishing
src/ai/                    OpenAI-compatible AI provider (defaults to OpenRouter) + boundary adapters
loops/<name>/              the catalog (loop.yaml + playbook.md + hooks/)
openspec/                  spec-driven development workflow (specs, changes, research)

Long-horizon loops (foundations)

Beyond the single-shot loops above, src/core/longrun/ provides the primitives for stateful, multi-step, long-horizon product-level loops (see openspec/research/product-level-loops.md): a durable state store (memory across runs), a first-class approval gate (human checkpoints), and resumable multi-step plans (runPlan) with wait-states and gate-blocking. These are the substrate for ambitious loops like experiment orchestration, incident coordination, and churn intervention.

Development

npm install
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm test            # vitest
npm run build       # compile distributable JS
npm run dogfood     # exercise every loop through generated demo artifacts

Verified against the current working tree on 2026-06-27: typecheck, lint, 249 Vitest tests, and build all passed locally; latest ci, pages, and dogfood GitHub Actions runs passed on main.

Requires Node.js >= 20.

1-click import

Import any loop into your repo with a single command — it scaffolds a ready-to-run GitHub workflow wired to the loop's trigger, output, and secrets:

npx loopy add dep-updates     # scaffolds .github/workflows/loopy-dep-updates.yml
npx loopy list                # see all loops and what each needs

Commit the generated workflow and set the listed secrets (always GITHUB_TOKEN; AI loops also need OPENROUTER_API_KEY). The workflow runs npx loopy run <loop>, which executes the loop and opens the PR/comment.

AI provider. loopy ships an OpenAI-compatible client that defaults to OpenRouter and the z-ai/glm-5.2 model — set OPENROUTER_API_KEY and you're done. It's configurable via env, so any OpenAI-compatible endpoint/model works:

Env var	Default	Purpose
OPENROUTER_API_KEY (or LOOPY_AI_API_KEY / OPENAI_API_KEY)	—	API key
LOOPY_AI_BASE_URL	https://openrouter.ai/api/v1	OpenAI-compatible base URL
LOOPY_AI_MODEL	z-ai/glm-5.2	model id

dep-updates and changelog are deterministic (no AI). auto-docs and pr-review are turnkey once an AI key is set (pr-review runs on the pull_request event and posts an advisory comment); test-coverage also needs its coverage boundary wired — see each loop's README.

For a fully manual setup instead, see loops/auto-docs/example.github-workflow.yml.

License

MIT