Metadata-Version: 2.4
Name: claude-ralph-harness
Version: 0.1.0
Summary: Ralph Loop Harness: iterative Claude runner + stream-json renderer
Project-URL: Repository, https://github.com/alexhughson/claude-ralph-harness
Author: Alex
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 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

```bash
# 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:

```bash
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:

```bash
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):

```bash
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
