Stop prompting. Design the loop. Get a score.
Project owner: Darrell Mesa (darrell.mesa@pm-ss.org) · https://eli-labz.com/
⭐ If Looping saves you time, a star helps others find it
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.
Looping 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
| Feature | What it does |
|---|---|
| loop-sync v1.0.0 | Detects drift between STATE.md and LOOP.md — catches loops that wander off design |
| Constraints scoring | loop-audit now scores budget caps, denylist completeness, and human-gate coverage |
| MCP server (v1) | Runtime lookup for patterns, skills, and state over MCP |
| Task Families | New text-tasks/ and human-action-tasks/ templates for staged rollout |
| Physical-World Boundaries | Supervisor-friendly rollout guide for loops that touch the physical world |
- Quickstart (5 min)
- Quick Links
- Why This Matters
- The Five Building Blocks + Memory
- Patterns
- Task Families
- 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 |
| Looping 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 |
| Task Families (text + human-action) | New task-family templates for text tasks and supervised human-action workflows |
| Token Schemas | Observation/action/outcome/state schemas for auditable loop runtime |
| Core Loop Runtime | Observe → plan → risk-gate → execute → verify → trace → recover/escalate |
| 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-mcp-server | MCP runtime lookup for patterns, skills, state — node tools/mcp-server/dist/index.js (repo v1; npm pending) |
| Goal Engineering | Companion: loops discover, goals finish — /goal + stack cookbook (npx @cobusgreyling/goal doctor .) |
| Stories | Real wins and honest failures |
| Community update | v1.5.0 release — 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)
New family folders for staged capability rollout:
- Text Tasks - summarize, classify, draft, compare, extract
- Human-Action Tasks - browser, spreadsheet, email, and supervised physical-world routing
Runtime token models and schemas:
- TypeScript token model
- Observation token schema
- Human-action token schema
- Outcome token schema
- Looping agent state schema
# 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
- Governance — reliability metrics as product features
- Risk Gates — allow/block/escalate policy checks
- Human Approval — explicit sign-off for high-impact actions
- Action Ledger — auditable observation/action/outcome trace
- Physical-World Boundaries — supervised, simulator-friendly rollout
Looping 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.”
Share production patterns, tool mappings, and failure stories. See CONTRIBUTING.md, adopters, and GitHub Discussions.
MIT
Practical, tool-aware reference for Looping, patterns you can clone, checklists you can ship against, and stories that include what broke.