Ralphe 0.1.1

Ralphe

Ralphe is a loop orchestrator for Claude Code. It automates task execution described as GitHub Issues — from implementation, through review, to commit and issue closure.

How it works

Ralphe fetches the specified GitHub Issue along with its sub-issues, then runs an agent pipeline for each open sub-issue. The pipeline is fully dynamic — you can define multiple named pipelines and assign them per sub-issue.

By default (without configuration), Ralphe uses a single-agent pipeline with a default agent that implements the task, verifies it (including running tests when appropriate), and reports a verdict. Each sub-issue can specify a different pipeline using a GitHub Alert in the issue body:

> [!IMPORTANT]
> Do not remove this. Ralphe uses this to select the agent pipeline for this issue.
> pipeline: tdd

If the last agent in the pipeline approves the changes (PASS), Ralphe commits them and closes the issue. If it rejects (FAIL), the pipeline is retried with feedback — up to 10 times.

Requirements

• .NET 10 SDK
• Claude Code CLI (claude) available in PATH
• GitHub repository with a configured token (gh auth login)

Installation

dotnet tool install -g Ralphe

# Update to the latest version:
dotnet tool update -g Ralphe

Usage

ralphe <issue-number> [options]
ralphe init

Options

Commands

Examples

ralphe 42                              # Process issue #42 with default settings
ralphe 42 --debug                      # With debug logging
ralphe 42 --max-retries 5              # Maximum 5 attempts per sub-issue
ralphe init                            # Initialize project configuration

Interruption (Ctrl+C)

• First Ctrl+C — graceful shutdown: Ralphe cancels current operations, kills Claude processes, and exits with code 130
• Second Ctrl+C — force quit: immediate process termination

Exit codes

Configuration

Configuration hierarchy: CLI args > ralphe.yml > hardcoded defaults.

Run ralphe init to generate .claude/ralphe/ralphe.yml with default values:

max-retries: 10
claude-path: claude
disallowed-tools:
  - "Bash(git:*)"
log-directory: .temp/ralphe

pipelines:
  require-match: false
  .default:
    description: Default pipeline
    agents:
      - name: default
        model: opus

Prompt templates

To use custom prompts for an agent, set SystemPrompt or UserPrompt in the agent definition to a file path. The file will be loaded at runtime.

Template variables

Use {{VARIABLE_NAME}} in prompt files. Variables are replaced with values from the pipeline context:

Conditional blocks

Use {{#if KEY}}...{{/if}} to include a section only when the variable is non-empty:

{{#if RETRY_FEEDBACK}}
## Previous feedback (attempt {{ATTEMPT_NUMBER}})
{{RETRY_FEEDBACK}}
{{/if}}

Custom agent pipelines

Pipelines are defined in ralphe.yml under the pipelines key. Prompt directories are located in .claude/ralphe/pipelines/. Use ralphe init to generate the structure, or create it manually:

Directory structure:

.claude/ralphe/
  ralphe.yml                        # configuration + pipeline definitions
  pipelines/                       # prompt directory
    tdd/
      01-test-writer/              # numeric prefix = fallback ordering
        prompt-system.md           # required
        prompt-user.md             # required
      02-implementor/
        prompt-system.md
        prompt-user.md
      03-reviewer/
        prompt-system.md
        prompt-user.md

Pipeline definition in ralphe.yml:

pipelines:
  require-match: false
  tdd:
    description: "TDD red-green-refactor pipeline"
    agents:
      - name: test-writer
        model: opus                # optional, default: sonnet
        timeout: "00:05:00"        # optional, default: 00:10:00
      - name: implementor
        model: opus
      - name: reviewer             # uses default values

Key principles:

• Agents execute sequentially in the order defined in ralphe.yml
• Each agent's output is passed to the next via the {{PREVIOUS_OUTPUT}} variable
• The last agent in the pipeline acts as a gate — it decides the loop outcome
• Agent defaults: model=sonnet, timeout=00:10:00

Pipeline selection per sub-issue — add a GitHub Alert in the issue body:

> [!IMPORTANT]
> Do not remove this. Ralphe uses this to select the agent pipeline for this issue.
> pipeline: tdd

Fallback when no alert is present: default pipeline → first in directory → hardcoded default agent.

Lifecycle hooks

Hooks are Claude agents invoked at specific points of the Ralphe loop. They run synchronously — each hook must complete before the main flow continues.

All hooks share parent issue variables (PARENT_ISSUE_NUMBER, PARENT_ISSUE_TITLE, PARENT_ISSUE_BODY, SUB_ISSUE_COUNT).

Configuration

Hooks are configured in ralphe.yml under the hooks key. All hooks are disabled by default.

hooks:
  on-start:
    enabled: true
    fail-fast: false       # true = error aborts the loop
    model: sonnet
    timeout: 120           # seconds
    disallowed-tools: []   # override global disallowed-tools
  on-end:
    enabled: true
    fail-fast: true

Prompt files

Hook prompts are stored in .claude/ralphe/hooks/{hook-name}/:

.claude/ralphe/hooks/
  on-start/
    prompt-system.md
    prompt-user.md
  on-pre-iteration/
  on-post-iteration/
  on-end/

Run ralphe init to generate placeholder prompt files for all hooks.

Per-agent disallowed-tools

The disallowed-tools setting can be overridden per agent (in pipeline definitions) or per hook. If not specified, the global disallowed-tools value is used as a fallback.

disallowed-tools:
  - "Bash(git:*)"           # global fallback

pipelines:
  .default:
    agents:
      - name: coder
        disallowed-tools:    # override for this agent
          - "Bash(git:*)"
          - "Bash(rm:*)"