mcpField
R
ralph

ralph

github.com/civitaiAgent workflows7.3k62 installsUpdated today
Repository

About ralph

Ralph is an autonomous agent skill that turns project work into prioritized user stories with acceptance criteria and runs them in sessions. It supports pausing, guidance, monitoring, and orchestration of child sessions.

Key features

  1. 01Plan work as PRD user stories
  2. 02Run and monitor agent sessions
  3. 03Pause, resume, and inject guidance
  4. 04Spawn and coordinate child sessions
  5. 05Support code, orchestration, and testing PRDs

Use cases

  1. 01Automate implementation from a structured feature plan
  2. 02Pause work while waiting for an API
  3. 03Guide a running session with new information
  4. 04Split a project across child sessions

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/civitai/civitai --skill ralph

After installing, type/ralphin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.gitignore
ralph.mjs
daemon/
server.mjs
session-manager.mjs
storage.mjs
turn-engine.mjs
ui.html
prompts/
base.md
code.md
orchestrator.md
original.md
testing.md

Details

From the project README

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

TypeUse Case
code (default)Implement features, commit code
orchestratorCoordinate multiple sub-Ralphs
testingBrowser automation testing

Set via "type": "orchestrator" in prd.json.

Full CLI Reference

Run ralph.mjs --help for complete documentation.

Comments

Markdown supported