# Agent Ralph Loop Claude

> Implements the Ralph Wiggum technique as a Claude Code plugin for iterative, self-referential AI development loops. Use when building projects that require hands-free AI implementation through continuous bash-style loops inside a single Claude Code session, where the same prompt is repeatedly fed back until completion criteria are met.

- **Type:** Skill
- **Install:** `agentstack add skill-tangledgroup-tangled-skills-agent-ralph-loop-claude`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tangledgroup](https://agentstack.voostack.com/s/tangledgroup)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tangledgroup](https://github.com/tangledgroup)
- **Source:** https://github.com/tangledgroup/tangled-skills/tree/main/misc/agent-ralph-loop-claude

## Install

```sh
agentstack add skill-tangledgroup-tangled-skills-agent-ralph-loop-claude
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Ralph Loop Claude Plugin v1.0.0

## Overview

Ralph Loop is a Claude Code plugin that implements the **Ralph Wiggum technique** — an iterative development methodology based on continuous AI agent loops. As Geoffrey Huntley describes it: **"Ralph is a Bash loop"** — a `while true` loop that repeatedly feeds an AI agent the same prompt, allowing it to iteratively improve its work until completion.

The plugin works entirely **inside your current Claude Code session** — no external bash loops needed. A Stop hook intercepts Claude's exit attempts and feeds the same prompt back, creating a self-referential feedback loop where Claude sees its own previous work in files and git history on each iteration.

## When to Use

**Good for:**

- Well-defined tasks with clear success criteria
- Tasks requiring iteration and refinement (e.g., getting tests to pass)
- Greenfield projects where you can walk away
- Tasks with automatic verification (tests, linters, build checks)

**Not good for:**

- Tasks requiring human judgment or design decisions
- One-shot operations
- Tasks with unclear success criteria
- Production debugging (use targeted debugging instead)

## Core Concepts

### The Ralph Loop Mechanism

The core loop works like this:

1. You run `/ralph-loop` with a task description once
2. Claude works on the task, modifying files
3. Claude tries to exit the session
4. A Stop hook intercepts the exit attempt
5. The Stop hook feeds the **same prompt** back to Claude
6. Claude sees its previous work in files and git history
7. Claude autonomously improves on its past work
8. Repeat until completion criteria are met

The "self-referential" aspect comes from Claude seeing its own previous work persisted in files — not from feeding output text back as input. Each iteration starts fresh with the same prompt, but the workspace has evolved.

### State Management

Ralph Loop uses a markdown state file at `.claude/ralph-loop.local.md` with YAML frontmatter:

```yaml
---
active: true
iteration: 1
session_id: 
max_iterations: 20
completion_promise: "DONE"
started_at: "2025-01-15T10:30:00Z"
---

Your task prompt text here...
```

The state file tracks iteration count, session isolation, max iterations, and the completion promise. The Stop hook reads this file to decide whether to block exit and continue the loop.

### Completion Promises

To signal genuine task completion, Claude outputs a `` tag:

```
TASK COMPLETE
```

The Stop hook extracts text from `` tags and compares it against the `--completion-promise` value. The match must be exact — no partial or fuzzy matching.

### Session Isolation

Each Ralph loop is scoped to a specific Claude Code session via `session_id`. If multiple Claude Code sessions are open in the same project, only the session that started the loop will be affected by its Stop hook.

## Advanced Topics

**Plugin Architecture**: Internal structure — commands, hooks, scripts, and plugin manifest → [Plugin Architecture](reference/01-plugin-architecture.md)

**Stop Hook Deep Dive**: The exit-interception mechanism, transcript parsing, and loop continuation logic → [Stop Hook Deep Dive](reference/02-stop-hook-deep-dive.md)

**Prompt Engineering**: Writing effective Ralph prompts with clear completion criteria and self-correction patterns → [Prompt Engineering](reference/03-prompt-engineering.md)

**Setup Script Reference**: Argument parsing, state file creation, and validation logic → [Setup Script Reference](reference/04-setup-script-reference.md)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tangledgroup](https://github.com/tangledgroup)
- **Source:** [tangledgroup/tangled-skills](https://github.com/tangledgroup/tangled-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tangledgroup-tangled-skills-agent-ralph-loop-claude
- Seller: https://agentstack.voostack.com/s/tangledgroup
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.