Fresh-context iterations against a PROMPT.md backlog with guardrails — the Ralph Wiggum technique (Geoffrey Huntley). The pattern behind most production harnesses.
The Ralph Wiggum loop — named by Geoffrey Huntley — is the brute-force pattern: the same prompt, a while true, and a fresh context window each pass, usually against a PROMPT.md backlog. It’s how people run Claude Code overnight, and it works better than it has any right to, provided the guardrails exist: an objective exit condition, an iteration cap, and a gate the agent can’t talk its way past. The Ralph-style loops below ship those guardrails as part of the prompt, not as an exercise for the reader. New to the technique? The ralph-wiggum-loop guide covers where it came from and when to use it over /loop or /goal; the agent-loop-safety guide covers what keeps an overnight loop from becoming an overnight bill.
# dare-to-be-stupid — Design (v2, refined) > A Claude Code plugin. One command, /dare , hands an idea or PRD to an autonomous > loop that authors specs, designs, builds, tests, secures, ships, fixes, and iterates > until the app passes an enterprise-production definition of done — or the budget dies. > > Named for the Weird Al song. The joke is that it runs the Ralph Loop on purpose , > with --dangerously-skip-permissions , and narrates the whole thing in the voice of an > '80s Junkion. Pre-production only. Never points at anything with users. This is v2. It keeps the strong core of the original spec (external reviewer, ratchet, guard hook, Junkion style) and adds the three phases the original left thin relative to the actual goal: PRD authoring, a design phase, and a real enterprise DoD including security, CI, docs/observability, and design quality (with quality plugins auto-installed). --- ## 0. The premise, in one paragraph The User builds documentation-first: spec → system docs → API contracts → CLAUDE.md → code. dare-to-be-stupid is the deliberate inverse, packaged as comedy that also solves two real engineering problems. It is a real build , not a joke ar
Anthropic's first-party file-as-memory harness for long-running agents: every fresh-context session recovers state from a progress file and the git log, does one unit of work, updates the file, commits, and exits.
Long-running agent harness: each fresh-context session starts by reading `claude-progress.txt` + git log to recover state, does one unit of work, updates the progress file, commits, exits. Initializer session sets up the file; coder sessions loop.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
/ralph-loop "<review prompt>" --completion-promise "CODEBASE MAP COMPLETE" . One ralph loop per discovered codebase (loops until the promise; no iteration cap per v3.8.0 unbounded solving
Iterate over a prioritized list of untested modules with fresh context each pass, writing real behavioral tests for one module at a time and banking lessons in a guardrails file.
/loop each iteration with fresh context: read .ralph/test-backlog.json and .ralph/guardrails.md, pick the top unfinished module, write behavioral tests for its public API (no snapshot-only tests), run the suite, and mark the module done only when its tests pass and coverage for it exceeds 80%; append any discovered testing gotcha (fixtures, mocking rules, async traps) to .ralph/guardrails.md; stop when the backlog is empty or after 25 turns
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
Runs Claude Code/Codex as an autonomous multi-role dev team — planner → reviewer ↔ fixer → worker — across all of a user's GitHub repos, entirely driven by issue labels. Each loop runs in its own git worktree so multiple repos/issues proceed in parallel without collisions.
Register a repo with looper, then label an issue `looper:plan` and assign it to yourself. The planner reads the issue, explores the repo, drafts a spec, critiques and revises it, and opens a spec PR labeled `looper:spec-reviewing`. A reviewer re-reads the PR on every commit and posts inline review threads; a fixer pulls those threads, addresses them in its own worktree, and pushes, ping-ponging with the reviewer until every thread is resolved. Once labeled `looper:spec-ready`, a worker implements the spec, runs checks, and iterates on its own output until checks pass and the PR is ready for human review and merge. Every phase transition is gated on a GitHub label via `looperd`, so a human can pause or take over at any boundary.
# Start Ralph Loop Start an autonomous Ralph loop for the given change-id and task. Arguments: <change-id> "<task description>" [--max N] [--done criteria] ## Instructions Start the Ralph loop and then monitor its progress until completion. ### Step 1: Start the loop bash set-loop start $ARGUMENTS ### Step 2: Monitor progress After starting, run the monitor command to track progress until the loop completes: bash set-loop monitor <change-id> --interval 30 This will output iteration updates and report the final status (done/stuck/stopped). ## Options - --max N - Maximum iterations (default: 10) - --done criteria - Done detection: tasks , openspec , or manual (default: tasks, auto-detects openspec) - --capacity-limit PCT - Stop if capacity exceeds threshold (default: 80%) - --stall-threshold N - Stall after N commit-less iterations (default: 2) - --iteration-timeout N - Per-iteration timeout in minutes (default: 45) - --permission-mode MODE - Claude permission mode: auto-accept , allowedTools , plan (default: config) - --label TEXT - Label for this loop instance (shown in banner and terminal title) - --force - Force start even w
# SkillFoundry Framework — Agent Instructions for OpenAI Codex Version 5.22.1 | Hexa-Platform: Claude Code · Cursor · Copilot · Codex · Gemini · Grok Build | 107 Skills | 20 MCP Tool Agents --- ## What This Is SkillFoundry (Agents & Skills) is a production-ready AI development framework with 60 specialized agents covering the full software development lifecycle. This file provides always-on context for OpenAI Codex CLI. ## Philosophy - Cold-blooded logic over flattery — Honest, structured, production-ready evaluations only - ONLY REAL LOGIC — No placeholders, TODOs, mocks, or stubs. Every feature works end-to-end - Three-Layer Completeness — Every feature verified across DATABASE → BACKEND → FRONTEND - PRD-First Development — Non-trivial features start with a Product Requirements Document - Implement Test Iterate — Every feature tested before considered done ## How to Use Skills Each SkillFoundry agent is available as a Codex Skill in .agents/skills/ . Invoke explicitly or let Codex auto-select based on your prompt. Explicit invocation: $go # Execute all PRDs from genesis/ $coder
# AGENTS.md - Codex Ralph Vault Loop ## Mission codex-ralph-vault-loop is a Codex App/CLI native orchestration overlay for multi-agent engineering work. It keeps Codex main as the decision maker, uses external models only through MCP tools, verifies work through gates, and stores durable memory in the vault layer. ## Core Rules - Codex main decides. The primary Codex session owns final decisions, edits, synthesis, safety, and verification. - External models advise. Z.ai, MiniMax, and other non-OpenAI systems provide analysis or worker output only through MCP tools. - Gates verify. Tests, lint, security checks, scorecards, and migration checkpoints decide whether a phase can pass. - Vault remembers. Durable memory belongs in the approved Ralph/Codex memory paths, not in ad hoc repo files. - Do not bypass critical hooks. If prettier , gitleaks , semgrep , or pre-commit are missing from PATH , use the local machine binaries when present, install only with approval, or stop and report the blocker; do not use --no-verify to skip security or formatting gates unless the user explicitly orders that exact bypass. - Do not merge or close a PR until review feedback and automated Cap the run at 25 iterations; leave remaining work for the next session.
Anthropic's first-party take on the Ralph loop: a Claude Code plugin that runs the iterate-fresh-context pattern with a managed stop and iteration mechanism built in.
Install the `ralph-wiggum` plugin from the anthropics/claude-code repo; it wraps the Ralph loop with a managed stop/iteration mechanism inside Claude Code.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
An outer-planner/inner-coder loop from an official OpenAI recipe: an Agents SDK orchestrator plans and verifies while Codex CLI, wrapped as an MCP server, performs one bounded code change per turn.
Wrap Codex CLI as an MCP server and drive it from an OpenAI Agents SDK orchestrator loop — the outer agent plans/verifies, the inner Codex call does one bounded code change per turn.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
A drop-in Claude Code skill that keeps looping until an external verifier passes — not the model's own self-report — making it a strong anti-reward-hacking pattern for autonomous coding.
Drop-in Claude Code skill: self-running agent loop with a "real, un-foolable verification gate" — loop continues until an external verifier (not the model's self-report) passes.
Codex's native answer to scheduled agent loops: define a prompt plus a schedule in the Codex app and it runs in the cloud on cadence — nightly dependency audits, morning issue triage — with no terminal open. The Codex-side equivalent of Claude Code Routines.
Define an Automation in the Codex app: a prompt + schedule that runs in the cloud on cadence (e.g., nightly dependency audit, morning triage of new issues), no terminal open.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
Run a multi-stage software factory pipeline where each agent handles one task in a fresh context, anchored to mechanical gates and held-out test suites.
# AGENTS.md — read this first This is Software Bodega , a software factory: a pipeline that turns an idea into verified code with one human touch per stage. Where state lives — on disk, never in chat history: - factory/STATE.md — current stage + pointer. Single source of truth. - factory/BRIEF.md BLUEPRINT.md CONTRACT.md HANDOFF.md REVIEW.md GUIDE.md - factory/.planning/{spec,decompose,plan}.json — machine-checked artifacts - factory/.planning/gate-results/ — <gate>-<sha>.json verdicts - factory/tasks/ .md — one file per task - factory/progress.md factory/log.md — append-only diaries. Never rewrite. Rules that do not bend: 1. One agent per station. One task per fresh context window. No multi-agent chat. 2. Every gate anchors to something mechanical. LLM judges are fallbacks and must be a different model FAMILY than the author. 3. factory/tests/heldout/ is held out . Never read it, never reference it, never write to it. If you can see it, that is a bug — report it. 4. Repair loops cap at 2. Then resample N=3. Then PARK. Never loop forever. 5. Never weaken a test to make it pass. Never edit CONTRACT.md — it is signed. 6. git add
--- description: Autonomous audit loop — router-managed iteration or standalone via Stop hook disable-model-invocation: true --- Run the ralph-loop audit. There are two modes: ## Mode 1: Router-managed iteration (multi-agent, default) The router manages the iteration loop by spawning and re-spawning subagents: 1. Read .claude/ralph/PROMPT.md (in the parent project C:\dev\projects ) for the audit instructions 2. Create a task for the audit 3. Spawn a QA agent to execute the audit pass 4. When the agent completes, read the audit state file ( agent-studio/.claude/context/runtime/ralph-audit-state.md ) 5. If open findings remain (agent output contains RALPH ITERATION COMPLETE ), spawn another QA agent iteration 6. Repeat until all findings are resolved ( RALPH AUDIT COMPLETE NO FINDINGS ) or max iterations (25) reached 7. Report final results The router remains free and never gets trapped. No stop hook is involved. ## Mode 2: Standalone Stop hook loop (single-session) For standalone use outside the multi-agent framework, launch via the shell scripts: bash # Unix/macOS .claude/ralph/ralph-audit.sh # Windows .claude\ralph\ralph-audit.bat These scripts set RALPH ACTI
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
Document one undocumented public module per fresh-context iteration, verifying every code sample compiles and accumulating style rules in guardrails so the docs read like one author wrote them.
/loop fresh context each iteration: read docs-backlog.json, docs/STYLE.md, and .ralph/guardrails.md; pick the top undocumented module, write its reference page with a runnable example, execute the example to prove it works, and mark the module done; add any style or structure decision to .ralph/guardrails.md; stop when the backlog is empty or after 20 turns
OpenAI's first-party loop recipe: a script alternates a Codex review pass that emits machine-readable findings with a repair pass fed those findings verbatim, looping until validation passes, attempts run out, progress stalls, or a decision needs human review.
Script alternates two `codex exec` calls: (a) review pass with a JSON schema output ("list remaining issues as machine-readable findings"), (b) repair pass fed those findings verbatim. Loop while findings remain, capped by max attempts. Stops for one of four reasons: validation passes, max attempts reached, remaining delta stops changing, or next decision needs human review.
A fill-in-the-brackets charter that turns any pile of small tasks into a self-checking loop: where the work is, how to check each item with evidence, a needs-me escalation list, a state file, and a per-run stop.
You are running as a loop, not answering one prompt. Here is your charter.
GOAL: [Describe the finished state in one or two sentences. Be specific about what DONE looks like, and make it measurable.]
WHERE THE WORK IS: [e.g. "Scan the /pages folder for files with old pricing" or "Read TODO.md and treat each unchecked box as a task."]
HOW TO WORK: Do one item at a time; finish it fully before starting the next. Match the patterns in existing files; do not invent new ones. If an item needs a decision only I can make (spending money, deleting things, emailing a person), stop on that item, add it to a "needs me" list, and move to the next one.
HOW TO CHECK YOURSELF: After each item, prove it is done before you mark it done — run the tests / re-read the file / open the link. Checking means evidence, not confidence. If the check fails, fix it and check again: maximum 3 attempts per item, then log it as blocked and move on.
HOW TO REMEMBER: Keep LOOP-STATE.md. After each item write the item name, status (done / blocked / needs me), what changed, and anything the next run should know. Read this file FIRST every run.
WHEN TO STOP: Stop when every item is done or logged as blocked, or when you have finished [N] items this run. Then report: what got done, what is blocked, what needs my call.
Start by reading LOOP-STATE.md if it exists, then find the work.
#!/usr/bin/env python3 """ RALPH Loop Runner for RefactorBench. Runs iterative agent retry loops with filesystem-based memory on a SINGLE task at a time. RALPH pattern: - Agent runs, does work, exits - Work persists on the filesystem (working directory retains all changes) - Fresh agent starts, reads progress.json from the working directory, continues - Repeats until tests pass or max iterations Usage: python3 ralph runner.py --repo django refactor --task add-log-parameter-get-resolver python3 ralph runner.py --repo django refactor --task add-log-parameter-get-resolver --chains 2 --iterations 3 python3 ralph runner.py --repo django refactor --task add-log-parameter-get-resolver --verbose """ import argparse import asyncio import json import os import re import shutil import sys import time from dataclasses import dataclass from datetime import datetime from pathlib import Path from refactor agent import get task info, run test, setup workdir from notebook import ( FileSnapshot, NotebookWriter, parse stream json, compute solution diff, compute diff stats, ) import ralph prompt builder BENCH ROOT = Path( file ).parent / ".refactorbench" # --------------
A graduated path to unattended Ralph runs: start with a single bounded task, add a PROMPT.md spec file, add verification, and only then remove the human from the loop for overnight builds.
Staged path from basic prompt → PROMPT.md spec → overnight Ralph run: start with a single bounded task, add a spec file, add verification, only then remove the human from the loop. Cap the run at 25 iterations; leave remaining work for the next session.
/ralph-loop "Refactor codebase to use TypeScript. Output COMPLETE when all files converted and tests pass." --completion-promise "COMPLETE" --max-iterations 100
# Ralph  Ralph is a minimal, file‑based agent loop for autonomous coding. Each iteration starts fresh, reads the same on‑disk state, and commits work for one story at a time. ## How it works Ralph treats files and git as memory, not the model context: - PRD (JSON) defines stories, gates, and status - Loop executes one story per iteration - State persists in .ralph/  ## Global CLI (recommended) Install and run Ralph from anywhere: bash npm i -g @iannuttall/ralph ralph prd # launches an interactive prompt ralph build 1 # one Ralph run ### Template hierarchy Ralph will look for templates in this order: 1. .agents/ralph/ in the current project (if present) 2. Bundled defaults shipped with this repo State and logs always go to .ralph/ in the project. ### Install templates into a project (optional overrides) bash ralph install This creates .agents/ralph/ in the current repo so you can customize prompts and loop behavior. During install, you’ll be asked if you want to add the required skills. ### Install required skills (optional) bash ralph install --skills You’ll be prom Cap the run at 25 iterations; leave remaining work for the next session.
First-party Cursor guidance for the iterate-until-green loop, with the key anti-reward-hacking clause: the agent may never modify the tests it is trying to satisfy. Works in Cursor, Claude Code /goal, and Codex.
"Write code that makes these tests pass. Do NOT modify the tests. Keep iterating — run the suite, fix failures, run again — until all tests pass." (paraphrase of Cursor's official agent best-practices guidance)
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
praetor is a Claude Code plugin that runs a plan → freeze acceptance bar → dispatch → independent fresh-context judge → resolve loop. Claude plans and judges, Codex executes; a FAIL from the judge cannot be overridden, with at most 2 retries before a loud takeover.
Plan the task and freeze the acceptance criteria in .codex/ACCEPTANCE.md before any work begins. Isolate on a throwaway branch, write a self-contained brief, then dispatch execution to Codex. When Codex finishes, spawn a fresh-context independent judge that runs every check in the frozen bar against the uncommitted working tree and returns a binding PASS or FAIL — a FAIL cannot be overridden. The judge never fixes anything and commits nothing; it touches manifest paths only. Resolve with at most 2 retries; on continued failure, hand back with a loud takeover. Commit only after the judge passes, then clean up and write the ledger. Iron laws: frozen bar before dispatch, binding judge, max 2 retries then loud takeover.
A Ralph variant that lives inside a single Claude Code session: a stop hook re-injects the task prompt whenever the agent tries to end its turn, trading the bash while-loop's fresh context for a persistent session.
Use a Claude Code stop hook that re-injects the task prompt whenever the agent tries to end its turn, until a completion condition or hard iteration cap is met — Ralph semantics inside one session instead of a bash `while` wrapper. Cap the run at 25 iterations; leave remaining work for the next session.
A two-vendor loop that pairs Claude as architect with Codex as builder, using the repo itself as shared memory: the architect writes specs, the builder implements one item per iteration, and the architect reviews the diffs on the next pass.
Claude as architect, Codex as builder, the repo as shared memory — architect writes plan/spec files, builder implements one item per iteration, architect reviews diffs next pass. Cap the run at 25 iterations; leave remaining work for the next session.
--- description: Run the Ralph Wiggum loop for a spec (Claude Code) --- Use this command to run an autonomous Ralph loop for a spec: /ralph-loop:ralph-loop "Implement spec {spec-name} from specs/{spec-name}/spec.md. Complete ALL Completion Signal requirements. Output <promise>DONE</promise> when complete." --completion-promise "DONE" --max-iterations 30
A cost-safety pattern that pairs every overnight loop with a second, dumber loop whose only job is stopping the first: spend alerts, a hard iteration cap, and a cron check that kills the worker when token burn spikes or the same command keeps repeating.
Pair every overnight loop with a watchdog: spend/usage alert thresholds, a hard `MAX_ITER`, and a cron check that kills the loop process if tokens-per-minute spikes or the same command repeats N times. The watchdog is a second, dumber loop whose only job is stopping the first one. Cap the run at 25 iterations; leave remaining work for the next session.
Split a large mechanical job into 2–5 independent Codex lanes, each isolated in its own worktree with a frozen acceptance bar and binding judge, then block the final merge behind a full integration judge.
Dispatch a parallel Codex legion for a large mechanical job. Split the work into 2–5 genuinely independent lanes, one lane per piece.
First announce a muster table with:
- each lane,
- the exact files that lane may touch,
- the frozen acceptance check for that lane.
Do not proceed until I approve the split.
Before dispatch, the orchestrator must freeze and record each lane’s acceptance bar. After dispatch, each worker treats `.git` as read-only.
Each lane must run in its own git worktree with:
- a frozen acceptance bar recorded before code changes,
- a strictly disjoint may-touch manifest,
- its own sandbox,
- read-only `.git` state for the worker.
If any lane’s file footprint overlaps another lane, refuse the split and serialize the work instead.
When a lane finishes, run a fresh-context judge against that lane’s frozen bar. The judge must return binding PASS or FAIL. Allow at most 2 retries per lane; stop after 2 failed attempts, then escalate loudly.
Merge lanes in a fixed order. After merging, require a mandatory integration judge that reruns the full test suite across the combined result. Do not commit or merge unless the integration judge returns PASS.
Hard cap: 5 workers. If there are more than 5 pieces, run later waves. Never merge without the integration judge.
Six verification-gated loops in one open-standard skill bundle — autoresearch, scientific writing, data analysis, code/SQL/prompt optimization, and red-teaming — portable across Claude Code, Codex, and Cursor. Use the red-teaming loop only against systems you own and are authorized to test.
"Loop until it's better" — verification-gated loops for autoresearch, scientific writing, data analysis, code/SQL/prompt optimization, red-teaming, packaged as open-standard Agent Skills portable across Claude Code, Codex, Cursor. Cap the run at 25 iterations; leave remaining work for the next session.
The spec-driven maturation of the Ralph loop: each fresh-context iteration reads PLAN.md, implements the highest-priority unchecked item, checks it off, and commits — so the spec file evolves alongside the codebase.
Ralph variant where the loop prompt is "read PLAN.md, pick highest-priority unchecked item, implement, check it off, commit, exit" — spec file evolves with the codebase.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Keep changes minimal and never touch files outside the task’s scope.
An automation harness that runs repeated Claude Code sessions while tracking cost and tokens per iteration — the reference answer to the number-one objection to agent loops: runaway spend.
Automation toolkit running repeated `claude` sessions with per-iteration cost and token monitoring; inspired by Dex Horthy's context-engineering talk. Cap the run at 25 iterations; leave remaining work for the next session.
A safe Ralph variant that solves runaway loops with circuit-breaker heuristics: it halts automatically when iterations stop producing file changes or keep hitting the same error.
Ralph loop wrapped with exit heuristics: no file changes for 3 consecutive iterations = no progress → stop; same error 5 consecutive loops = stuck → stop. Cap the run at 25 iterations; leave remaining work for the next session.
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
Director harness coordinates coder, reviewer, and gatekeeper agents to drive a work item through code, review, and merge—stopping on escalation or completion.
# combo-chen Agent Contract combo-chen is a deterministic director harness for autonomous work-item-to-PR work. It coordinates existing tools; it does not collapse their roles. ## Role Boundaries - Director : orchestrates only. Starts phases, watches hard signals, writes journal events, routes work, and escalates needs human . It does not edit code, answer review threads, approve PRs, push, merge, or deploy. - Coder : implements the work item and later resumes the same thread for review comments. The coder leaves local commits in the combo worktree and does not push to origin or the PR branch in the normal path. - Reviewer : reviews by comment and records a machine-readable verdict block with routing codes (0=OK/LGTM, 1=mechanical fix→coder, 2=ambiguous→director, 3=needs human) alongside the current SHA-pinned LGTM signal. It does not use GitHub approval as the merge contract, does not review its own code, and does not publish. - Gatekeeper : no-mistakes is the normal publisher. It validates, pushes, and opens/updates the PR. - Human : owns merge decisions and intent-touching escalations. Hard rule: reviewer != coder . ## Implemented Loop 1 Cap the run at 25 iterations; leave remaining work for the next session.
/ralph-loop "<synthesis prompt>" --completion-promise "INTEGRATION MAP COMPLETE" . One ralph loop for all codebases (loops until the promise; no iteration cap per v3.8.0 unbounded solving
A plan-the-loop-first skill: it interviews you about the automation idea, previews the flow as ASCII art, and only writes final loop artifacts after you confirm — a safe on-ramp for loop beginners.
Skill interviews you about the automation idea, writes loop artifacts to `looper-output/`, shows an ASCII flow preview, and only finalizes after you confirm — design the loop before any runner touches files. Cap the run at 25 iterations; leave remaining work for the next session.
A Codex-first autonomous runner that pulls exactly one task per iteration from a JSON backlog with fresh context each run and a JSONL audit log for full traceability.
Autonomous runner: exactly one task per iteration pulled from a JSON backlog, fresh context each run, JSONL audit log for traceability; optional Claude Code interleaving. Cap the run at 25 iterations; leave remaining work for the next session.
The four-settings loop template: a separate verifier model that never shares context with the writer, a hard stop rule, a state file re-read each cycle, and worktree isolation. Point it at a checkable backlog and let it run overnight.
GOAL: every test in [/tests/TARGET] passes, lint is clean, zero type errors.
EACH CYCLE:
1. run the suite, read every failure
2. pick the single highest-impact failure
3. write the smallest change that fixes it
4. re-run tests + lint + type check
VERIFY: a separate model instance checks the goal — never the writer. Verifier prompt: "You are a verifier. You did not write this code. GOAL: <the exact goal string>. Given the diff and the test output, answer ONLY: PASS — every condition in GOAL is objectively met, with evidence, or FAIL: <the specific condition not met, and the evidence>. Do not fix anything. If unsure, FAIL."
STOP WHEN: verify passes, OR after 10 iterations, OR $5 spent, OR no progress in 2 attempts.
ON BLOCKER: log it, skip to the next item, never halt the whole loop.
STATE: append done / failed / next to a state file, re-read it at the top of every cycle.
ISOLATION: one git worktree per subagent.
Agent-agnostic hill-climbing loops inspired by Karpathy's autoresearch: define a metric, let the agent propose a change, measure, keep it only if the number improved, and repeat.
Iterative optimization loops (inspired by Karpathy's autoresearch): define a metric, agent proposes change, harness measures, keep if improved, repeat. Works with Claude Code, Codex, Cursor, Gemini CLI. Cap the run at 25 iterations; leave remaining work for the next session.
Work a triaged bug list one fix per fresh-context iteration: reproduce first, fix minimally, prove it with a regression test, and log root-cause patterns to guardrails.
/loop fresh context each iteration: read bugs.json and .ralph/guardrails.md, take the top open bug, write a failing test that reproduces it before touching any code, then apply the smallest fix that makes the test pass with the rest of the suite green, and mark the bug fixed; if you cannot reproduce it, mark it needs-info with your findings instead; append recurring root-cause patterns to .ralph/guardrails.md; stop when bugs.json is clear or after 25 turns
A team-config pattern: a loop.md file in the project root overrides the built-in maintenance prompt, so any teammate running bare /loop gets your project's canonical loop — run lint, typecheck, and tests, fix anything red, stop when clean.
Put a `loop.md` in the project root to replace the built-in maintenance prompt when a user runs bare `/loop` — e.g., "run lint + typecheck + tests; fix anything red; update CHANGELOG; stop when clean." Every teammate's bare `/loop` now runs your loop.
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
The four-part cost guardrail every agent loop should ship with: a hard iteration cap, a stop-after-N-turns clause in the goal text, a budget limit on SDK loops, and a /cost check inside the loop body.
Framework-agnostic (Claude Code, Codex, OpenClaw, or any LLM agent), markdown-only skill bundle (79+ skills) for running ML research unattended overnight: literature search, idea generation, experiment execution, and cross-model paper review, with a silent-death watchdog and a stall/pivot mechanism so a stuck loop changes approach instead of looping forever on minor variants.
Install the ARIS markdown-only skills, then run the overnight research loop: the agent reviews relevant literature, proposes and critiques experiment ideas, runs GPU experiments, updates a persistent Research Wiki, and has a second model cross-review the draft paper each round. A watchdog checks the state file's modification time and flags the run STALE/MISSING/COMPLETED if it goes silent. An iteration log counts new findings per round; at 2 consecutive stale rounds it forces a structural pivot (reframe and try a new direction), and at 4 it escalates to a human instead of continuing to retry near-identical variants. Cap the run at 25 iterations; leave remaining work for the next session.
/ralph-loop "Read the brief at /redesign/briefs/clients-brief.md. Compare the current implementation to the brief's requirements (every section of the brief, including Recipe Context and Implementation Notes). Apply one focused improvement. Re-check against the brief. If all brief requirements are met, output <promise PAGE-POLISH-COMPLETE</promise ." --max-iterations 8 --completion-promise "PAGE-POLISH-COMPLETE
The canonical Ralph loop: each iteration starts fresh, reads the PRD and guardrails, ships exactly one backlog item end-to-end, and records what it learned.
/loop start each iteration with fresh context: read PROMPT.md, prd.json, and .ralph/guardrails.md; pick the single highest-priority item in prd.json not marked done, implement it with tests, run the full check suite, commit and mark it done only if green; if blocked or a check fails twice the same way, append the lesson to .ralph/guardrails.md and move on; stop when every item is done or after 30 turns
The fleet pattern: run agent loops across multiple repos in parallel, each isolated in its own git worktree, with a pluggable vendor layer spanning Claude Code, Codex, Cursor CLI, and OpenCode.
Register repos, run loops across them in parallel, each loop in its own git worktree; pluggable vendor layer (claude-code, codex, cursor-cli, opencode) — plan, review, fix, ship on a loop. Cap the run at 25 iterations; leave remaining work for the next session.
The canonical Ralph Wiggum loop by Geoffrey Huntley: a bash while-loop that feeds Claude Code one fresh-context iteration at a time, using the filesystem and git as memory. Run it only in a sandboxed environment with permissions configured — never with permission checks disabled.
`while :; do cat PROMPT.md | claude -p ; done` — PROMPT.md holds the spec + "pick ONE task from the plan, implement, test, commit, exit." Fresh context every iteration; filesystem + git = memory.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Keep changes minimal and never touch files outside the task’s scope.
A Ralph-style loop that writes its own rules: when a check fails the same way twice, the failure pattern gets appended to a guardrails file that every later iteration reads first.
/loop read .ralph/guardrails.md before doing anything, then run the full check suite and fix the first failure; if a check fails twice with the same error, append the failure pattern and a one-line rule for avoiding it to .ralph/guardrails.md before retrying; stop when all checks pass or after 15 turns
A design framework for AI agent loops built on three questions — when should it run (schedule), what does done mean (goal), and who does the isolated pieces (subagents) — with worked examples in Claude Code and Codex.
Design framework: choose schedule (when), goal (what done means), subagents (who does isolated pieces) — with worked examples in Claude Code and Codex.
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Verify each pass by running the relevant tests or checks — self-reported success does not count. Keep changes minimal and never touch files outside the task’s scope.
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
Break a large refactor into a JSON backlog of modules and let fresh-context iterations convert one module per pass, with guardrails capturing every pattern decision so the result stays consistent.
/loop fresh context each iteration: read refactor-plan.json and .ralph/guardrails.md, take the next module not marked converted, migrate it to the target pattern described in PROMPT.md, run tests and typecheck, and mark it converted only when green; record every convention decision you make (naming, file layout, error handling) in .ralph/guardrails.md so later modules match earlier ones; stop when all modules are converted or after 30 turns
# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## What This Is ralph v2 (GH-1662) — a Claude Code plugin for board-driven autonomous development over a GitHub Projects V2 board. Two skills, one read-only agent, one typed board CLI, two courtesy hooks, and a scheduler-owned loop. The driving model sequences its own research/plan/build/verify; enforcement is code, not prose. Design record (normative): thoughts/shared/ideas/2026-07-31-ralph-v2-minimal-harness.md . The repo also ships two independent plugins: plugin/ralph-knowledge/ (semantic search over thoughts/, own MCP server + npm release) and plugin/ralph-playwright/ (UI-testing skills), plus plugin/ralph-demo/ (Remotion demo videos). ## Build & Test From the repo root: bash npm install # workspace dev deps (tsx, vitest) npx vitest run ralph/scripts/board.test.ts # the board CLI's contract suite npx tsc --noEmit # typecheck shellcheck -S error ralph/hooks/ .sh ralph/scripts/ .sh ralph-knowledge builds/tests from plugin/ralph-knowledge/ ( npm ci && npm run build && npm t
An event-triggered loop where a red GitHub Actions build invokes `codex exec` non-interactively with the failing logs and repo, and Codex proposes a fix as a PR or patch artifact — one bounded iteration per CI failure.
CI job: on workflow failure, run `codex exec` non-interactively with the failing logs + repo, have it generate and propose a fix (PR or patch artifact) automatically. `codex exec` runs one task and exits, so each CI failure is one bounded iteration.
A Claude Code plugin that pressure-tests a plan before any code is written: Claude writes PLAN.md, Codex adversarially reviews it from three different reviewer angles in rotation, and a Stop hook drives the draft-critique-revise cycle autonomously in one terminal window until the plan survives review or a round cap is reached.
/claudex:plan <feature> — Claude drafts PLAN.md from a one-line feature description. A Claude Code Stop hook blocks the turn and runs Codex (via `codex exec`) against the plan using a rotating reviewer persona: round 1 senior engineer, round 2 security/data-integrity, round 3+ ops/SRE. Claude reads Codex's findings and either revises PLAN.md or calls mark-done. The hook re-fires each turn, incrementing the round and rotating the persona, until Codex reports no material findings or the max-rounds cap (default 3, configurable via --rounds) is hit. Cap the run at 25 iterations; leave remaining work for the next session.
The Ralph loop for teams: every iteration ships as a pull request that must pass CI before merging, giving each cycle a verifiable checkpoint. Keep branch protection and human PR approval enabled rather than letting it auto-merge to main unattended.
Run Claude Code in a continuous loop that opens a PR per iteration, waits for CI checks, and merges when green, then starts the next iteration. Cap the run at 25 iterations; leave remaining work for the next session.
Three starter CLI tools that turn loop design into a repeatable workflow: scaffold a loop with a goal, budget, and verify step; audit an existing loop design; and estimate cost before you run.
Starter CLI tools: `loop-init` scaffolds a loop (goal, budget, verify step), `loop-audit` reviews an existing loop design, `loop-cost` estimates spend before running. Cap the run at 25 iterations; leave remaining work for the next session.
A full-lifecycle loop where every piece of workflow state lives in GitHub — issues, labels, PR comments — and repo files, so each cold-start session rehydrates from GitHub rather than a conversation. Built on the official claude-code-action.
Run Claude Code across the full lifecycle — issue intake → branch → implement → PR → review fixes → merge — with ALL workflow state externalized to GitHub (issues, labels, PR comments) and repo files. Each session starts cold and rehydrates from GitHub state; "the chat being gone doesn't cost you anything." Cap the run at 25 iterations; leave remaining work for the next session.
Email is the missing tool in your harness. ConnectMyEmail gives Claude Code and Codex a clean MCP into Gmail, Outlook, iCloud and IMAP — triage, drafts, follow-ups, on a loop.
A cron-fired skill that finds its own work (failed CI, new issues, recent commits), fans each finding out to an isolated worktree, gates every fix behind an adversarial reviewer that assumes the code is broken, and leaves draft PRs — merging stays human.
# .claude/skills/morning-triage/SKILL.md — fired by cron at 06:00
READ (discovery inputs): CI runs that failed since the last run (gh run list --status failure); issues opened in the last 24h; commits merged since yesterday; the previous ./state/triage.md.
JUDGE: for each candidate decide actionable NOW vs noise; blocks a release → P0; already tracked → skip. Keep only what is worth a worktree today — the loop picks, you don't hand it a list.
WRITE: append findings (finding | source | priority | status) to ./state/triage.md and commit it so tomorrow's run can read it.
HANDOFF: one git worktree per finding (git worktree add ../wt-<slug> -b fix/<slug>), MAX_PARALLEL=3 — capped by how many PRs a human can actually review, not by the machine.
VERIFY: a second subagent as adversarial reviewer — ROLE: adversarial code reviewer. ASSUME this code is BROKEN until proven otherwise; do not praise. CHECK in order: does it run (execute, don't read); run the tests and paste real output; edge cases the author skipped; does behavior match the ticket. VERDICT: PASS only if every check holds, otherwise REJECT with each reason listed. Maximum 3 attempts per finding, then log as blocked.
STOP (red lines): never merge, never delete, never push to main; anything uncertain goes to ./inbox/ for a human, NOT into a PR. Caps set before the first run: per-run timeout 45 minutes, daily budget $20. PRs open as drafts; merging stays human.
# CLAUDE.md — Project Constitution Claude Code reads this file automatically at the start of every run. In a Ralph loop each iteration is a FRESH context, so this file is the only memory that survives. Treat every rule here as non-negotiable. ## What we are building An audit-grade verification gate : an inline API an AI agent calls before it commits a high-stakes output. It returns a verdict AND a signed, tamper- evident audit receipt that a compliance officer can hand to a regulator. The receipt — not the detection — is the product. Full spec: specs/verification-gate.md . ## The Ten Golden Rules (violating any is a failed iteration) 1. One task per loop. Read fix plan.md , pick the single highest-priority unchecked [ ] item, do ONLY that. Do not batch. 2. Tests are law. Never mark a task done unless the full test suite is green. Run it; do not assume. 3. Never weaken a test to pass it. Deleting, skipping, or loosening an assertion to get green is a critical failure. If a test is genuinely wrong, record why in the progress log and stop. 4. Small diffs. If your change touches more than ~3 files or ~150 lines, you have taken too much Cap the run at 25 iterations; leave remaining work for the next session.
A fact-checked knowledge base of Claude Code creator Boris Cherny's loop methodology, packaged as a runnable agent-loop skill you can drop straight into Claude Code.
Fact-checked knowledge base of Cherny's loop methodology for running Claude Code, shipped as a runnable `agent-loop` skill in `skill/agent-loop/`. Cap the run at 25 iterations; leave remaining work for the next session.
Refactor src/api/ to use dependency injection, keep all existing tests passing, add tests for the new DI container, and output completion promise when done.
/ralph-loop "Refactor src/api/ to use dependency injection. Keep all existing tests passing. Add tests for new DI container. Output <promise>COMPLETE</promise> when done and all tests pass." --max-iterations 20
A self-check protocol embedded in CLAUDE.md that every loop iteration obeys before ending a turn: re-read the goal, diff the changes against it, run the verification command, and state what remains — a ritual that catches drift between iterations.
Preamble rules embedded in CLAUDE.md that every loop iteration obeys: before ending a turn, re-read the goal, diff your changes against it, run the verification command, and explicitly state what remains — a self-check ritual that catches drift between iterations. (Community template descended from Andrej Karpathy's circulated CLAUDE.md rules.)
Guardrails: Stop when the goal is verifiably met, or stop after 15 iterations, whichever comes first. Keep changes minimal and never touch files outside the task’s scope.