rw-runner

Autonomous task runner powered by Claude. Define tasks, set completion requirements, and let Claude work through them autonomously.

Install

# Using bun (recommended)
bun install -g rw-runner

# Using npm
npm install -g rw-runner

Requirements: Claude Code CLI must be installed and authenticated.

Quick Start

# Initialize rw in your project
rw init

# Add a task
rw add task

# Add context files Claude can reference
rw add resource

# Start the autonomous loop
rw run

How It Works

┌─────────────────────────────────────────────────────────────────┐
│  RALPH LOOP                                                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. Claude picks the most important pending task                │
│  2. Claude works on it autonomously                             │
│  3. Claude outputs "DONE: task name"                            │
│  4. Ralph runs requirement checks (tests, commands)             │
│     ├── PASS → mark complete, next task                         │
│     └── FAIL → retry with error context (max 3)                 │
│  5. Repeat until all tasks complete                             │
│                                                                  │
│  HOTKEYS:                                                        │
│    [t] - takeover (jump into Claude session)                    │
│    [q] - quit                                                    │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Commands

| Command | Description | |---------|-------------| | rw init | Initialize rw in current directory | | rw add task | Add a task interactively | | rw add resource | Add a context file | | rw validate | Check spec.md syntax | | rw status | Show task completion status | | rw run | Start the autonomous loop |

spec.md Format

# Spec

## Tasks
- [ ] Implement user authentication
  - [run]: `npm test`
    [expect]: PASS
    [expect-not]: FAIL

- [ ] Add rate limiting
  - [run]: `go test ./...`
    [expect-exit]: 0
  - [run]: `curl localhost:3000/health`
    [eval]: "Returns 200 OK"

## Resources
[file]: `docs/architecture.md`
High-level system design. Read this first.

[file]: `docs/api.md`
API endpoint documentation.

Task States

• [ ] - pending
• [x] - completed
• [!] - failed (skipped after 3 retries)

Requirement Checks

| Check | Description | |-------|-------------| | [expect] | Output must contain this string | | [expect-not] | Output must NOT contain this string | | [expect-exit] | Exit code must match | | [eval] | LLM evaluates output against criteria |

Configuration

Global config at ~/.rw/config.yaml:

# Model for LLM evaluations
model: claude-sonnet

# Max retries before marking task as failed
max_retries: 3

# Delay between loop iterations (seconds)
loop_delay: 2

Takeover Mode

Press t during rw run to jump into the active Claude session. This lets you:

• Provide additional context
• Guide Claude through tricky parts
• Fix issues manually

When you exit (Ctrl+D or /exit), Ralph asks if you want to run requirements, then continues the loop.

License

MIT