Ralph - Autonomous Agent
Ralph breaks big projects into user stories and executes them autonomously. The workflow:
-
Create a PRD - Define user stories with acceptance criteria
-
Run it - ralph.mjs create --prd path/to/prd.json --start
-
Monitor - ralph.mjs logs <session-id> --follow
Creating a PRD
Create a project folder and prd.json:
.claude/skills/ralph/projects/<project-name>/prd.json
PRD Structure
{ "description": "Brief description of the feature", "branchName": "feature/my-feature", "userStories": [ { "id": "US001", "title": "Short descriptive title", "description": "As a [user], I want [feature] so that [benefit]", "acceptanceCriteria": [ "Specific testable criterion", "Typecheck passes" ], "priority": 1, "passes": false } ] }
Story Guidelines
-
Priority 1: Foundation - migrations, types, base components
-
Priority 2-3: Core functionality
-
Priority 4+: Secondary features, polish
-
Each story should touch 1-3 files, not 10-file refactors
-
Include "Typecheck passes" in acceptance criteria
CLI Commands
The daemon starts automatically when you run any command.
Running Sessions
Create and start a session
ralph.mjs create --prd path/to/prd.json --start
List all sessions
ralph.mjs list
Check session status
ralph.mjs status <session-id>
Follow logs in real-time
ralph.mjs logs <session-id> --follow
Session Control
Pause a session
ralph.mjs pause <session-id> --reason "Waiting for API"
Resume with guidance
ralph.mjs resume <session-id> --guidance "API is ready on port 3000"
Inject guidance into running session
ralph.mjs inject <session-id> --message "Try using the helper in utils.ts"
Abort a session
ralph.mjs abort <session-id>
Orchestration (Multi-Level)
For orchestrator PRDs that spawn child sessions:
Spawn a child session
ralph.mjs spawn <parent-id> --prd child/prd.json --start
List children of a session
ralph.mjs children <session-id>
Wait for all children to complete
ralph.mjs wait <session-id>
View session tree
ralph.mjs tree <session-id>
Abort parent and all children
ralph.mjs abort <session-id> --cascade
PRD Types
Type Use Case
code (default) Implement features, commit code
orchestrator
Coordinate multiple sub-Ralphs
testing
Browser automation testing
Set via "type": "orchestrator" in prd.json.
Full CLI Reference
Run ralph.mjs --help for complete documentation.