loop-engineering is an MIT-licensed TypeScript pattern library, starter collection, and CLI for developers and platform teams who want to design loops that discover work, hand it to AI coding agents, verify the results, and persist state instead of typing the next prompt themselves.

What it is

Loop engineering lives in the AI coding agent ecosystem and ships a command-line front door published as @cobusgreyling/loop, run through npx. It is a pattern library for operating agents around a codebase, inspired by Addy Osmani and Boris Cherny, and it pairs written patterns with starters and small CLI tools so that agent work runs on a defined cadence rather than on improvisation. The documented patterns each carry a cadence, a week-one rollout level, and a cost tier, so a team can reason about what it is about to automate before switching anything on.

The concrete problem it solves is the habit of manually prompting an agent turn after turn. The project replaces that habit with a loop: a system that discovers work, hands it to agents, verifies results, and persists state. The README is explicit that this is not a "rewrite the module" button — it is infrastructure for keeping a repository healthy, landing and babysitting pull requests, and shipping features or refactors as small PRs from a todos list.

Key capabilities

• npx @cobusgreyling/loop init . --pattern daily-triage --tool claude scaffolds a loop; --tool defaults to claude and can be swapped for grok, codex, or opencode.
• npx @cobusgreyling/loop doctor . checks whether a repository is ready for a loop.
• npx @cobusgreyling/loop cost --pattern daily-triage --level L1 estimates the token cost of a chosen pattern and rollout level.
• A named pattern set with per-pattern cadence, week-one level, and cost: daily-triage, thin-loop, pr-babysitter, ci-sweeper, dependency-sweeper, changelog-drafter, post-merge-cleanup, and issue-triage, indexed in patterns/registry.yaml.
• Three rollout levels — L1 report, L2 assisted, L3 unattended — with the documented rule that a loop advances only after the verifier has been right for a week.
• STATE.md as the persisted loop state, with a thin-loop starter that requires no STATE.md at all.
• Loop Ready scoring that weights recent runs harder than files on disk, so a 30-day-old STATE.md is not treated as L3.

Who uses it and how

• Teams keeping a repository healthy — issues, CI, dependencies — start with the Quickstart and the daily-triage pattern, which runs at one day to two hours on a low cost tier and stays at L1 report in week one.
• Maintainers who land and babysit pull requests use the PR Babysitter pattern at a 5-to-15-minute cadence, which the project marks as high cost.
• Platform engineers sweeping CI use ci-sweeper at 5-to-15 minutes, marked very high cost with an L2 cautious week one.
• Projects that want a loop inside GitHub Actions with almost no files use the thin-loop starter, which needs no STATE.md and runs on event plus one-day cadence.
• Developers shipping a feature or refactor follow the refactor path, turning todos into small PRs.

Getting started

Run npx @cobusgreyling/loop init . --pattern daily-triage --tool claude, then npx @cobusgreyling/loop doctor . to check readiness. An empty repository can follow scripts/empty-to-state-demo.sh for a first STATE.md walkthrough.

How it compares

The project is deliberately tool-agnostic across the agents it targets, with worked examples for Claude Code, Grok, Codex, OpenClaw, Opencode, and GitHub Actions, plus a Claude Code plugin. Rather than competing with those agents, it sits above them as the loop design and measurement layer, so the same pattern can be reused when a team changes which agent runs the work.

When to use it — and when not to

A self-hoster must operate the loop itself: the STATE.md state file, a verifier that has to prove itself over a week, and the agent tooling behind it, with the README warning plainly that token costs can explode and that unattended loops make unattended mistakes. It is a poor fit for anyone wanting a one-shot code rewrite button, or for teams unwilling to spend week one in report-only mode. Platforms that cannot absorb bursty token spend, or cannot review what an unattended loop ships, should not enable L3.

npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop doctor .

npx @cobusgreyling/loop init . --pattern daily-triage --tool claude
npx @cobusgreyling/loop doctor .
npx @cobusgreyling/loop cost --pattern daily-triage --level L1