A lightweight Node.js CLI for running Ralph-style coding agent loops with durable state, guardrails, and logs.
Transform fragile single-run agent executions into controlled, repeatable loops.
- Why Loopy?
- Key Features
- Installation
- Quick Start
- Common Workflows
- How It Works
- Documentation & Examples
- Contributing
- License
Running coding agents on complex tasks can be unpredictable. They might stop mid-task, fail unexpectedly, or lose track of progress. Loopy solves this by wrapping any agent CLI and providing:
- 🔁 Automatic iteration control — Run your agent repeatedly until the task is complete
- 💾 Durable state management — Never lose progress, resume anytime
- 🛡️ Built-in guardrails — Detect and prevent infinite loops, drift, and errors
- 📊 Complete visibility — Full logs, status tracking, and progress monitoring
- 🌿 Git integration — Automatic branching and commits with meaningful messages
Perfect for: Feature development, refactoring, bug fixes, test writing, and any multi-step coding task that benefits from agent persistence.
| Feature | Description |
|---|---|
| Zero-Config Start | Run loopy and answer prompts — no setup files required |
| Plan-Driven Execution | Track progress with markdown checklists |
| Failure Recovery | Resume from where you left off, even after crashes |
| Phase Management | Organize work into plan → implement → verify phases |
| Smart Rotation | Automatically rotate context to prevent token bloat |
| Test Integration | Run tests between iterations to validate progress |
| Git Automation | Auto-commit with semantic messages, branch management |
| Agent Agnostic | Works with any CLI that accepts stdin prompts |
npm install -g loopygit clone https://github.com/yourusername/loopy.git
cd loopy
npm install
npm linkRequirements:
- Node.js 18+
- A git repository (for your project)
- An agent CLI that accepts prompts via stdin (e.g.,
cursor-agent,copilot)
Just run loopy — that's it! No configuration files needed upfront.
loopyIf no plan exists, Loopy starts in plan mode and asks for a seed; otherwise it runs build mode.
Loopy also includes AGENTS.md and a specs/ summary in each prompt. If AGENTS.md is missing, it bootstraps one in the project root (unless --no-bootstrap-agents is set).
Loopy will interactively guide you through:
- 🤖 Agent command — Select or enter your agent CLI (e.g.,
cursor-agent,copilot --allow-all) - 📝 Task description — Describe what you want to build or fix
- 🌿 Git branch — Choose a branch name (optional but recommended)
That's all you need to get started!
Provide everything via command-line flags for automation or scripting:
loopy \
--agent "copilot --allow-all" \
--prompt "Add authentication middleware with JWT support" \
--git-branch "loopy/add-auth"# Feature development
loopy --agent "copilot --allow-all" \
--prompt "Add OAuth2 authentication with Google provider"
# Bug fix
loopy --agent "cursor-agent" \
--prompt "Fix memory leak in the WebSocket handler"
# Refactoring
loopy --agent "copilot" \
--prompt "Convert all class components to functional components with hooks"loopy --resumePicks up exactly where you left off using
.loopy/state.json. Perfect for continuing after crashes, breaks, or manual stops.
# Test with a single iteration
loopy --max-iterations 1
# Run 5 iterations then pause
loopy --max-iterations 5 --resumeloopy statusDisplays: iteration count, current phase, last status, test results, errors, output size, and timestamps.
loopy --mode plan --prompt @examples/feature-prd.mdUse the PRD-first flow to generate/update LOOPY_PLAN.md from a PRD seed.
If you already have a clear plan seed, run plan mode with --generate-prd=false.
loopy --mode plan --prompt "Add OAuth login to the app"Generates/updates LOOPY_PLAN.md and exits without running build iterations. Run loopy to start build mode.
Add PROMPT_build.md and PROMPT_plan.md to customize prompts per mode. Use --prompt-template <file> to override the template path.
📚 More workflows in
docs/REFERENCE.mdand Ralph-specific guidance indocs/RALPH_WORKFLOW.md. Templates live inexamples/.
Loopy treats a markdown plan document as the source of truth and orchestrates your agent through structured iterations:
┌─────────────────────────────────────────┐
│ 1. Read Plan (LOOPY_PLAN.md) │
│ ↓ │
│ 2. Prepare Agent Prompt │
│ ↓ │
│ 3. Execute Agent CLI │
│ ↓ │
│ 4. Capture Output & State │
│ ↓ │
│ 5. Apply Guardrails │
│ ↓ │
│ 6. Update Plan & State │
│ ↓ │
│ 7. Commit Changes (if enabled) │
│ ↓ │
│ 8. Check Completion → Loop or Exit │
└─────────────────────────────────────────┘
- Plan-Driven: Progress is tracked via markdown checkboxes
- [ ]→- [x] - Stateful: Every iteration updates
.loopy/state.jsonwith progress, errors, and metrics - Recoverable: Crashes or interruptions don't lose progress — just
--resume - Observable: Full logs in
.loopy/history/for every iteration - Controlled: Guardrails detect loops, drift, and repetitive errors automatically
Completion criteria: All checkboxes in the current phase are checked, or max iterations reached.
| Resource | Description |
|---|---|
| Complete Reference | Full CLI reference, configuration options, git integration, and troubleshooting |
| Architecture | Lightweight module diagram and system map |
| Ralph Workflow | Planning vs building guidance, templates, and workflow conventions |
| Examples | Sample PRDs, prompts, and plan templates for common use cases |
Contributions are welcome! Here's how you can help:
- Report bugs — Open an issue with details and reproduction steps
- Suggest features — Share your ideas for improvements
- Submit PRs — Fix bugs or add features (please open an issue first for major changes)
git clone https://github.com/yourusername/loopy.git
cd loopy
npm install
npm link
npm test- Follow existing code style
- Add tests for new features
- Update documentation for user-facing changes
- Keep commits focused and descriptive
MIT License — see LICENSE for details.
Copyright (c) 2026 Vagner Santana