Loop Engineering — Stop Prompting Agents, Design the Loop
Loop Engineering — Stop Prompting Agents, Design the Loop
AI coding agents like Claude Code, Grok, and Codex are incredibly powerful — but there's a ceiling on how much you can accomplish by typing one prompt at a time. The industry is shifting from prompting agents to designing systems that prompt agents.
This is loop engineering: the practice of building scheduled, stateful control loops that triage issues, fix bugs, draft changelogs, and sweep dependencies — all without you sitting at the keyboard.
The open-source Loop Engineering toolkit by Cobus Greyling provides CLI tools, production patterns, and scaffold starters to get you running in minutes. It's currently trending on GitHub with over 5,400 stars.
What is Loop Engineering?
The core idea is simple: instead of manually prompting an agent each time, you design a loop — a scheduled automation that:
- Runs on a cadence (every hour, every day, on every PR)
- Reads persistent state from
STATE.md - Executes a specific pattern (triage, fix, sweep, draft)
- Writes results back to state
- Optionally gates risky actions behind a human check
The loop replaces you as the prompter. Your job becomes designing, monitoring, and improving the loop — not typing prompts.
Why It's Trending
Three forces converged to make loop engineering the hottest pattern in AI-assisted development:
-
Boris Cherny (Head of Claude Code at Anthropic) publicly stated: "I don't prompt Claude anymore. I have loops running that prompt Claude. My job is to write loops."
-
Addy Osmani (Google Chrome) published a deep essay on loop engineering, calling it the next evolution of developer productivity.
-
Token economics — running agents manually is expensive. A well-designed loop with proper budget controls costs less and covers more ground.
The reference repo hit 5,400+ stars in under a month.
Prerequisites
- Node.js 18+ (for the npm CLI tools)
- An AI coding agent: Grok, Claude Code, Codex, or Opencode
- A git repository (any project)
Architecture
The loop engineering architecture has four layers:
- Orchestration Layer — scheduled triggers (cron, systemd, GitHub Actions) that wake the loop on a cadence
- State Layer — persistent
STATE.md,LOOP.md, andloop-run-log.mdthat track context across iterations - Skill Layer — reusable pattern skills (triage, babysit, sweep, draft) that encode project knowledge
- Execution Layer — the agent harness (Grok, Claude Code, Codex) running in isolated worktrees with verifier sub-agents
A human gate sits between execution and production — until the loop reaches L3 (unattended), every action requires review.
Getting Started
Step 1: Install Loop Init
No global install needed — run directly with npx:
npx @cobusgreyling/loop-init .This scaffolds the starter files in your project: STATE.md, LOOP.md, loop-budget.md, and loop-run-log.md.
Step 2: Pick a Pattern
The toolkit ships with 7 production patterns:
| Pattern | Cadence | Cost | Purpose |
|---|---|---|---|
| Daily Triage | 1d–2h | Low | Surface priorities daily |
| PR Babysitter | 5–15m | High | Watch open PRs |
| CI Sweeper | 5–15m | Very high | Fix CI failures fast |
| Dependency Sweeper | 6h–1d | Medium | Keep dependencies current |
| Changelog Drafter | 1d or tag | Low | Draft release notes |
| Post-Merge Cleanup | 1d–6h | Low | Clean up after merge |
| Issue Triage | 2h–1d | Low | Organize issue backlog |
For beginners, start with Daily Triage:
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grokSwap --tool for claude, codex, or opencode depending on your agent.
Step 3: Check Token Cost
Before scheduling, estimate what the loop will cost:
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1 --cadence 1dThis prints a token estimate so you can adjust cadence or pattern before committing to a schedule.
Step 4: Audit Your Setup
Run the built-in audit to get a Loop Readiness Score:
npx @cobusgreyling/loop-audit . --suggestScores range from 0–100. Aim for L1 (~40+) in week one by following the concrete suggestions printed by the audit.
Step 5: Run Your First Loop
For Grok:
/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.For Claude Code:
/loop 1d Run $loop-triage. Read STATE.md. Merge findings into High Priority and Watch List. Update Last run. Do not edit code.Week one rule: report only. No auto-fix, no auto-merge. Read what the loop writes before you let it act.
Configuration
Loop Budget
The loop-budget.md file controls token spending:
# Budget
- Max tokens per run: 100,000
- Max cost per day: $2.00
- Cadence: 1d
- Level: L1 (report only)Loop Design Levels
| Level | Behavior | When |
|---|---|---|
| L1 | Report only | Week 1 — read everything |
| L2 | Assisted fixes | Week 2+ — verifier gate |
| L3 | Unattended | Proven runs only |
Custom Skills
You can write custom skills in skills/ directory. A skill is a markdown file with instructions for the agent:
# Skill: my-custom-triage
Run every 6 hours. Check logs for error spikes.
If error rate > 5%, escalate to human.
Write findings to STATE.md under "Errors".Phased Rollout Strategy
The recommended rollout follows three phases:
- Week 1 (L1): Scaffold, audit, run report-only loops. Read every output. Tune your
LOOP.mdandSTATE.md. - Week 2 (L2): Add a verifier sub-agent. Let the loop suggest fixes in isolated worktrees. Review before merge.
- Week 3+ (L3): If runs are clean and budgets hold, remove human gates for allowlisted actions.
Verification Checklist
npx @cobusgreyling/loop-audit . --suggestreturns score ≥ 40STATE.mdandLOOP.mdexist in project root- Loop-budget is set and matches your token limits
- Week one runs report-only (no auto-fix)
- You understand the failure modes in
docs/failure-modes.md
Resources
- GitHub Repository: github.com/cobusgreyling/loop-engineering
- Interactive Showcase: cobusgreyling.github.io/loop-engineering
- Loop Engineering Essay: cobusgreyling.substack.com/p/loop-engineering
- Addy Osmani's Essay: addyosmani.com/blog/loop-engineering
- NPM Package: npmjs.com/package/@cobusgreyling/loop-init
- License: MIT