Autonomous task execution protocol for AI coding agents.
Define what you want. Let the agent loop until it's done.
Installation • Quick Start • How It Works • Configuration • Protocol Reference
Most AI coding agents do one thing, then stop and wait. You describe, they implement, you review, you describe again. It's slow.
easy-ralph turns that into an autonomous loop. You define the task once — what to build, when it's done, what not to touch — and the agent iterates on its own until every criterion is met. No hand-holding, no babysitting.
It works with any language, any framework. Just tell it how to verify your code, and it handles the rest.
- Language-agnostic — auto-detects your project (Node, Python, Flutter, Rust, Go) and picks the right verification commands
- Anti-drift — re-reads the original task at every iteration to prevent the "telephone game" problem
- Hard stops — safety brakes that kill the loop before it does something stupid
- Validate-then-commit — nothing gets committed until lint, tests, and (for web) Playwright E2E all pass
- Works solo or with friends — optionally delegates to Codex or other agents; runs fine without them
Copy the skill into your global skills directory:
# Clone
git clone https://github.com/5iing/easy-ralph.git
# Copy to Claude Code skills
cp -r easy-ralph/skills/ralph-task ~/.claude/skills/ralph-taskThat's it. Claude Code auto-discovers skills in ~/.claude/skills/.
If you only want it in a specific project:
cp -r easy-ralph/skills/ralph-task your-project/.claude/skills/ralph-taskOpen Claude Code in any project and say:
run ralph
The skill asks you a few questions:
1. What are you building? → "Add rate limiting to all API endpoints"
2. When is it done? → "All endpoints return 429 on excess, tests pass"
3. What's off-limits? → "Don't touch auth middleware"
4. Verify commands look right? → [auto-detected: npm run lint, npm test]
It generates a task file, confirms with you, then the agent goes to work.
.ralph/tasks/2026-02-27-api-rate-limiting.md ← task definition
.ralph/tasks/logs/api-rate-limiting-iter-1.md ← iteration log
.ralph/tasks/logs/api-rate-limiting-iter-2.md
...
┌─────────────────────────────────────────────────────┐
│ 1. PRE-FLIGHT │
│ Read docs → Analyze impact → Log affected files │
├─────────────────────────────────────────────────────┤
│ 2. PLANNING │
│ Per-file plan → Dependency order → Log to file │
├─────────────────────────────────────────────────────┤
│ 3. EXECUTION │
│ ⚠️ Anti-drift check (every iteration) │
│ Implement → Run verify commands per file │
├─────────────────────────────────────────────────────┤
│ 4. VALIDATION → COMMIT │
│ verify_commands → Playwright E2E (web) → Review │
│ All pass? → Atomic commit │
│ Fail? → Back to step 3 │
├─────────────────────────────────────────────────────┤
│ 5. DONE? │
│ ✅ All criteria met → Summary + finish │
│ ❌ Not yet → Next iteration (go to 3) │
│ 🛑 Hard stop triggered → Halt + report │
└─────────────────────────────────────────────────────┘
Long agent loops drift. By iteration 10, the agent is solving a different problem than what you asked for.
easy-ralph forces the agent to re-read the original task at the start of every iteration and compare it against current progress. If drift is detected, it stops, realigns, and resumes. Every iteration is logged to a file so context survives even when the conversation window fills up.
### Iteration 3
- Original objective: Add rate limiting to API endpoints
- Completed this iteration: Created rate limiter middleware, applied to /api/users
- Remaining: Apply to /api/orders, /api/payments, write tests
- Drift status: noneThe agent has a "don't stop" rule — but some things should always stop it:
| Condition | Action |
|---|---|
| Modified a file listed in Constraints | git checkout revert → halt → report violation |
| 5+ consecutive skips | Halt → full progress summary |
| Working outside project root | Halt → report location |
| No verify_commands configured | Refuse to start |
These override everything else. No exceptions.
Every task includes a domain block in its frontmatter:
domain:
platform: "web" # "web" → Playwright E2E required before commit
verify_commands: # Required. What commands prove the code works.
- "npm run lint"
- "npm test"
collaborator: "codex" # Optional. Delegates analysis to another agent.
domain_agents: [] # Optional. Specialized agents for your stack.The skill detects your project type and suggests verify commands:
| Detected File | Suggested Commands |
|---|---|
package.json |
npm run lint, npm test |
pubspec.yaml |
flutter analyze, flutter test |
pyproject.toml |
ruff check ., pytest |
Cargo.toml |
cargo clippy, cargo test |
go.mod |
go vet ./..., go test ./... |
You can always override or add to these.
If you have access to Codex or another analysis agent, set collaborator. The agent delegates impact analysis and code review to it.
If you don't, set it to null. The agent does everything itself — Grep, Glob, self-review. No degraded experience, just fewer delegation steps.
When platform: "web", the agent runs Playwright MCP E2E tests before every commit. This is not optional — it's a hard gate. If Playwright fails 3 times, the change goes to failure handling.
For non-web projects, this step is skipped entirely.
The full execution protocol lives in skills/ralph-task/references/ralph-loop.local.md.
It covers:
- Core principles and graceful degradation
- Pre-flight, planning, and execution phases
- Validation → commit ordering
- Failure handling and retry logic
- Hard stop conditions
- Agentic behavior rules
---
active: true
iteration: 1
max_iterations: 20
started_at: "2026-02-27T14:30:00Z"
domain:
platform: null
verify_commands:
- "npm run lint"
- "npm test"
collaborator: null
domain_agents: []
---
Execute autonomously following the @ralph-loop.local.md protocol.
## Task
Add rate limiting to all API endpoints.
- 100 requests per minute per IP
- Return 429 with Retry-After header
- Redis-backed sliding window
## Done Criteria
- [ ] Rate limiter middleware created
- [ ] Applied to all /api/* routes
- [ ] 429 response includes Retry-After header
- [ ] All verify_commands pass
## Constraints
- Do not modify auth middleware
- Do not change existing response formats- Not a magic wand. Garbage in, garbage out. Vague tasks produce vague results. Be specific about done criteria.
- Context window is finite. The iteration log helps, but extremely long tasks (30+ iterations) may still lose context. Break large work into smaller tasks.
- Verify commands must exist. If your project doesn't have a linter or test suite, easy-ralph can't verify anything. Set up your toolchain first.
- Playwright requires setup. Web QA only works if Playwright MCP is installed and configured in your Claude Code environment.
PRs welcome. If you find the agent drifting in a way the protocol doesn't catch, open an issue with the iteration logs — that's the most useful debugging info.
MIT