claude-ralph-harness

Ralph Loop Harness: iterative Claude runner + stream-json renderer.

Two modes:

• render - Reads JSONL from stdin and renders a human-friendly terminal view of Claude Code's stream-json output
• loop - Drives Claude iteratively until a completion promise is detected

Stdlib only, no external dependencies.

Install

# from PyPI
uvx claude-ralph-harness

# or install globally
uv tool install claude-ralph-harness

Usage

Render mode

Pipe Claude Code's stream-json output for a readable terminal view:

claude -p --output-format stream-json --verbose "your prompt" | claude-ralph-harness render

Options:

--show-thinking     Display thinking block content
--no-color          Disable ANSI color codes
--verbose           Show raw JSON for unrecognized events
--show-tool-output  Show full tool result content

If stdin is piped and no subcommand is given, render mode is the default:

claude -p --output-format stream-json --verbose "prompt" | claude-ralph-harness

Loop mode

Run Claude iteratively until it outputs a <promise>SKILL COMPLETE</promise> tag (or a custom phrase):

claude-ralph-harness loop --prompt PROMPT.md --max-iterations 50

Options:

--prompt FILE              Path to the prompt markdown file (required)
--completion-phrase TEXT    Phrase inside <promise> tags that signals completion
                           (default: SKILL COMPLETE)
--max-iterations N         Maximum number of iterations (default: 50)
--working-dir DIR          Working directory for claude subprocess (default: .)
--show-thinking            Display thinking block content
--verbose                  Show raw JSON for unrecognized events

License

MIT