Ralph

!Ralph

Ralph is a minimal, file-based agent loop for autonomous coding. Each iteration starts fresh, reads the same on-disk state, and commits work for one story at a time.

> Fork Note: This is a fork of @iannuttall/ralph with improved agent support and first-run configuration.

What's New in This Fork

$3

- Web Dashboard - Real-time monitoring UI for managing multiple projects from a single interface (ralph dashboard) -- see Dashboard
- Automatic Retry - Transient errors (API timeouts, rate limits) trigger automatic retries with exponential backoff
- Story Blocking - Stories that fail repeatedly are automatically blocked to prevent infinite loops
- Git Cleanup - Failed iterations automatically clean up uncommitted changes
- Lean Progress Log - Detailed run info moved to .ralph/runs/, keeping progress.md concise

$3

- First-run agent selection - Prompted to choose your default agent on first use
- ralph config command - Reconfigure your default agent anytime
- Improved Claude support - Uses stdin mode (-p -) for reliable prompt passing
- Better Windows compatibility - Fixed shell quoting and Python detection
- Global config storage - Settings persist in ~/.ralph/config.json

How It Works

Ralph treats files and git as memory, not the model context:

- PRD (JSON) - Defines stories, quality gates, and status
- Loop - Executes one story per iteration
- State - Persists in .ralph/ directory

!Ralph architecture

Installation

$3

``bash
npm i -g @canivel/ralph
`

$3

`bash
git clone https://github.com/canivel/ralph.git
cd ralph
npm install
npm link
`

$3

You need at least one AI agent CLI installed:

| Agent | Install Command |
|-------|-----------------|
| Claude | curl -fsSL https://claude.ai/install.sh \| bash |
| Codex | npm i -g @openai/codex |
| Droid | curl -fsSL https://app.factory.ai/cli \| sh |
| OpenCode | curl -fsSL https://opencode.ai/install.sh \| bash |

Quick Start

`bash

1. Navigate to your project

cd my-project

2. Generate a PRD (first run prompts for agent selection)

ralph prd "A task management app with projects and due dates"

3. Build one story at a time

ralph build 1
`

On first run, you'll see the agent selection prompt:

`
Ralph Configuration
? Select your default agent
> claude (Anthropic Claude CLI)
codex (OpenAI Codex CLI)
droid (Factory Droid CLI)
opencode (OpenCode CLI)
`

Commands

| Command | Description |
|---------|-------------|
| ralph prd [""] | Generate a PRD JSON file via agent |
| ralph build [n] | Run n build iterations (default: continuous) |
| ralph config | Configure or change default agent |
| ralph install | Copy templates to current repo for customization |
| ralph install --skills | Install required skills (commit, dev-browser, prd) |
| ralph overview | Generate human-readable overview from PRD |
| ralph ping | Health check for agent connectivity |
| ralph log "" | Append to activity log |
| ralph dashboard | Start the Ralph dashboard web server |
| ralph help | Show help message |

$3

| Option | Description |
|--------|-------------|
| --agent | Override agent (codex, claude, droid, opencode) |
| --prd | Override PRD file path |
| --out | Override PRD output path (for prd command) |
| --progress | Override progress log path |
| --no-commit | Dry run without committing (for build command) |
| --force | Force overwrite (for install command) |

Usage Examples

$3

`bash

Interactive mode - prompts for description

ralph prd

Direct mode - pass description as argument

ralph prd "A REST API for user authentication with JWT tokens"

Specify output path

ralph prd --out .agents/tasks/prd-auth.json "Auth API"
`

$3

`bash

Build one story

ralph build 1

Build 5 stories

ralph build 5

Dry run (no commits)

ralph build 1 --no-commit

Use specific PRD file

ralph build 1 --prd .agents/tasks/prd-auth.json

Override agent for this run

ralph build 1 --agent codex
`

$3

`bash

Change default agent

ralph config

Install templates for customization

ralph install

Install skills (commit, dev-browser, prd)

ralph install --skills
`

Configuration

$3

Ralph stores global settings in ~/.ralph/config.json:

`json
{
"defaultAgent": "claude",
"configuredAt": "2026-01-19T12:00:00.000Z"
}
`

To change your default agent:

`bash
ralph config
`

$3

After running ralph install, you can customize behavior in .agents/ralph/config.sh:

`bash

Override agent command (Claude uses stdin mode by default)

AGENT_CMD="claude --dangerously-skip-permissions -p -"

Build settings

NO_COMMIT=false
MAX_ITERATIONS=25
STALE_SECONDS=0
`

Template Hierarchy

Ralph looks for templates in this order:

1. .agents/ralph/ in current project (if present)
2. Bundled defaults from the package

State and logs always go to .ralph/ in the project.

PRD Story Status

The build loop automatically updates story status:

| Status | Meaning |
|--------|---------|
| open | Available for selection |
| in_progress | Currently being worked on (with startedAt) |
| done | Completed (with completedAt) |
| blocked | Too many failures (with blockedReason) |

If a loop crashes while a story is in_progress, set STALE_SECONDS in config to auto-reopen stalled stories.

Error Handling & Retry

Ralph includes robust error handling for transient failures:

$3

When the agent fails with a transient error (API timeouts, rate limits, connection resets), Ralph automatically retries:

`
╔═══════════════════════════════════════════════════════════╗
║ Transient error detected, retrying (1/3)...
╚═══════════════════════════════════════════════════════════╝
`

Detected transient errors:
- "No messages returned" (Claude CLI)
- Rate limit errors
- API overload errors
- Connection resets (ECONNRESET, ETIMEDOUT)
- Socket hang up

$3

If a story fails repeatedly (default: 3 times), it's automatically marked as blocked:

`json
{
"id": "US-001",
"status": "blocked",
"blockedReason": "Failed 3 times"
}
`

Blocked stories are skipped in subsequent iterations. To retry a blocked story, manually change its status back to open in the PRD JSON.

$3

When an iteration fails, Ralph automatically cleans up uncommitted changes to prevent polluting the next iteration:

`bash

Automatic cleanup on failure

git checkout -- .
git clean -fd
`

$3

Control retry behavior in .agents/ralph/config.sh:

`bash

Number of retries per iteration for transient errors (default: 3)

MAX_RETRIES=3

Delay between retries in seconds (default: 5)

RETRY_DELAY=5

Max failures before blocking a story (default: 3)

MAX_STORY_FAILURES=3
`

State Files

All state is stored in .ralph/ in your project:

| File | Purpose |
|------|---------|
| progress.md | Append-only progress log |
| guardrails.md | Lessons learned ("Signs") |
| activity.log | Activity and timing log |
| errors.log | Repeated failures and notes |
| runs/ | Raw run logs and summaries |

Dashboard

Ralph includes a real-time web dashboard for monitoring and managing multiple projects from a single interface. Run several autonomous builds in parallel and track all of them from one place.

`bash
ralph dashboard --open
`

$3

The dashboard landing page shows every registered project as a card. Each card displays the project name, path, story completion progress, and last activity time. Click any card to drill into that project's full detail view.

!Ralph Dashboard — Projects

Adding projects:

There are three ways to register projects with the dashboard:

1. Auto-detect -- If the current directory contains a .ralph/ folder, it is registered automatically when you start the dashboard.
2. CLI flag -- Pass multiple project paths at launch:
`bash
ralph dashboard --projects ~/project-a,~/project-b,~/project-c
`
3. From the UI -- Click the Add Project button in the top-right corner, browse to a directory that contains a .ralph/ folder, and add it. Projects can be added at any time without restarting the server.

Any directory with a .ralph/ folder is a valid Ralph project. You can mix and match projects that use different agents or PRDs.

$3

Click a project card to open its detail view. The header shows the project name, status (Idle / Running), path, story progress bar, and run count. Below that, seven tabs give you full visibility into the build.

!Ralph Dashboard — Story Board

| Tab | What It Shows |
|-----|---------------|
| Overview | Story progress bar, quality gates, recent activity feed, current iteration status |
| Stories | Kanban board with Open, In Progress, and Done columns. Cards show story ID, title, blocked/dependency status, and elapsed time |
| Runs | Timeline of every iteration with duration, success/failure status, and expandable raw output |
| Logs | Browsable activity log, error log, and per-run logs with search and filtering |
| Progress | Rendered progress.md with syntax highlighting |
| Guardrails | Rendered guardrails.md with color-coded Sign entries |
| Metrics | Charts for completion rate, iteration durations, and success/failure rates over time |

$3

- Real-time Updates -- WebSocket-based live updates as files change on disk; no manual refresh needed
- Multi-project Support -- Switch between projects from the landing page or the sidebar to monitor parallel builds
- Story Dependency Tracking -- Blocked stories show which dependency they are waiting on (e.g. "Waiting on: US-005")
- Elapsed Time Tracking -- In-progress and completed stories display elapsed time
- Connection Status -- A live indicator in the header shows the WebSocket connection state
- Dark / Light Mode -- Toggle between themes
- Responsive Design -- Works on desktop and mobile

$3

| Option | Description |
|--------|-------------|
| --port | Port to run the server on (default: 4242) |
| --host | Host to bind to (default: localhost) |
| --open | Open browser automatically after starting |
| --projects | Comma-separated project paths to register |

`bash

Examples

ralph dashboard # default port 4242
ralph dashboard --port 8080 # custom port
ralph dashboard --open # auto-open browser
ralph dashboard --host 0.0.0.0 # expose on all interfaces
ralph dashboard --projects ~/app-a,~/app-b,~/app-c # register three projects
`

$3

- Frontend: React 19, TypeScript, Vite, Tailwind CSS, shadcn/ui, Recharts
- Backend: Express, WebSocket (ws), chokidar (file watching)
- State: Zustand for client state management

$3

`bash

Run all dashboard tests (113 tests)

npm run test:dashboard

Tests cover:

- Data parsers (PRD, activity log, errors log, progress.md, guardrails.md)

- Project manager service

- API endpoints

`

Advanced

$3

If you have multiple PRD JSON files in .agents/tasks/ and don't specify --prd, Ralph will prompt you to choose.

$3

For faster performance with OpenCode, run opencode serve in a separate terminal and uncomment the server mode lines in .agents/ralph/agents.sh:

`bash
AGENT_OPENCODE_CMD="opencode run --attach http://localhost:4096 \"\$(cat {prompt})\""
`

$3

Agents are passed prompts via stdin by default. Use {prompt} placeholder when the agent needs a file path instead:

`bash

Stdin mode (default for claude, codex)

AGENT_CMD="my-agent -"

File path mode (for agents that require a file)

AGENT_CMD="my-agent --file {prompt}"
`

Development

$3

`bash

Dry-run smoke tests (no agent required)

npm test

Fast agent health check

npm run test:ping

Integration tests (requires agents)

RALPH_INTEGRATION=1 npm test

Full real-agent loop test

npm run test:real
`

$3

`bash
npm login
npm publish --access public
``

License

MIT