Loop Engineering: GitHub Repo Patterns for AI Coding Agents

Repository Summary

The

repository collects patterns, starters, and tooling for designing loops that orchestrate AI coding agents. It draws from ideas by Addy Osmani and Boris Cherny at Anthropic. The project supplies a LOOP.md definition, a primitives matrix comparing models, seven production patterns, and CLI tools for auditing and initialization. The content focuses on replacing manual prompting with recursive control systems that manage goals, verification, and handoff.

Core Concepts from the Documentation

Loop engineering centers on recursive goals. A developer defines a purpose, then the system iterates through sub-agents, state checks, and verification steps until completion or explicit handoff. The repository distinguishes this from single-prompt interactions by treating the loop itself as the primary artifact.

The five building blocks listed in the docs include memory, verification, budgeting, logging, and routing. Memory tracks prior outputs across iterations. Verification runs tests or static checks before accepting changes. Budgeting caps token spend per loop. Logging records each step for later review. Routing decides when to spawn sub-agents or escalate to a human.

The LOOP.md file provides a formal grammar for these elements. It specifies how a loop declares its exit conditions and what external state it may read or write. STATE.md complements this by defining the schema for persistent data that survives individual runs.

Patterns, Starters, and CLI Tools

Seven patterns ship with the repository. They cover daily triage, feature implementation, bug triage, documentation updates, dependency audits, test generation, and migration scaffolding. Each pattern includes a template that wires the required primitives together.

Starters exist for Grok, Claude Code, and Codex. Running the loop-init command scaffolds a new directory with the chosen pattern, a budget file, and a run log. The command accepts flags for the target model and the specific pattern name.

Three npm packages accompany the repo. The loop-audit tool scans a codebase for loop readiness and suggests missing primitives. The loop-cost estimator projects token usage from a given pattern description. The loop-init package handles the scaffolding step. All three are invoked via npx and write JSON output that downstream scripts can consume.

A primitives matrix compares model capabilities across the supported agents. It rates each model on context length, tool-calling reliability, and cost per token. Developers can use the matrix to select the right agent for a given loop step without manual trial and error.

Trade-offs When Adopting These Patterns

The approach shifts effort from prompt writing to loop specification and monitoring. This reduces repetitive prompting but introduces new failure modes: loops can enter infinite retries if verification thresholds are set too high, or they can produce low-quality output if the budget cuts iterations short.

Integration with Node.js or Python projects requires wiring the loop outputs into existing build pipelines. The run logs are plain JSON, so they fit into standard CI artifacts. However, the repository does not supply adapters for Rails or Next.js deployment hooks, leaving that mapping to the implementer.

The audit CLI currently detects only surface-level signals such as the presence of tests and type definitions. It does not yet analyze runtime behavior or security boundaries. Teams that need deeper checks must extend the tool or combine it with separate static analysis passes.

Budget enforcement relies on the calling script to enforce limits after the fact. The estimator gives projections but does not intercept live API calls. Production use therefore requires an additional wrapper that tracks cumulative spend and aborts when thresholds are crossed.

FAQs

What is the difference between a loop and a single agent call? A loop maintains state across multiple agent invocations, applies verification gates, and decides routing or handoff automatically. A single call returns once and leaves all orchestration to the developer.

Can the provided starters run without modification in a Next.js project? The starters produce plain Node scripts and JSON configuration. They require an additional step to invoke them from a Next.js API route or build script.

How does the loop-audit tool determine readiness? It scans for files matching known patterns such as tests, type definitions, and CI configuration, then assigns a numeric score based on coverage of the five primitives.

---

📖 Related articles

• Agentic Coding: Una Trappola per lo Sviluppo Software?
• File agents.md: utili per gli agenti di coding?
• Phantom su GitHub: L'AI co-worker auto-evolvente e sicuro