Loop Engineering
Design, scaffold, score, and operate repeatable loops for AI coding agents.
Per-dimension scores and reasoning
Evidence shows: README and SECURITY.md explicitly discuss least privilege (MCP read-only, denylist), user confirmation (L1 reports, human gates), data flow transparency (STATE.md no secrets), sensitive data handling (denylist .env), external effects (auto-merge restrictions), rollback (worktree isolation). However, dependency security only mentions supply-chain risks without evidence of audits or lockfiles; rollback mechanism only mentions worktrees without specific recovery procedures. Therefore deductions: insufficient evidence for dependency security, weak evidence for rollback.
Evidence shows: README and package.json indicate test scripts for multiple tools, but no test results or coverage; dependency availability implied by npm publishing and CI workflows, but not verified; failure messages mentioned in SECURITY.md and docs/failure-modes.md, but no concrete examples. Therefore deductions: insufficient test evidence, lack of specific failure messages.
Evidence shows: README details multiple tools (Grok, Claude Code, Codex, etc.) and scenarios (daily-triage, PR babysitter, etc.) with a pattern picker; capability boundaries defined via L1-L3 phases and denylist; trigger precision via pattern cadence and CLI arguments; environment fit via GitHub Actions and npm packages. Therefore deductions: capability boundaries and trigger precision rely on documentation claims without actual configuration examples.
Evidence shows: README provides clear information architecture (table of contents, quick links), install notes (npx commands), naming stability (multiple npm packages), examples and FAQ (docs/QUICKSTART.md), known limitations (Caveats section), MIT license, versioning via discussion release notes, and maintenance responsibility via CONTRIBUTING.md. Therefore deductions: insufficient evidence for versioning and changelog, maintenance responsibility not explicitly assigned.
Evidence shows: output usability via CLI output and documentation; marginal value via pattern comparisons and cost estimates; cost-benefit via token cost estimates and L1-L3 phases. Therefore deductions: no actual output examples, no real cost data.
Evidence shows: claim traceability via cited sources (Addy Osmani, Boris Cherny) and documentation; cross-source corroboration via multiple sources (Substack, blog) and community discussions; fact-inference separation via documentation distinguishing concepts and patterns. Therefore deductions: insufficient cross-source evidence, fact-inference separation not explicitly stated.
- Insufficient evidence for dependency security: no dependency audits or lockfiles, supply-chain risks only mentioned.
- Weak evidence for rollback: only mentions worktree isolation, no specific recovery procedures.
- Insufficient test evidence: package.json has test scripts, but no test results or coverage.
- Insufficient evidence for versioning and changelog: only via discussion release notes, no formal CHANGELOG.
What does this agent do, and when should you use it?
Loop Engineering is a reference repository and CLI suite for designing AI coding-agent loops, rather than a single hosted agent. It includes seven production patterns, starters for Grok, Claude Code, Codex, and Opencode, plus GitHub Actions examples. The unified `@cobusgreyling/loop` CLI initializes projects, runs health checks, reports status, audits loop readiness, and estimates cost, while the older individual packages remain supported. Its model is to put skills, durable state, budget files, constraints, and optional worktree isolation into a project, then advance from L1 reporting through L2 assisted fixes to L3 unattended operation. It produces a Loop Ready score, a first loop command, prioritized doctor actions, and outputs for status, cost, and drift checks. The repository is MIT licensed and also ships composable MCP lookup, worktree, gate, and GitHub Composite Action components.
Running npx @cobusgreyling/loop init . --pattern daily-triage --tool grok scaffolds skills, state, and budget files, then prints a Loop Ready score and first loop command. npx @cobusgreyling/loop doctor . combines audit, sync, and file checks into the top three next actions; loop audit, loop cost, loop badge, and loop status expose readiness review, cost estimation, badge generation, and status views. loop-sync detects drift between STATE.md and LOOP.md, while loop-context --check --ledger run.json supplies stateful memory management and a circuit breaker for long runs. loop-worktree manages isolated Git worktrees per fix attempt, loop-mcp-server looks up patterns, skills, and state, and loop-gate mechanically checks a gate.yaml path denylist and auto-merge allowlist.
- A team introducing Codex or Claude Code can scaffold Daily Triage and begin with an L1 report-only loop for recurring repository triage.
- A maintainer responsible for a busy pull-request queue can use the PR Babysitter pattern to watch PR activity every 5–15 minutes after assessing its high token cost.
- An engineer maintaining a flaky CI system can use the CI Sweeper starter to structure a 5–15 minute loop and phase in cautious L2 fixes.
- A dependency owner who needs recurring update work can adopt Dependency Sweeper for a patch-only L2 maintenance workflow.
- A team that wants each automated fix attempt isolated from the main checkout can use
loop-worktree create --run-id <id> --pattern <p>to manage Git worktrees.
What are this agent's strengths and limitations?
- The unified
@cobusgreyling/loopfront door combines init, doctor, status, audit, and cost while retaining the older packages for existing forks. - Seven named patterns are mapped to cadence, initial autonomy level, starter kit, and token-cost expectations.
- The toolkit goes beyond templates with
loop-sync,loop-context,loop-worktree,loop-gate, and an MCP server for drift detection, long-run state, isolation, and enforcement. - It documents a concrete adoption path from L1 reports to L2 assisted changes and L3 unattended loops.
- The project explicitly warns that sub-agents and long-running loops can rapidly increase token spending, especially for PR Babysitter and CI Sweeper.
- Verification remains the operator's responsibility, and unattended loops can make unattended mistakes.
- Adoption requires maintaining state, budgets, constraints, gates, and scheduling rather than relying on one-off prompts.
- The supplied material does not specify a Node.js version, credential setup, or complete runtime requirements for each supported coding tool.
How do you install or deploy this agent?
From the target project in a shell, use npx without cloning the repository: npx @cobusgreyling/loop init . --pattern daily-triage --tool grok. Then run npx @cobusgreyling/loop doctor . to check the result. Replace --tool with claude, codex, or opencode as needed. The supplied material does not state a Node.js version or required credentials, so the selected coding tool's installation, authentication, and credentials must be available in the execution environment.
How do you use this agent?
Start with npx @cobusgreyling/loop init . --pattern daily-triage --tool codex, then review the generated files, Loop Ready score, and first loop command. Run npx @cobusgreyling/loop doctor . to receive the combined audit, sync, and file-check recommendations. For budget planning, run npx @cobusgreyling/loop cost --pattern daily-triage --level L1; begin with L1 reporting and move to L2 assisted fixes or L3 unattended operation only when appropriate.
FAQ
Does it directly run my coding agent for me?
How can I control cost and autonomy?
loop cost to estimate a pattern and adopt the documented L1 report, L2 assisted-fix, then L3 unattended progression. The project recommends starting report-only in week one.Can it prevent sensitive changes or unsafe auto-merges?
loop-gate checks a gate.yaml path denylist and auto-merge allowlist. The documented safety material also addresses denylists, auto-merge, and MCP scopes.How is context handled across long-running loops?
loop-context --check --ledger run.json provides stateful memory management and a circuit breaker. The design also uses STATE.md as durable state, with loop-sync checking it for drift against LOOP.md.