ralph-agent

Ralph Agent

A Claude Code plugin that automatically executes implementation plans. Give it a task list and it implements each one in order, fixes itself until verification passes, then moves to the next task.

Why Use This

• Continuous Execution: Finishes one task and automatically moves to the next. No need to manually prompt each step
• Verification Gating: Tasks are only marked complete when tests/linting pass. The agent cannot stop and claim "done" without proof
• Loop Detection: Warns and forces strategy reconsideration if the same file is edited 5+ times
• File Protection: Blocks writes to sensitive files like .env, *.pem, *.key
• Context Preservation: Re-injects current progress and verification commands even after conversation compaction

Installation

Run two commands in Claude Code:

# 1. Add the marketplace
/plugin marketplace add tmdgusya/roach-loop

# 2. Install the plugin
/plugin install ralph-agent@ralph-agent-marketplace

To update:

/plugin update ralph-agent

Quick Start

Three steps: create a plan → set up verification → execute. Each step has options you can mix and match.

Step 1: Create a Plan

Choose one:

Option A: Write tasks manually

/ralph-agent:ralph-init

Open IMPLEMENTATION_PLAN.md and fill in tasks:

# Implementation Plan

## Tasks
- [ ] Create SQLAlchemy User model (id, email, name, created_at)
- [ ] Implement POST /users endpoint with input validation
- [ ] Implement GET /users/:id endpoint with 404 handling
- [ ] Write pytest tests for all endpoints

Option B: Auto-generate from specs

Create a specs/ directory with requirement files:

# specs/user-auth.md

## Feature: User Authentication

### Requirements
- Users can register with email/password
- Users can login with JWT tokens
- Passwords are hashed with bcrypt

Then generate the plan:

/ralph-agent:gplan

This analyzes your specs and creates IMPLEMENTATION_PLAN.md automatically. You can review and edit it before running.

Step 2: Set Up Verification

Create AGENTS.md in your project root:

# Verification Commands
- `pytest tests/ -v`
- `ruff check .`

The agent runs these after each task. All must pass before a task is marked complete.

Step 3: Execute

Choose one:

# Execute tasks, no Git management (you commit manually)
/ralph-agent:ralph

# Execute tasks + automatic git commit → push → tag (0.0.0, 0.0.1, ...)
/ralph-agent:gbuild

Both find the first unchecked task (- [ ]), implement it, run verification, mark it - [x], and move to the next. The only difference is whether Git is handled automatically.

Combining freely

Plan creation and execution are independent — mix however you like:

Plan	Execute	Use when
gplan (auto)	ralph	Specs exist, but you handle Git yourself
gplan (auto)	gbuild	Specs exist, want full automation
ralph-init (manual)	ralph	Simple task list, manual Git
ralph-init (manual)	gbuild	Simple task list, want auto Git

Practical Tips

Writing good tasks

Specific, independent tasks dramatically improve Ralph's success rate.

Bad	Good
"Work on auth"	"Implement JWT-based POST /auth/login endpoint"
"Add tests"	"Write pytest tests for User model CRUD operations"
"Refactor"	"Extract DB logic from UserService into UserRepository"

Principles:

• One task = one verifiable outcome
• Tasks should not depend on each other's completion order
• 30 minutes to 2 hours of work per task is ideal

Verification command setup

List verification commands in AGENTS.md, ordered fastest first:

# Verification Commands
- `ruff check .`          # Lint (fast)
- `mypy src/`             # Type check (medium)
- `pytest tests/ -v`      # Tests (slow)

Ralph runs all of these after each task. All must pass before a task is marked complete. If any fail, Ralph fixes the code and retries.

Iteration limits

For long-running sessions, you can cap the number of tasks:

# Process only 5 tasks then stop
/ralph-agent:ralph --max-iterations=5

# Pause for user review between tasks
/ralph-agent:loop ralph max=5 pause=true

Stopping mid-session

Type stop or cancel while Ralph is working. It will finish the current task, save progress to IMPLEMENTATION_PLAN.md, and stop. Run /ralph-agent:ralph later to resume from where it left off.

Things to Know

The .harness/ directory

Ralph creates a .harness/ directory in your project root during execution:

.harness/
├── state.json          # Session state (current task, verification results, etc.)
├── edit-tracker.json   # Per-file edit counts (for loop detection)
└── trace-log.jsonl     # Log of all tool calls

This is for session state tracking. Add it to .gitignore:

.harness/