# Loop Engineering

> An open-source reference repo and CLI toolkit for designing automated loop systems that orchestrate AI coding agents like Grok, Claude Code, and Codex.

Loop Engineering is an open-source project by Cobus Greyling that provides practical patterns, starter kits, and CLI tools for building automated systems that prompt and orchestrate AI coding agents. Licensed under MIT, the repository lives on GitHub and ships three npm-published CLIs alongside seven production-ready loop patterns. The project draws on ideas articulated by Addy Osmani and Boris Cherny (Head of Claude Code at Anthropic), who are quoted in the README.

## What It Is

Loop Engineering is a framework concept and reference implementation for a shift in how developers work with AI coding agents. Rather than crafting individual prompts, the practitioner designs a *loop* — a recursive, scheduled control system that issues prompts, verifies results, manages state, and decides when to escalate to a human. The repository translates this concept into clone-and-run starters, a pattern library, and three CLI tools that scaffold, audit, and cost-estimate loops.

## The Five Building Blocks

The project organizes loop design around six primitives:

- **Automations / Scheduling** — discovery and triage on a cadence
- **Worktrees** — safe parallel execution environments
- **Skills** — persistent project knowledge attached to the agent
- **Plugins & Connectors** — reach into real tools via MCP
- **Sub-agents** — maker/checker splits for verification
- **Memory / State** — durable state outside any single conversation

A cross-tool primitives matrix documents how Grok, Claude Code, and Codex each implement these primitives.

## The CLI Toolkit

Three npm packages ship from tagged releases and require no repository clone:

- **loop-audit** (`@cobusgreyling/loop-audit`) — scores a project's loop readiness, detects activity, and suggests improvements via `--suggest`
- **loop-init** (`@cobusgreyling/loop-init`) — scaffolds a starter for a chosen pattern and tool, with budget and run-log support
- **loop-cost** (`@cobusgreyling/loop-cost`) — estimates token spend for a given pattern and cadence

The repository's own CI runs `validate-patterns` and `audit` workflows on every push and pull request, dogfooding the tools it ships.

## Seven Production Patterns

The pattern library covers seven named loops, each with a recommended cadence, a starter kit, a suggested first-week level (L1 report-only through L3 unattended), and a token-cost estimate:

- Daily Triage, PR Babysitter, CI Sweeper, Dependency Sweeper, Changelog Drafter, Post-Merge Cleanup, Issue Triage

An interactive pattern picker is hosted on GitHub Pages, and a machine-readable `patterns/registry.yaml` indexes all seven patterns for tooling consumption.

## Safety and Tradeoffs

The README is candid about risks. Token costs can escalate sharply with sub-agents and long-running loops. Verification remains the developer's responsibility — unattended loops make unattended mistakes. The project documents failure modes in an incident-style catalog, anti-patterns to avoid before production, multi-loop coordination guidance, and a safety file covering denylists, auto-merge gates, and MCP scopes. The phased rollout model (L1 → L2 → L3) is designed to build confidence before granting unattended execution rights.

## Update: Active Development as of June 2026

The repository was created on 2026-06-09 and last pushed on 2026-06-22, indicating rapid early development. loop-audit reached v1.4 with activity detection, loop-init reached v1.2 with budget and run-log support, and loop-cost is also published to npm. The project had accumulated 698 stars and 90 forks within roughly two weeks of creation, according to the GitHub metadata.

## Features
- Seven production loop patterns (Daily Triage, PR Babysitter, CI Sweeper, Dependency Sweeper, Changelog Drafter, Post-Merge Cleanup, Issue Triage)
- loop-audit CLI for loop readiness scoring and suggestions
- loop-init CLI for scaffolding starters with budget and run-log support
- loop-cost CLI for token spend estimation by pattern and cadence
- Clone-and-run starter kits for Grok, Claude Code, and Codex
- Interactive pattern picker on GitHub Pages
- Cross-tool primitives matrix (Grok vs Claude Code vs Codex)
- Machine-readable patterns/registry.yaml
- Loop Design Checklist for ship readiness
- Failure modes catalog, anti-patterns guide, and safety documentation
- MCP connector cookbook examples
- CI workflows that dogfood loop-audit and validate-patterns on every push
- Phased rollout model: L1 report → L2 assisted fixes → L3 unattended
- Memory/state management guidance for durable loop state
- Multi-loop coordination documentation

## Integrations
Grok, Claude Code, Codex, Cursor, GitHub Actions, MCP (Model Context Protocol), npm, Git, GitHub Discussions

## Platforms
WEB, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Version
loop-audit v1.4, loop-init v1.2

## Links
- Website: https://cobusgreyling.github.io/loop-engineering/
- Documentation: https://github.com/cobusgreyling/loop-engineering
- Repository: https://github.com/cobusgreyling/loop-engineering
- EveryDev.ai: https://www.everydev.ai/tools/loop-engineering