Autonomous Claude Code runner that executes tasks from a backlog or feature plans
npm install ralph-runAutonomous Claude Code runner for hands-off task execution.
Ralph runs Claude Code in a loop, working through backlog tasks or feature plans until complete, stuck, or max iterations reached.
``bash`
npm install -g ralph-run
Ralph checks for updates on startup and notifies you when a new version is available.
In any project where you want to use Ralph:
`bash`
ralph setup
This creates:
- .ralph/backlog.json - Task backlog.ralph/state.json
- - Runner state.ralph/progress.txt
- - Progress log
Set NTFY_URL in your environment to receive notifications when Ralph completes, errors, or gets stuck:
`bash`
export NTFY_URL=https://ntfy.sh/your-topic
Work through tasks in .ralph/backlog.json:
`bash`
ralph backlog # Run loop until complete or max iterations
ralph backlog --once # Single iteration
ralph backlog --resume # Resume from last iteration
ralph backlog --max-iterations 100
Run a specific feature plan from .ralph/features/:
`bash`
ralph feature
ralph feature
Feature directories contain:
- plan.md - Feature plan and contexttasks.json
- - Task breakdownprogress.txt
- - Progress log
`bash`
ralph status # Show current state
ralph cancel # Stop running session
ralph help # Show help
`bash`
ralph completions bash >> ~/.bashrc
`json`
{
"tasks": [
{
"title": "Add user authentication",
"description": "Implement JWT-based auth with refresh tokens",
"acceptance": ["Login endpoint works", "Tokens refresh correctly"],
"branch": "feature/auth",
"passes": false
}
]
}
1. Ralph spawns Claude Code with --permission-mode acceptEdits
2. Claude reads the backlog/feature plan and works on the highest priority task
3. Claude runs linting, type checking, and tests
4. Claude commits and creates/updates a PR
5. If Claude outputs , Ralph exits successfully
6. If Claude outputs
7. Otherwise, Ralph starts the next iteration
- Bun
- Claude Code CLI
- Graphite CLI (for PR workflows)