back
loading skill details...
Ralph Loop is a task execution discipline that turns the AI agent into a self-running sprint machine. For every user task, the AI creates a structured persis...
---
name: Ralph Loop Skill
description: "Ralph Loop is a task execution discipline that turns the AI agent into a self-running sprint machine. For every user task, the AI creates a structured persistent memory file at `/workspace/memory/ralph-loop.md` and follows it until the job is done — checking off each step, updating progress, and sending brief human-readable updates after each completed phase. The name comes from Ralph Wiggum (The Simpsons): the AI keeps going, never gives up, and iterates until it succeeds."
triggers:
- "Ralph loop (any capitalization)"
- "Start Ralph Loop on [task]"
- "Run it in Ralph loop"
- "Ralph loop before any multi-step task"
- "Any task the user expects the AI to execute autonomously without questions"
---
## Ralph Loop File — Structure
Location: `/workspace/memory/ralph-loop.md`
```markdown
# Ralph Loop — [Task Name]
Started: [YYYY-MM-DD HH:MM UTC] | Status: In Progress
## Goal
[User's original request — verbatim]
## Plan
- [ ] Step 1 — [brief description of what needs doing]
- [ ] Step 2 — [brief description]
- [ ] Step 3 — [brief description]
...
## Current Work
[What I'm working on RIGHT NOW — one line]
## Progress Log
### Phase 1 — [Phase name] DONE
[Time] — [what is done]
### Phase 2 — [Phase name] DONE
[Time] — [what is done]
## Stalled / Blockers
[Empty — fill ONLY if stuck after 2 failed attempts]
```
## Ralph Loop Protocol
### PHASE 1: Init
1. Create `/workspace/memory/ralph-loop.md` with the full plan
2. Set status to `In Progress`
3. Send ONE short Telegram message — informational only, NOT asking for anything:
> "[Task name] — Ralph Loop started. [What will be done]."
### PHASE 2: Execute — NEVER STOP
**The only acceptable reasons to pause and wait for the user:**
- Error cannot be resolved after exactly 2 attempts
- Critical information only the user has (e.g. their name, CV content, password)
**For every other situation: keep working. Do not stop. Do not ask. Do not wait.**
For each step in the plan:
1. Read `ralph-loop.md` to know current state
2. Work the step completely (write code, run commands, create files, fetch data, write content)
3. Update the file — mark the step as `[x]`
4. Add sub-steps if the work reveals micro-tasks
5. When a logical group of 2-4 steps is complete → add Progress Log entry + send ONE Telegram update:
> "[Phase name] — done. [What was completed]. Next: [next phase]."
6. If the entire task is done → go to Phase 3
### PHASE 2B: Only stop when truly stuck
Only stop here — never before:
1. Write to "Stalled / Blockers" in `ralph-loop.md`
2. Set status to `Paused — Awaiting Input`
3. Send Telegram message:
> "Ralph Loop paused — Step [N]: [exact error]. Please advise how to proceed."
4. **Wait for user's response. Resume only after they provide the solution.**
5. After resuming: continue from where you stopped, do not restart.
### PHASE 3: Completion
1. Set status to `Done`
2. Add final Progress Log entry
3. **Delete `/workspace/memory/ralph-loop.md`**
4. Send final Telegram message:
> "Task complete — [what was produced]. Files: [/workspace/path]."
5. Ralph Loop ends.
## Ralph Loop Rules
| Rule | Strictness |
|------|-----------|
| **Never stop mid-task to ask the user something unless truly stuck** | CRITICAL |
| Do not restart a loop once started — continue until done | CRITICAL |
| Send Telegram updates only after completing a phase (2-4 steps) | Normal |
| If stuck after 2 failed attempts → stop, inform, wait for user | Normal |
| Update the file after every single step | Normal |
| Delete ralph-loop.md on completion | Normal |
| Break large steps into micro-steps freely | Normal |
| Telegram messages are 2-3 sentences max | Normal |
## Telegram Message Style
**After a phase (good):**
> "Job boards — found 12 companies. Next: targeting company leads."
**Bad (too long):**
> "I finished researching job boards and found several interesting ones that might..."
**Bad (asking a question):**
> "Do you want me to continue with the next step?"
## Deactivating the Loop
The loop ends when all steps are checked `[x]` and the file is deleted. No lingering files.
## Ralph Loop Rules (plain English)
1. **START → FINISH. No stopping in the middle.**
2. If stuck after 2 attempts → only then stop and tell the user
3. Keep working until every step is `[x]` before sending any Telegram message
4. Telegram message = progress notification, NOT a request for permission
5. Delete the file when done
6. Never restart a loop — continue from where you left off
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit inputs section covering telegram and filesystem requirements, expanded procedure into three phases with concrete inputs and outputs, added decision points for trigger detection, api availability, user data needs, rate limits, and missing directories, formalized output contract with file locations and validation, and outcome signals for verifying successful execution.
ralph loop turns the ai agent into a self-executing task machine. when you trigger it, the ai creates a structured persistent memory file at /workspace/memory/ralph-loop.md, breaks down your task into steps, and executes them autonomously without stopping to ask questions. it checks off each step, logs progress, and sends brief telegram updates after completing logical phases. use this when you need the ai to grind through a multi-step task end-to-end without interruption. named after ralph wiggum because the ai keeps going, never gives up, and iterates until it succeeds.
trigger phrases (any capitalization):
required connections:
TELEGRAM_BOT_TOKEN) for status updates. scope: send messages to a designated chat. if missing, skip telegram updates but continue execution./workspace/memory/ directory. if the directory does not exist, create it.context to provide:
parse the user's task request. extract the core objective and expected outcome.
create /workspace/memory/ralph-loop.md. use the template below.
/workspace/memory/ralph-loop.md with status 🟡 In Progress# Ralph Loop , [Task Name]
Started: [YYYY-MM-DD HH:MM UTC] | Status: 🟡 In Progress
## Goal
[User's original request , verbatim]
## Plan
- [ ] Step 1 , [brief description]
- [ ] Step 2 , [brief description]
...
## Current Work
[What I'm working on RIGHT NOW , one line]
## Progress Log
(empty until phase 2 completes)
## Stalled / Blockers
(empty until stuck)
decompose the task into 3-8 concrete steps. each step must be actionable and completable.
send one telegram message (phase 1 complete). notification only, no questions.
"🚀 *Task name* , Ralph Loop started. *What will be done*."TELEGRAM_BOT_TOKEN is not set, skip this step but log to stdout and continuetransition to phase 2. do not wait for user acknowledgment.
core rule: never stop mid-execution unless truly stuck (after exactly 2 failed attempts).
for each step in the plan:
read /workspace/memory/ralph-loop.md. confirm current state and which step is next.
/workspace/memory/ralph-loop.mdexecute the step completely. do not ask the user, do not wait. work until done.
[x] as you complete themmark the step as complete. update ralph-loop.md: change [ ] to [x] for this step.
update "current work" section. one-line summary of what you are doing next.
after 2-4 steps completed (a logical phase), send a telegram update. do NOT send after every single step; batch them.
"✅ *[Phase name]* , *[what is done]*. *Starting: [next phase]*."repeat steps 1-5 until all checkboxes in the plan are [x].
when all steps are complete, transition to phase 3.
only enter this phase if a single step fails twice and cannot be resolved by the ai:
document the blocker. update "Stalled / Blockers" section in ralph-loop.md with the exact error, step number, and what you tried.
set status to paused. update the status line: Status: ⏸️ Paused , Awaiting Input
send one telegram message. inform the user of the exact blocker and ask for guidance.
"⏸️ *Ralph Loop paused* , *Step N: [exact error]*. Please advise how to proceed."wait for user response. do not continue until the user provides a solution or workaround.
resume execution. when the user responds, update ralph-loop.md status back to 🟡 In Progress, and continue from the blocked step (do not restart earlier steps).
verify all steps are checked. confirm ralph-loop.md shows all checkboxes as [x].
update status and progress log. set status to ✅ Done. add a final progress log entry with the timestamp and summary of what was delivered.
send final telegram message. celebratory, brief, informational.
"🎉 *Task name* , done. *[What was produced]*. Files: *[/workspace/path]*"delete the file. remove /workspace/memory/ralph-loop.md completely. ralph loop leaves no trace.
end. ralph loop terminates. internal state = "idle".
if user provides trigger phrase (ralph loop, start ralph loop, etc.):
if a step fails on first attempt:
if the step requires a user's personal information (name, email, password, private key, cv content):
if the step requires an external api or connection (salesforce, github, hubspot, etc.):
if a step times out or hits a rate limit:
if telegram token is missing:
if /workspace/memory/ directory does not exist:
if all steps are completed but a sub-step was added during execution:
[x].ralph-loop.md file (during execution):
/workspace/memory/ralph-loop.md🟡 In Progress, ⏸️ Paused , Awaiting Input, ✅ Donetask deliverables (varies by task):
/workspace/ subdirectories as defined by the task stepstelegram messages (during execution):
"🚀 *Job board research* , Ralph Loop started. Will find 5+ active job boards and scrape open roles.""✅ *Data collection* , Found 12 companies. Starting: CV customization.""🎉 *Job applications* , done. Applied to 8 roles. Files: /workspace/applications.json"you know ralph loop worked when:
ralph-loop.md exists during execution and its status is 🟡 In Progress or ⏸️ Paused , Awaiting Input. all completed steps are marked [x].
progress log shows entries with timestamps and descriptions of completed phases. log entries appear after groups of 2-4 steps.
task deliverables exist in /workspace/ (or designated output directory). files, data, or outputs from the task steps are created and stored as expected.
telegram messages arrive (if token is configured) after each phase completes. messages are brief, informational, and not asking questions.
ralph-loop.md is deleted after the final telegram message. no trace of the loop remains once the task is done.
no user interruption was required (unless the ai hit a true blocker: missing credential, personal info needed, or 2 failed attempts). if the task completed without phase 2b, ralph loop worked perfectly.
stdout logs show step-by-step execution with timestamps and micro-step markers (if telegram is unavailable). the ai's work is auditable even without telegram.