Minimal, file-based agent loop for autonomous coding. Fork with improved Claude support and first-run configuration.
npm install @canivel/ralphralph dashboard) -- see Dashboard
.ralph/runs/, keeping progress.md concise
ralph config command - Reconfigure your default agent anytime
-p -) for reliable prompt passing
~/.ralph/config.json
.ralph/ directory
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
``