Ralph CLI

Lightweight Ralph loop: PRD → ralph start → autonomous execution → done. Simple CLI tool for PRD-driven development with Codex or Claude Code.

Based on Geoffrey Huntley's Ralph pattern and inspired by ralph-mcp.

中文文档

Quick Start

# Install
npm install -g ralph-cli

# Start a task (defaults to Codex)
ralph start ./my-prd.json

# Check status
ralph status

# List all tasks
ralph list

Why Ralph CLI?

Without Ralph	With Ralph CLI
Manual implementation	Autonomous agent execution
Lost progress on restart	Persistent state tracking
Manual git branch management	Automatic worktree isolation
No visibility into progress	Real-time status monitoring
Manual quality checks	Auto quality gates (type check, lint, build)

Features

Simple CLI Interface - Start, stop, and monitor tasks from command line
Git Worktree Isolation - Each task runs in its own worktree, zero conflicts
Dual Agent Support - Use Claude Code or Codex CLI
State Persistence - Task state survives restarts
Quality Gates - Automatic type check, lint, and build before commits
Batch Execution - Start multiple PRDs at once
Watch + Auto-Ingestion - Poll the queue and auto-enqueue new ez4ielts PRDs
Progress Tracking - Monitor task status and completion

Installation

From npm (coming soon)

npm install -g ralph-cli

From source

git clone https://github.com/G0d2i11a/ralph-cli.git
cd ralph-cli
npm install
npm run build
npm link

Usage

Start a new task

ralph start <prd-path> [options]

Options:
  --repo <path>    Repository path (defaults to current directory)
  --agent <name>   Agent to use: claude or codex (default: codex)

Examples:

# Start with the default agent (Codex)
ralph start ./prd-auth.json

# Start with Claude Code explicitly
ralph start ./prd-payment.md --agent claude

# Specify repository
ralph start ./prd-api.json --repo ~/Code/my-project

Batch start multiple PRDs

ralph batch-start prds/*.json

Tasks beyond the configured concurrency limit stay pending and start automatically as running tasks finish.

Watch pending tasks and auto-ingest new ez4ielts PRDs

# Queue safety-net only
ralph watch

# Queue safety-net + auto-ingest brand new ez4ielts PRDs
ralph watch --auto-ingest-ez4ielts

When --auto-ingest-ez4ielts is enabled, Ralph polls the configured ez4ielts PRD directory (set RALPH_EZ4IELTS_WATCH_DIR or configure ingestion.ez4ielts.watchDir in ~/.ralph/config.json) for new files matching ez4ielts-*.json and sends them through the same queue/start flow as ralph start.

Existing matching files are treated as backlog and skipped when the watcher starts.
Each new file is ingested once, even if it is modified again later.
Auto-ingested tasks default to Codex unless --agent claude is passed.
Auto-ingested tasks default to the watched docs directory parent as their repo unless --repo is passed. For your current setup, pass --repo /Users/shawn/Project/ez4ielts so execution happens in the project repo rather than the docs workspace.
New files still respect dependency checks and the configured concurrency limit.

You can also enable the same mode through ~/.ralph/config.json and then run plain ralph watch.

Check task status

# Show all running tasks
ralph status

# Show specific task
ralph status <task-id>

List all tasks

# List all tasks
ralph list

# Filter by status
ralph list --status running
ralph list --status completed
ralph list --status failed

Stop a task

ralph stop <task-id>

Update task progress

ralph update <task-id> --status completed --notes "Implemented authentication"

Retry failed task

ralph retry <task-id>

Merge completed task

ralph merge <task-id>

Reset stagnation detection

ralph reset-stagnation <task-id>

View statistics

ralph stats

PRD Format

Ralph CLI supports both JSON and Markdown formats for PRD files.

JSON Format

{
  "id": "prd-auth",
  "title": "User Authentication System",
  "description": "Implement secure user authentication with JWT",
  "userStories": [
    {
      "id": "US-001",
      "title": "User Registration",
      "description": "As a new user, I want to register an account",
      "acceptanceCriteria": [
        "Email validation",
        "Password strength check",
        "Duplicate email prevention"
      ]
    },
    {
      "id": "US-002",
      "title": "User Login",
      "description": "As a registered user, I want to log in",
      "acceptanceCriteria": [
        "JWT token generation",
        "Session management",
        "Invalid credentials handling"
      ]
    }
  ],
  "dependencies": []
}

Markdown Format

---
id: prd-auth
title: User Authentication System
description: Implement secure user authentication with JWT
userStories:
  - id: US-001
    title: User Registration
    description: As a new user, I want to register an account
    acceptanceCriteria:
      - Email validation
      - Password strength check
      - Duplicate email prevention
  - id: US-002
    title: User Login
    description: As a registered user, I want to log in
    acceptanceCriteria:
      - JWT token generation
      - Session management
      - Invalid credentials handling
dependencies: []
---

## Additional Context

This PRD implements a secure authentication system using industry best practices.

How It Works

Parse PRD - Ralph reads your PRD file and extracts user stories
Create Worktree - Creates a git worktree for isolated development
Spawn Agent - Launches Codex by default, or Claude Code when requested
Track Progress - Maintains state in ~/.ralph/tasks/<task-id>/
Quality Gates - Runs type check, lint, and build before commits
Watch + Queue - ralph watch can keep the queue moving and auto-ingest new ez4ielts PRDs
Complete - Marks task as completed when all user stories pass

State Management

Task state is stored in ~/.ralph/tasks/<task-id>/state.json:

{
  "id": "task-xxx",
  "prdId": "prd-auth",
  "status": "running",
  "currentUS": "US-001",
  "completedUS": [],
  "failedUS": [],
  "worktree": "/path/to/worktree",
  "logPath": "/path/to/log",
  "agent": "codex",
  "createdAt": "2026-03-07T10:00:00Z",
  "updatedAt": "2026-03-07T10:30:00Z"
}

Agents

Claude Code

Uses Claude Opus 4 via LiteLLM proxy.

Requirements:

Claude Code CLI installed (npm install -g @anthropic/claude-code)
LiteLLM running on localhost:4000

Environment variables:

export ANTHROPIC_BASE_URL=http://localhost:4000/v1
export ANTHROPIC_API_KEY=<your-litellm-master-key>

Command:

ralph start ./prd.json --agent claude

Codex

Uses GPT-5.3 Codex via LiteLLM proxy.

Requirements:

Codex CLI installed
LiteLLM running on localhost:4000

Environment variables:

export OPENAI_BASE_URL=http://localhost:4000/v1
export OPENAI_API_KEY=<your-litellm-master-key>

Command:

ralph start ./prd.json

Configuration

Ralph CLI stores configuration in ~/.ralph/config.json:

{
  "agent": {
    "path": "codex",
    "timeout": 600,
    "model": "claude-opus-4-6-thinking-xchai"
  },
  "runner": {
    "maxConcurrent": 3,
    "stagnationTimeout": 1800,
    "pollInterval": 10
  },
  "ingestion": {
    "ez4ielts": {
      "enabled": false,
      "watchDir": "/absolute/path/to/your/ez4ielts-prds",
      // Or set RALPH_EZ4IELTS_WATCH_DIR to override this per machine.
      "pattern": "ez4ielts-*.json",
      "settleMs": 2000
    }
  },
  "notification": {
    "enabled": false,
    "channel": "feishu",
    "target": ""
  }
}

agent.path defaults to codex in the generated config. New tasks also default to Codex unless --agent claude is passed. agent.model is only used for Claude runs.

Set concurrency to 2 by changing runner.maxConcurrent:

{
  "runner": {
    "maxConcurrent": 2
  }
}

Enable ez4ielts auto-ingestion by changing ingestion.ez4ielts.enabled to true and then running ralph watch:

{
  "ingestion": {
    "ez4ielts": {
      "enabled": true
    }
  }
}

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Run tests
npm test

Architecture

src/
├── cli.ts              # CLI entry point
├── worker.ts           # Background worker process
├── types/
│   ├── prd.ts         # PRD data structures
│   └── task.ts        # Task data structures
├── core/
│   ├── state.ts       # State management
│   ├── worktree.ts    # Git worktree operations
│   ├── agent.ts       # Agent execution
│   ├── task-intake.ts # Shared PRD queueing logic
│   ├── prd-auto-ingest.ts # ez4ielts PRD auto-ingestion
│   └── merge.ts       # Merge operations
├── commands/
│   ├── start.ts       # Start command
│   ├── batch-start.ts # Batch start command
│   ├── status.ts      # Status command
│   ├── list.ts        # List command
│   ├── stop.ts        # Stop command
│   ├── update.ts      # Update command
│   ├── retry.ts       # Retry command
│   ├── merge.ts       # Merge command
│   ├── stats.ts       # Statistics command
│   └── completion.ts  # Shell completion
├── config/
│   └── manager.ts     # Configuration management
└── utils/
    └── helpers.ts     # Utility functions

Comparison with Ralph MCP

Feature	Ralph CLI	Ralph MCP
Interface	Command line	MCP protocol (Claude Desktop)
Agent Support	Claude Code, Codex	Claude Code only
Parallel Execution	Automatic queueing up to configured concurrency	Automatic (Runner)
Dependency Management	Automatic task queueing	Automatic
Stagnation Detection	Manual reset	Automatic
Notifications	None	Windows Toast
Best For	CLI users, Codex support	Claude Desktop integration

Troubleshooting

Task stuck in "running" state

# Check task status
ralph status <task-id>

# Reset stagnation detection
ralph reset-stagnation <task-id>

# Stop and retry
ralph stop <task-id>
ralph retry <task-id>

Agent not found

Make sure the agent CLI is installed and in your PATH:

# For Claude Code
which claude

# For Codex
which codex

LiteLLM connection error

Check that LiteLLM is running:

curl http://localhost:4000/health

License

MIT

Credits

Based on Geoffrey Huntley's Ralph pattern
Inspired by ralph-mcp
Built with Commander.js

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
docs/proposals		docs/proposals
src		src
test		test
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Ralph CLI

Quick Start

Why Ralph CLI?

Features

Installation

From npm (coming soon)

From source

Usage

Start a new task

Batch start multiple PRDs

Watch pending tasks and auto-ingest new ez4ielts PRDs

Check task status

List all tasks

Stop a task

Update task progress

Retry failed task

Merge completed task

Reset stagnation detection

View statistics

PRD Format

JSON Format

Markdown Format

How It Works

State Management

Agents

Claude Code

Codex

Configuration

Development

Architecture

Comparison with Ralph MCP

Troubleshooting

Task stuck in "running" state

Agent not found

LiteLLM connection error

License

Credits

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages