Stop prompting. Design the loop. Get a score.
The prevailing paradigm of human-machine interaction relies on a critical structural flaw: the ad-hoc prompt. This high-entropy method assumes that continuous, manual intervention can reliably steer an autonomous computational agent, but in practice, it merely introduces cognitive fatigue, context degradation, and operational drift. To arrest this decay, the architecture must transition from conversational persuasion to deterministic regulation. Loop Engineering eliminates the fragility of human prompting by replacing it with a closed, autonomous control system—a rigorous operational harness where execution is dictated not by improvisation, but by pre-configured, immutable design.
Within this paradigm, computational agency is no longer an open-ended dialogue but a formalized geometric trajectory. An operational loop is initiated by a defined trigger, drawing upon strict contextual boundaries before generating an action internally. This execution is immediately subjected to a harsh verification gate, enacted through an adversarial separation between the subagent that generates and the subagent that validates. Only when this internal admissibility test is satisfied does the system update its state memory and proceed. By confining this entire sequence within isolated worktrees and enforcing explicit constraints, the system achieves true autonomy: the capacity to execute continuously without the liability of human babysitting.
Autonomy, however, is inherently volatile unless bound by unforgiving limits. The architecture secures itself through fail-closed circuit breakers, strict path denylists, and rigid cost ceilings, ensuring that any deviation from the operational contract results in immediate termination rather than compounding error. This structural integrity is never left to assumption; it is quantified through a definitive readiness evaluation. Before any loop is permitted to operate in a production environment, it must prove its transition from an unsafe script into a hardened asset, measured against a strict metric that demands explicit memory contracts, continuous state synchronization, and absolute zero drift.
Ultimately, this operational tooling functions as the mechanical execution of a broader epistemic philosophy. The localized utilities and automated triage patterns are not merely development conveniences; they are the physical manifestation of the realization gate, demanding that developers stop prompting and instead architect the loop itself. By enforcing this strict separation between generative noise and validated consequence, the system ensures that every automated action is anchored in deterministic law. It is an architecture that survives and scales not by expanding the freedom of the agent, but by perfecting the precision of its constraints.
npx @cobusgreyling/loop-init .loop-init scaffolds skills, state, and budget files, then prints your Loop Ready score and first loop command. Swap --tool for claude, codex, or opencode.
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
For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agents.
→ Interactive showcase + pattern picker · Essay · Addy Osmani
- Quickstart (5 min)
- Quick Links
- Why This Matters
- The Five Building Blocks + Memory
- Patterns
- Getting Started (5 minutes)
- Examples by Tool
- Operating & Safety
- Caveats
- Contributing
- Sources
- License
| Start here | Description |
|---|---|
| Quickstart (5 min) | Scaffold → cost check → audit → first loop — start here if you just landed |
| Wiki Portal | Comprehensive systems documentation, primitives, patterns, and safety architecture |
| Loop Engineering essay | The concept, primitives, and Grok mapping — read for the why |
| Pattern Picker | Which loop to run first — start here if unsure |
| Primitives Matrix | Cross-tool loop primitive mapping — bookmark this |
| Loop Design Checklist | Ship readiness rubric |
| Patterns | 7 production patterns + interactive picker |
| Starters | Clone-and-run kits (Grok, Claude Code, Codex, Opencode) |
| Opencode examples | CLI-first loops: cron/systemd + opencode run, skills, worktrees |
| loop-audit | Loop Readiness Score CLI (v1.5 + constraints scoring) — npx @cobusgreyling/loop-audit . --suggest · --badge for README |
| loop-init | Scaffold starters + budget/run-log + constraints (v1.2) — npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok |
| loop-cost | Token spend estimator — npx @cobusgreyling/loop-cost |
| loop-sync | Drift detection between STATE.md and LOOP.md — npx @cobusgreyling/loop-sync . |
| loop-context | Stateful memory manager + circuit breaker for long runs — npx @cobusgreyling/loop-context --check --ledger run.json |
| loop-mcp-server | MCP runtime lookup for patterns, skills, state — npx @cobusgreyling/loop-mcp-server |
| Goal Engineering | Companion: loops discover, goals finish — /goal + stack cookbook (npx @cobusgreyling/goal doctor .) |
| Stories | Real wins and honest failures |
| Contributor quickstart | Help wanted: 12 scoped good first issues — comment I'll take this to get assigned |
| Community update | July 4: 5.5k stars, traffic sources, contributor merges |
| Prior release notes | v1.5.0 — loop-sync, constraints, MCP server |
| Add your project | Pinned: Loop Ready badge + adopters list |
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.
| Primitive | Job in the Loop |
|---|---|
| Automations / Scheduling | Discovery + triage on a cadence |
| Worktrees | Safe parallel execution |
| Skills | Persistent project knowledge |
| Plugins & Connectors | Reach into your real tools (MCP) |
| Sub-agents | Maker / checker split |
| + Memory / State | Durable spine outside any conversation |
Full detail: docs/primitives.md · Cross-tool matrix: docs/primitives-matrix.md
Mermaid diagram (copy-friendly)
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
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.
| Pattern | Cadence | Starter | Week 1 | Token cost |
|---|---|---|---|---|
| Daily Triage | 1d–2h | minimal-loop | L1 report | Low |
| PR Babysitter | 5–15m | pr-babysitter | L1 watch | High |
| CI Sweeper | 5–15m | ci-sweeper | L2 cautious | Very high |
| Dependency Sweeper | 6h–1d | dependency-sweeper | L2 patch-only | Medium |
| Changelog Drafter | 1d or tag | changelog-drafter | L1 draft | Low |
| Post-Merge Cleanup | 1d–6h | post-merge-cleanup | L1 off-peak | Low |
| Issue Triage | 2h–1d | issue-triage | L1 propose-only | Low |
Not sure which to pick? Try the interactive picker or pattern-picker.
Machine-readable index: patterns/registry.yaml (7 patterns)
# 1. Scaffold + get your Loop Ready score (printed automatically)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
# 2. Estimate token spend for your cadence
npx @cobusgreyling/loop-cost --pattern daily-triage --level L1
# 3. Re-audit after improvements
npx @cobusgreyling/loop-audit . --suggest
# Optional: paste Loop Ready badge into your README
npx @cobusgreyling/loop-audit . --badge
# 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.All three CLIs publish to npm from tagged releases — see docs/RELEASE.md. No clone required.
Develop from source (monorepo contributors):
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 15mPhased rollout: L1 report → L2 assisted fixes → L3 unattended — see loop-design-checklist.
- 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
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.”
First PR? Start with the contributor quickstart — ~10 min to ~1 hr tasks with same-day review on stories and adopters. See CONTRIBUTORS.md for everyone who has shipped so far.
| Pick one | Issue |
|---|---|
| ~10 min | #120 — Add your project to adopters |
| ~20 min | #121 — QUICKSTART loop-init --tool values |
| ~1 hr | #118 / #119 — failure stories welcome |
Comment "I'll take this" on any good first issue for assignment.
Share production patterns, tool mappings, and failure stories. See CONTRIBUTING.md (contribution ladder + good first issue backlog), adopters, and GitHub Discussions.
- Cobus Greyling – Loop Engineering (Substack)
- Addy Osmani – Loop Engineering
- Attribution & further reading
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
