ralph

Ralph - Autonomous Agent

Ralph breaks big projects into user stories and executes them autonomously. The workflow:

1. Create a PRD - Define user stories with acceptance criteria
2. Run it - ralph.mjs create --prd path/to/prd.json --start
3. 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.