Loop Engineering

Stop prompting. Design the loop. Get a score.

Start in 5 minutes · Quickstart · Pattern picker · Contribute · ⭐ Star

_{If this repo changed how you run agents, a star helps others find the patterns. Docs & small PRs: we aim to review within 48 hours.}

# One front door — init + doctor + status
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop doctor .

loop init scaffolds skills, state, and budget files, then prints your Loop Ready score. loop doctor turns audit + sync into top-3 next actions. Swap --tool for claude, codex, or opencode. Optional: --with-foundry for a versioned harness stack. Legacy npx @cobusgreyling/loop-init . still works. See docs/cli-front-door.md.

Loop engineering replaces you as the person who prompts the agent — you design the system that does it instead.

New here? Quickstart (5 min) · Interactive picker · Help wanted

For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agents.

→ Interactive showcase + pattern picker · Essay · Addy Osmani

Contents

• Quickstart (5 min)
• Quick Links
• Why This Matters
• The Five Building Blocks + Memory
• Patterns
• Getting Started (5 minutes)
• Examples by Tool
• Operating & Safety
• Caveats
• Help wanted
• Contributing
• Sources
• License

Quick Links

Ecosystem stack

memory-engineering → loop-engineering → harness-foundry → outerloop → fleet-engineering
   (persist)            (patterns)         (runtime)        (verdict)     (population)

Scale beyond one loop: when agents forget across sessions, add memory-engineering. When you have many agents/loops on a team, add fleet-engineering.

Next after Loop Ready 80+: version the loop as a harness — loop-init prints the CTA automatically; loop-audit recommends Foundry when the score is strong but .foundry/stack.yaml is missing.

Community & announcements

Why This Matters

Peter Steinberger:

“You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents.”

Boris Cherny (Head of Claude Code at Anthropic):

“I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops.”

The leverage point has moved from crafting individual prompts to designing the control systems that orchestrate agents over time.

The Five Building Blocks + Memory

Full detail: docs/primitives.md · Cross-tool matrix: docs/primitives-matrix.md

Visual Overview

Anatomy of a Loop

flowchart LR
    A[Schedule / Automation] --> B[Triage Skill]
    B --> C[Read + Write STATE / Memory]
    C --> D[Isolated Worktree]
    D --> E[Implementer Sub-agent]
    E --> F[Verifier Sub-agent<br/>tests + gates]
    F --> G[MCP / Git / Tickets]
    G --> H{Human Gate?}
    H -->|safe / allowlisted| I[Commit / PR / Action]
    H -->|risky / ambiguous| J[Escalate to human<br/>with full context]
    I --> A
    J --> A

Deeper diagrams — the actor-level sequence within one run, the run lifecycle's states, autonomy levels L1-L3, and how tools/ maps onto the primitives — live in docs/architecture-diagrams.md.

This reference repo now runs its own validate-patterns + audit workflows on every push/PR (see .github/workflows/). We also added LOOP.md describing the loops that will maintain it.

Patterns

Not sure which to pick? Try the interactive picker or pattern-picker.

Machine-readable index: patterns/registry.yaml (7 patterns)

Getting Started (5 minutes)

# 1. Scaffold + Loop Ready score (printed automatically)
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok

# 2. One health check (audit + sync + files → top 3 actions)
npx @cobusgreyling/loop doctor .

# 3. Optional: cost estimate / badge / day-2 dashboard
npx @cobusgreyling/loop cost --pattern daily-triage --level L1
npx @cobusgreyling/loop badge .
npx @cobusgreyling/loop status .

# 4. See scores climb: empty → L1 → L2
bash scripts/before-after-demo.sh

# 5. Start report-only (Grok example)
/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.

Same as before: npx @cobusgreyling/loop-init and loop-audit still work — CLI front door.

All npm CLIs publish from tagged releases — see docs/RELEASE.md. No clone required.

Develop from source (monorepo contributors):

cd tools/loop && npm ci && npm test && node dist/cli.js doctor ../..
cd tools/loop-init && npm ci && npm test && node dist/cli.js /path/to/project --pattern daily-triage --tool grok
cd tools/loop-audit && npm ci && npm test && node dist/cli.js /path/to/project --suggest
cd tools/loop-cost && npm ci && npm test && node dist/cli.js --pattern ci-sweeper --cadence 15m

Phased rollout: L1 report → L2 assisted fixes → L3 unattended — see loop-design-checklist.

Examples by Tool

• Grok
• Claude Code
• Codex
• OpenClaw
• Opencode
• GitHub Actions

Operating & Safety

• Failure Modes — incident-style catalog
• Anti-Patterns — design mistakes before production
• Multi-Loop Coordination — when loops collide
• Operating Loops — cost, logging, when to kill
• Safety — denylist, auto-merge, MCP scopes
• Security — reporting and unattended automation risks
• Concepts — intent debt, comprehension debt, harness vs loop
• MCP Cookbook — connector examples by pattern

Caveats

Loop engineering amplifies judgment — both good and bad.

• Token costs can explode with sub-agents and long-running loops.
• Verification is still on you. Unattended loops make unattended mistakes.
• Comprehension debt grows faster unless you read what the loop ships.
• Two people can run the same loop and get opposite results. The loop doesn't know. You do.

Addy Osmani:

“Build the loop. But build it like someone who intends to stay the engineer, not just the person who presses go.”

Help wanted

First PR? Pick an open issue below, or Add Adopter / Share a story.

Review SLA: docs, stories, adopters, and small tests — within 48 hours (same-day when possible). See CONTRIBUTORS.md and the contributor quickstart.

good first issue backlog (comment "I'll take this" for assignment). Prefer the live filter if a row below looks stale.

Recently shipped (thanks!): @AIMindCrafter — Windows/CRLF notes (#492), Windsurf Post-Merge Cleanup (#494), Windsurf Changelog Drafter (#495). @pxmpsdev — loop-sync CRLF tests (#496), readiness skill-dedup (#497), append-run-log invalid-JSON (#498), metrics unparseable run_id (#499). @shixi-li — Hermes CI Sweeper example (#500).

Docs/examples triage: @AIMindCrafter co-owns docs/, examples/, and stories/ (see CODEOWNERS + docs/area-owners.md).

Maintainers re-seed the backlog with bash scripts/create-good-first-issues.sh (idempotent; skips existing titles). Prefer live open GFI filter over this table if a row looks stale.

Contributing

Share production patterns, tool mappings, and failure stories. See CONTRIBUTING.md (ladder + setup), Code of Conduct, adopters, and hubs: Show your loop · Ask anything.

We aim to first-respond within 48 hours on external PRs. Start here: good first issue · Help wanted.

Sources

• Cobus Greyling – Loop Engineering (Substack)
• Addy Osmani – Loop Engineering
• Attribution & further reading

License

MIT

Practical, tool-aware reference for loop engineering, patterns you can clone, checklists you can ship against, and stories that include what broke.

Essay · Showcase · Cobus Greyling

_{Static chart (CI-updated daily). Live chart needs a GitHub token — stored in your browser only.}