Stop typing prompts. Start designing systems that prompt.
Automate repetitive coding tasks with AI agents. Set up once, run forever.
An MCP server that brings loop engineering to your AI coding workflow. Instead of manually prompting your AI agent for every task, you design loops that prompt the agent for you. Each loop implements the canonical loop-engineering control system:
- 🔄 Run automatically on a schedule (the heartbeat)
- 🔁 Iterate until the goal is verifiably met — act → verify → decide → repeat
- 🧑🔧 Maker/checker separation — the agent makes changes; an independent checker gate decides whether the goal is met (the agent never grades its own homework)
- 🛑 Stop rules — escalate to a human after N attempts or on a repeated failure (no Ralph-Wiggum runaway loops)
- 🌳 Worktree isolation — each run gets its own git worktree so parallel loops never collide
- 💸 Budget caps — daily run limits and a cumulative cost ceiling
- 🧠 Durable memory — state file with run history and lessons learned that survives restarts
- 🧪 Suitability test — a 4-condition pre-flight check so you only automate loop-shaped work
Think of it as: GitHub Actions + AI Agents + an Intelligent, Self-Verifying Control Loop
You: "Check CI failures" [5 minutes]
AI: [reports failures]
You: "What caused the auth test failure?" [3 minutes]
AI: [investigates]
You: "Fix it" [10 minutes]
AI: [writes fix]
You: "Open a PR" [2 minutes]
AI: [creates PR]
Total: 20 minutes × 4 times/day = 80 minutes/day
[You set up once: "Create a CI triage loop, run every 6 hours"]
Loop automatically:
✅ Detects failures
✅ Classifies (flake vs bug vs env issue)
✅ Drafts fixes for deterministic bugs
✅ Runs tests
✅ Opens PRs
✅ Escalates complex issues
✅ Records lessons learned
Total: 0 minutes/day (runs while you sleep)
Real Impact:
- ⚡ 80% faster - Loops run in parallel, don't need your attention
- 🎯 Higher quality - Consistent checks, learns from past mistakes
- 💰 Cost effective - Only runs when needed, tracks ROI
- 😴 Works 24/7 - Runs while you sleep, on weekends
- CI Triage - Classify failures, draft fixes, escalate blockers
- Dependency Updates - Check for updates, test compatibility, create PRs
- Lint & Format - Apply automated fixes on every PR
- Documentation Sync - Keep docs updated with code changes
- Flaky Test Detection - Identify and track intermittent failures
- Security Patches - Auto-apply safe security updates
- Architecture decisions (requires judgment)
- Auth/payment code (too risky)
- Production deployments (needs human oversight)
- Vague product work (unclear success criteria)
Pick one of the following. Both work with the MCP config templates in Setup below.
Install uv, then run the server from PyPI — no separate pip install needed:
uvx loop-mcpUse the uv MCP template (command: uvx) in Step 1.
pip install loop-mcpVerify it is on your PATH:
loop-mcpUse the pip MCP template (command: loop-mcp) in Step 1.
Clone and install:
# Clone repository
git clone https://github.com/yourusername/loop-engineering
cd loop-engineering
# Install Python package
cd python
pip install -e ".[dev]"Create or edit .cursor/mcp.json in your project.
uv (Option 1 — uvx fetches loop-mcp from PyPI automatically):
{
"mcpServers": {
"loop-engineering": {
"command": "uvx",
"args": ["loop-mcp"]
}
}
}pip (Option 2 — after pip install loop-mcp):
{
"mcpServers": {
"loop-engineering": {
"command": "loop-mcp"
}
}
}Create or edit .kiro/settings/mcp.json — same templates as Cursor above (uv or pip).
Mac: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: Edit %APPDATA%\Claude\claude_desktop_config.json
Use the same uv or pip template as Cursor above.
Local development? Use:
{
"command": "python",
"args": ["-m", "loop_engineering_mcp"]
}- Cursor: Reload window (Cmd/Ctrl + R)
- Kiro: Reconnects automatically
- Claude Desktop: Restart application
Open your AI agent and say:
Create a CI triage loop that runs every 6 hours
The AI will set up everything automatically.
You: "Create a CI triage loop"
AI: ✅ Loop 'ci-triage' created!
Schedule: Every 6 hours
Verification: npm test
Goal: All CI failures classified
Files created:
- .loop/loops.json (configuration)
- .loop/skills/ci-triage.md (instructions)
- .loop/state/ci-triage.json (state tracking)
You: "Start it"
AI: ✅ Loop started and will run automatically
You: "What loops are running?"
AI: 📊 Active loops:
ci-triage
- Last run: 2 hours ago
- PRs today: 3 (2 merged)
- Acceptance rate: 67%
- Token cost today: $4.20
You: "Show me ci-triage state"
AI: 📊 State for ci-triage:
Last 5 runs:
- 2h ago: Classified 3 failures, opened 2 PRs
- 8h ago: All tests passing, no action needed
- 14h ago: Fixed flaky auth test, escalated DB issue
Lessons learned:
- Auth tests need AUTH_SECRET env var
- E2E tests require Stripe webhook config
Once installed, your AI agent gets these tools:
| Tool | Purpose |
|---|---|
check_loop_suitability |
Run the 4-condition test before building a loop |
create_loop |
Set up a new loop (checker gate, stop rules, budgets, isolation) |
start_loop |
Start/resume a loop (activates the scheduler) |
stop_loop |
Pause a loop |
run_loop_now |
Begin a run — returns the brief for the host agent to execute |
complete_loop_run |
Submit an attempt (the loop body): runs the checker, opens a PR, iterates, or escalates |
list_pending_runs |
Show runs the scheduler queued for the next agent session |
run_verification |
Run a loop's verification command on demand |
set_goal_check |
Set/update the independent checker gate |
configure_verification |
Set/update the maker self-check command |
list_loops |
View all loops and their status |
delete_loop |
Remove a loop permanently |
add_skill / list_skills |
Manage reusable skill templates |
view_state |
Check loop history, attempts, and metrics |
add_lesson |
Record learnings for future runs |
get_metrics |
See overall performance |
Your AI agent uses these automatically when you ask for loop-related tasks.
run_loop_now ──► brief (goal, working dir, stop rule)
│
▼
agent makes the smallest change
│
▼
complete_loop_run ──► maker self-check ──► independent checker gate
│ │
│ ┌───────────┴───────────┐
│ goal met? not yet
│ │ │
▼ ▼ ▼
open PR & stop open PR & stop attempts left? ── yes ─► iterate (same run_id)
│
no / repeated failure
▼
escalate to human
# Navigate to python package
cd python
# Install in development mode
pip install -e ".[dev]"
# Run MCP server
loop
# Run background worker (optional - for scheduled execution)
loop-worker
# Run tests
pytest
# Run tests with coverage
pytest --cov- Install locally (commands above)
- Configure in your AI agent (see Setup section)
- Test with your AI agent:
"Do you have loop-engineering tools?" "Create a test loop" "List all loops"
loop-engineering/
├── python/ # Python MCP server
│ ├── src/
│ │ └── loop_engineering_mcp/
│ │ ├── server.py # MCP server
│ │ ├── loop_manager.py # Loop CRUD
│ │ ├── skill_manager.py # Skill templates
│ │ ├── state_manager.py # State tracking
│ │ ├── loop_executor.py # Control loop: isolation, checker gate, stop rules
│ │ ├── scheduler.py # Cron scheduler (the heartbeat)
│ │ ├── suitability.py # 4-condition loop suitability test
│ │ ├── verification_runner.py # Maker/checker gate runner
│ │ ├── github_client.py # GitHub integration
│ │ └── worker.py # Background worker
│ └── tests/
│
├── shared/ # Shared skill templates
│ └── skills/
│ ├── ci-triage.md
│ ├── dependency-updates.md
│ └── lint-fixes.md
│
└── references/ # Documentation
├── README.md # Full loop engineering guide
├── FRAMEWORK.md # Complete implementation guide
└── QUICKSTART.md # 5-minute setup
Loop engineering (Addy Osmani / Codez / O'Reilly, 2026) defines a loop as a small control system with six parts. This server maps to all six:
| Building block | What it means | How this server does it |
|---|---|---|
| Automations | The heartbeat that triggers runs | Cron scheduler (scheduler.py) queues runs on a schedule |
| Worktrees | Isolated dirs so parallel agents don't collide | Each run gets its own git worktree (isolation: "worktree") |
| Skills | Reusable project knowledge read every run | .loop/skills/*.md, injected into every run brief |
| Connectors | Tools to reach real systems | MCP itself + GitHub PR client |
| Sub-agents (maker/checker) | A separate verifier grades the work | Independent goal_check_command gate, distinct from the maker's self-check |
| Memory/State | Durable state across runs | .loop/state/*.json with runs, attempts, lessons, budgets |
Plus the safety rules that separate a real loop from a cron job: an iterate-until-goal cycle, stop rules (max attempts + no-progress detection), budget caps, and a 4-condition suitability test before you build at all.
Automatically classifies CI failures and drafts fixes:
- Flakes - Retry once, file issue if persists
- Bugs - Draft fix PR immediately
- Env issues - Escalate with clear instructions
- Dependency issues - Draft rollback PR
Keeps packages up-to-date safely:
- Checks for outdated packages
- Tests compatibility
- Creates PRs for safe updates
- Flags breaking changes for review
Maintains code quality automatically:
- Applies automated formatting
- Verifies no logic changes
- Runs tests before committing
- Opens clean-up PRs
"0 */6 * * *" # Every 6 hours
"0 9 * * 1" # Mondays at 9am
"0 0 * * *" # Daily at midnight
"*/30 * * * *" # Every 30 minutes
A loop has two gates. The maker self-check (verification_command) is the fast
check the agent runs after its changes. The independent checker
(goal_check_command) is a separate, objective command that decides whether the
goal is actually met — so the agent that wrote the code is not the one grading it.
A PR is opened only when both pass.
{
"verification_command": "npm test",
"goal_check_command": "npm run test:integration && npm run lint"
}{
"max_attempts": 3, // escalate to a human after 3 failed attempts
"max_runs_per_day": 24, // daily run cap (heartbeat budget)
"cost_budget": 5.00, // cumulative USD token-cost ceiling (0 = unlimited)
"isolation": "worktree" // "worktree" (isolated, parallel-safe) or "branch"
}The loop also performs no-progress detection: if the same failure occurs twice in a row it escalates immediately rather than burning tokens on a dead end.
# Optional: GitHub integration
export GITHUB_TOKEN="ghp_..."
# Optional: Custom workspace
export LOOP_WORKSPACE="/path/to/project"- QUICKSTART.md - 5-minute setup guide
- FRAMEWORK.md - Complete implementation guide with examples
- references/README.md - Loop engineering concepts and theory
- CONTRIBUTING.md - How to contribute
- PROJECT_STRUCTURE.md - Architecture details
# Check if installed
loop-mcp --version- Verify MCP config is valid JSON
- Check command path is correct
- Restart your AI agent
- Check AI agent logs for errors
# Unix/Mac
chmod -R u+w .loop/
# Windows
icacls .loop /grant Users:F /TQ: Do I need an API key?
A: No! Your AI agent (Cursor/Kiro/Claude) already has its own API key. This MCP server just provides tools.
Q: Does it work offline?
A: The MCP server works offline, but loop execution needs internet (to call AI APIs, create PRs, etc.)
Q: What about security?
A: Loops never auto-merge to main. Human review required. Verification gates prevent bad code.
Q: Can I use my own AI model?
A: Yes! Works with any AI agent that supports MCP (Cursor, Kiro, Claude Desktop, etc.)
Q: How much does it cost?
A: The MCP server is free. You only pay for AI API usage (same as manual prompting, but more efficient).
- Author: Codez (@0xCodez)
- Article: 14-Step Roadmap
- Based on: Anthropic engineering docs, Addy Osmani's research
- License: MIT
- Repository: GitHub
- Developed by: Anthropic
- Docs: modelcontextprotocol.io
- 📖 Documentation: FRAMEWORK.md
- 🐛 Report Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 🚀 Quick Start: QUICKSTART.md
- Install the MCP server (1 command)
- Configure your AI agent (add JSON config)
- Create your first loop ("Create a CI triage loop")
- Monitor performance (acceptance rates, time saved)
- Iterate based on learnings
Build the loop. Stay the engineer. 🚀
⭐ If this saves you time, give us a star on GitHub!
Made with ❤️ by the Loop Engineering community