Ralphe 0.1.6

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".docs/branding/ralphe-logo-dark.svg"/> <source media="(prefers-color-scheme: light)" srcset=".docs/branding/ralphe-logo-light.svg"/> <img src=".docs/branding/ralphe-logo-dark.svg" alt="Ralphe logo" width="96" height="96"/> </picture> </p>

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

<p align="center"> <img src="docs/flow-animation.svg" alt="Ralphe Flow — default pipeline example" width="800"/> </p>

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 42 --reporting summary          # Suppress intermediate agent reports
ralphe init                            # Initialize project configuration
ralphe doctor                          # Verify tools and configuration health

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
reporting: detailed
static-prompt: |
  Always respond in English.

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"
    enabled: true                  # optional, default: true
    agents:
      - name: test-writer
        model: opus                # optional, default: sonnet
        timeout: "00:05:00"        # optional, default: 00:10:00
        pass-output: true          # optional, default: false
      - name: implementor
        model: opus
        receive-output: true       # optional, default: false
        pass-output: true
      - name: reviewer             # uses default values

Key principles:

• Agents execute sequentially in the order defined in ralphe.yml
• Agent output propagation is controlled by two per-agent flags:
  • pass-output: true — agent's output becomes {{PREVIOUS_OUTPUT}} for the next agent (default: false)
  • receive-output: true — agent sees {{PREVIOUS_OUTPUT}} from the previous agent (default: false)
• The last agent in the pipeline acts as a gate — it decides the loop outcome
• Agent defaults: model=sonnet, timeout=00:10:00, pass-output=false, receive-output=false

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.

Comment templates

Ralphe posts comments on GitHub issues to report agent conclusions, pipeline results, and parent issue status. Default templates are embedded in the tool, but you can override them by placing custom files in .claude/ralphe/templates/:

.claude/ralphe/templates/
  comment-agent.md              # per-agent conclusions (skipped in summary mode)
  comment-summary-pass.md       # sub-issue PASS summary
  comment-summary-fail.md       # sub-issue FAIL summary
  comment-parent-pass.md        # parent issue PASS notification
  comment-parent-fail.md        # parent issue FAIL notification

Comment template variables

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
    allowed-tools:         # override global allowed-tools
      - "Bash(gh:*)"
  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 tool overrides

The disallowed-tools and allowed-tools settings can be overridden per agent (in pipeline definitions) or per hook. If not specified, the global values are used as a fallback.

disallowed-tools:
  - "Bash(git:*)"           # global fallback
allowed-tools: []            # global fallback (empty = no extra allowed tools)

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