takopi-ralph

Autonomous coding loop plugin for takopi

Ship features while you sleep. Ralph runs AI agents in a loop until all tasks are complete, with built-in safeguards to prevent runaway execution.

Requirements

Quick Start

1. Install

uv tool install takopi-ralph

Or from source:

git clone https://github.com/l3wi/takopi-ralph
cd takopi-ralph
uv pip install -e .

2. Configure

Add to ~/.takopi/takopi.toml:

[ralph]
max_loops = 100

3. Initialize

Start takopi and send:

/ralph init

Answer the interactive questions to generate your prd.json.

4. Start

/ralph start

Ralph will autonomously implement each user story until complete.

Lifecycle

┌─────────────────────────────────────────────────────────────────────────┐
│                              LIFECYCLE                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  INIT                         LOOP                         EXIT          │
│  ────                         ────                         ────          │
│                                                                          │
│  /ralph init                  /ralph start                 Automatic     │
│       │                            │                            │        │
│       ▼                            ▼                            │        │
│  ┌─────────┐                 ┌───────────┐                      │        │
│  │ Answer  │                 │ Load PRD  │◄─────────────────────┤        │
│  │questions│                 │ next_story│                      │        │
│  └────┬────┘                 └─────┬─────┘                      │        │
│       │                            │                            │        │
│       ▼                            ▼                            │        │
│  ┌─────────┐                 ┌───────────┐                      │        │
│  │ Generate│                 │  Augment  │                      │        │
│  │ prd.json│                 │  prompt   │                      │        │
│  └─────────┘                 └─────┬─────┘                      │        │
│                                    │                            │        │
│                                    ▼                            │        │
│                              ┌───────────┐                      │        │
│                              │ Run Claude│                      │        │
│                              │    CLI    │                      │        │
│                              └─────┬─────┘                      │        │
│                                    │                            │        │
│                                    ▼                            │        │
│                              ┌───────────┐     ┌────────────┐   │        │
│                              │  Analyze  │────►│  Update    │   │        │
│                              │ response  │     │circuit brkr│   │        │
│                              └─────┬─────┘     └────────────┘   │        │
│                                    │                            │        │
│                                    ▼                            │        │
│                              ┌───────────┐                      │        │
│                              │Exit signal│──────────────────────┘        │
│                              │  check    │                               │
│                              └─────┬─────┘                               │
│                                    │ no                                  │
│                                    ▼                                     │
│                               Loop again                                 │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Init Phase

1. /ralph init starts an interactive session
2. Questions cover: core requirements, target users, integrations, edge cases, quality level
3. Answers are used to generate prd.json with user stories

Loop Phase

1. Load prd.json and find the next incomplete story
2. Augment the prompt with Ralph instructions and RALPH_STATUS block requirements
3. Run Claude CLI with the augmented prompt
4. Parse the ---RALPH_STATUS--- block from Claude's response
5. Update circuit breaker state based on file changes and errors
6. Check exit conditions

Exit Conditions

• EXIT_SIGNAL: true in status block
• All stories have passes: true
• Circuit breaker is OPEN
• Max loops reached
• 3+ consecutive test-only loops (test saturation)

Context Targeting

Ralph supports targeting different projects and branches:

/ralph [project] [@branch] <command>

Examples

How It Works

1. Project resolution: Takopi resolves project aliases from your takopi.toml
2. Branch resolution: @branch targets git worktrees managed by takopi
3. Fallback: Without project/branch, uses current working directory

Project Configuration

Projects are defined in your takopi config:

[projects.myproject]
path = "/path/to/myproject"

Commands

Monitoring Status

Check Progress

/ralph status

Returns:

• Current loop number
• Stories completed / total
• Circuit breaker state (CLOSED/HALF_OPEN/OPEN)
• Last work type (IMPLEMENTATION/TESTING/etc.)
• Recent file changes

State Files

Ralph creates a .ralph/ directory in your project:

Debugging Stuck Loops

1. Check /ralph status for circuit breaker state
2. Review .ralph/state.json for loop history
3. Look at recent RALPH_STATUS blocks in conversation
4. If circuit breaker is OPEN, run /ralph reset

Configuration

Add to ~/.takopi/takopi.toml:

[ralph]
# Maximum loop iterations before forced exit
max_loops = 100

# Path to prd.json relative to project root
prd_path = "prd.json"

# Directory for Ralph state files
state_dir = ".ralph"

# Inner engine to use (only "claude" supported currently)
engine = "claude"

All options have sensible defaults. Minimal config:

[ralph]
max_loops = 100

PRD Format

The Product Requirements Document (prd.json) tracks user stories:

{
  "project_name": "My App",
  "description": "A task management application",
  "created_at": "2026-01-10T12:00:00Z",
  "branch_name": null,
  "quality_level": "production",
  "feedback_commands": {
    "typecheck": "bun run typecheck",
    "test": "bun run test",
    "lint": "bun run lint"
  },
  "stories": [
    {
      "id": 1,
      "title": "Project Setup",
      "description": "Initialize project with basic structure",
      "acceptance_criteria": [
        "Project structure created",
        "Dependencies installed"
      ],
      "passes": false,
      "priority": 1,
      "notes": ""
    }
  ]
}

Story Fields

Quality Levels

Feedback Commands

Customize validation commands for your stack:

{
  "feedback_commands": {
    "typecheck": "bun run typecheck",
    "test": "pytest -q",
    "lint": "ruff check ."
  }
}

RALPH_STATUS Block

Claude must include this block at the end of each response:

---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
TASKS_COMPLETED_THIS_LOOP: <number>
FILES_MODIFIED: <number>
TESTS_STATUS: PASSING | FAILING | NOT_RUN
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
EXIT_SIGNAL: false | true
RECOMMENDATION: <one-line summary of what to do next>
---END_RALPH_STATUS---

Exit Signal Conditions

Set EXIT_SIGNAL: true when:

• All stories in prd.json have passes: true
• All tests are passing
• No errors in the last execution
• Nothing meaningful left to implement

Circuit Breaker

Prevents runaway token consumption using a state machine:

CLOSED ──(2 loops no progress)──► HALF_OPEN ──(threshold)──► OPEN
   ▲                                    │
   └────(progress detected)─────────────┘

States

Thresholds

Reset

/ralph reset         # Reset circuit breaker only
/ralph reset --all   # Reset circuit breaker and clear all state

File Structure

After running Ralph, your project will have:

my-project/
├── prd.json                    # User stories (from /ralph init)
├── .ralph/
│   ├── state.json              # Loop state and history
│   ├── session.json            # Claude session ID
│   ├── circuit_breaker.json    # Circuit breaker state
│   └── clarify_sessions.json   # Active clarify sessions
└── ... your project files

Troubleshooting

Circuit Breaker is OPEN

The circuit breaker opens when:

• No file changes for 3+ consecutive loops
• Same error repeated 5+ times

Fix:

/ralph reset

No RALPH_STATUS Block

If Claude doesn't include the status block, the analyzer falls back to text analysis. Check:

1. The prompt template includes status block instructions
2. Claude isn't truncating the response

Loop Exits Immediately

Check:

1. prd.json exists and has stories with passes: false
2. Circuit breaker is CLOSED (/ralph status)
3. No syntax errors in prd.json

Clarify Session Expired

Clarify sessions are stored temporarily. Start a new one:

/ralph init

Development

Setup

git clone https://github.com/l3wi/takopi-ralph
cd takopi-ralph
uv sync --dev

Commands

uv run pytest              # Run tests with coverage
uv run ruff check .        # Lint
uv run ruff format .       # Format

Package Structure

src/takopi_ralph/
├── engine/              # Engine backend (RalphRunner)
├── command/             # Command backend (/ralph)
│   └── handlers/        # Subcommand handlers
├── prd/                 # prd.json management
├── state/               # Loop state persistence
├── circuit_breaker/     # Runaway protection
├── analysis/            # Response parsing
├── clarify/             # Interactive requirements
│   └── templates/       # Prompt templates
└── init/                # Initialization flow

License

MIT

Credits

• Ralph concept: Geoffrey Huntley and Ryan Carson
• ralph-claude-code: Frank Bria
• takopi: banteg