Ralphing - Autonomous AI Coding Loop

Version: 3.1.0

Ralphing is an autonomous AI coding agent that reads tasks from a Product Requirements Document (PRD), implements them one by one, and marks them complete. It supports multiple AI engines (Claude API, OpenCode, Cursor, Codex) and can run tasks sequentially or in parallel.

📦 Two Versions Available

Ralphing comes in two versions optimized for different use cases:

Script	AI Engine	Best For	Default Model
ralphing.sh	Claude API	Production use with Claude API	Claude (Anthropic API)
ralphing_z_ai.sh	z.ai zclaude	Cost-effective development with z.ai	GLM-4-Flash

Quick Start:

• For Claude API users: Use ./ralphing.sh (default)
• For z.ai users: Use ./ralphing_z_ai.sh (optimized for z.ai's GLM-4-Flash model)

Both versions support all the same features (parallel execution, branch-per-task, PR creation, etc.) - the only difference is the AI engine.

Table of Contents

• Features
• Prerequisites
• Installation
• Quick Start
• Usage
  • Basic Commands
  • AI Engine Selection
  • Workflow Options
  • Execution Modes
  • Git Branch Management
  • PRD Source Options
• PRD Formats
• Configuration
• Examples
• How It Works
• Advanced Features
• Troubleshooting
• Best Practices

---

Features

Core Capabilities

• Autonomous Task Execution: Reads tasks from PRD and executes them automatically
• Multiple AI Engines: Supports Claude Code (zclaude), OpenCode, Cursor, and Codex
• Sequential & Parallel Modes: Run tasks one at a time or concurrently (up to N parallel agents)
• Git Integration: Optional branch-per-task workflow with automated PR creation
• Real-time Progress Monitoring: Colorful status indicators and 30-second detailed updates
• Automatic Task Completion Tracking: Marks tasks complete in PRD after successful implementation
• Token Tracking: Monitors API usage and costs across all supported engines
• Retry Logic: Automatic retries on failures with configurable delay

New in 3.1.0

• Colorful Blinking Indicators: Visual feedback with rotating colored ⏺ indicators
• 30-Second Status Updates: Detailed progress reports every 30 seconds
• Reliable Task Completion: Script-level verification ensures PRD is always updated
• Per-Agent Indicators: In parallel mode, see status of each agent with unique colors
• Improved Error Handling: Better detection and reporting of stuck agents

---

Prerequisites

Required

• Bash 4.0+ (macOS and Linux supported)
• jq - JSON parsing (installation)
• Git - Version control
• One of the following AI engines:
  • Claude API via claude CLI (default for ralphing.sh)
  • z.ai zclaude for GLM-4-Flash model (default for ralphing_z_ai.sh)
  • OpenCode
  • Cursor agent
  • Codex CLI

Optional

• GitHub CLI (gh) - For PR creation and GitHub issues (installation)
• yq - YAML parsing for YAML task files (installation)
• bc - Better precision for cost calculations (usually pre-installed)

---

Installation

1. Install Prerequisites

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install jq gh yq bc

# Install Claude Code (recommended)
npm install -g @anthropic/claude-code

Linux (Ubuntu/Debian)

# Install dependencies
sudo apt update
sudo apt install jq bc curl

# Install GitHub CLI
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update
sudo apt install gh

# Install yq
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq

# Install Claude CLI (for ralphing.sh)
npm install -g @anthropic/claude-cli

# OR install z.ai zclaude (for ralphing_z_ai.sh)
# Follow z.ai setup instructions at https://z.ai/

2. Install Ralphing

Choose which version to download based on your AI engine:

Option A: Core Version (Claude API)

# Download ralphing.sh
curl -o ralphing.sh https://raw.githubusercontent.com/arslandevs/ralphing/master/ralphing.sh

# Make it executable
chmod +x ralphing.sh

Option B: Z.AI Version (GLM-4-Flash)

# Download ralphing_z_ai.sh
curl -o ralphing_z_ai.sh https://raw.githubusercontent.com/arslandevs/ralphing/master/ralphing_z_ai.sh

# Make it executable
chmod +x ralphing_z_ai.sh

Option C: Both Versions

# Clone the repository to get both
git clone https://github.com/arslandevs/ralphing.git
cd ralphing
chmod +x ralphing.sh ralphing_z_ai.sh

3. Set Up AI Engine

For Claude API (ralphing.sh)

# Install Claude CLI
npm install -g @anthropic/claude-cli

# Set your Anthropic API key
export ANTHROPIC_API_KEY="your-api-key-here"

# Or add to ~/.bashrc or ~/.zshrc
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc

For z.ai zclaude (ralphing_z_ai.sh)

# Install z.ai zclaude
# Follow instructions at https://z.ai/

# The GLM-4-Flash model is configured by default
# No additional API key needed if using z.ai

For OpenCode

# Follow OpenCode setup instructions
# https://opencode.ai/docs/

For Cursor

# Install Cursor and ensure 'agent' is in your PATH
# https://cursor.com/

---

Quick Start

1. Create a PRD File

Create a PRD.md file in your project root:

# Project Tasks

## Features

- [ ] Add user authentication
- [ ] Create database schema
- [ ] Build API endpoints
- [ ] Add frontend components
- [ ] Write tests
- [ ] Deploy to production

2. Create a Progress File

touch progress.txt

3. Run Ralphing

Using Core Version (Claude API)

# Basic run (sequential mode)
./ralphing.sh

# Run with verbose output
./ralphing.sh --verbose

# Run with parallel execution (3 agents)
./ralphing.sh --parallel --max-parallel 3

# Run with branch-per-task and PR creation
./ralphing.sh --branch-per-task --create-pr

Using Z.AI Version (GLM-4-Flash)

# Basic run (sequential mode)
./ralphing_z_ai.sh

# Run with verbose output
./ralphing_z_ai.sh --verbose

# Run with parallel execution (3 agents)
./ralphing_z_ai.sh --parallel --max-parallel 3

# Run with branch-per-task and PR creation
./ralphing_z_ai.sh --branch-per-task --create-pr

---

Usage

Basic Commands

# Show help
./ralphing.sh --help

# Show version
./ralphing.sh --version

# Dry run (see what would be executed)
./ralphing.sh --dry-run

# Verbose mode (debug output)
./ralphing.sh --verbose

AI Engine Selection

Core Version (ralphing.sh)

# Use Claude API (default)
./ralphing.sh --claude

# Use OpenCode
./ralphing.sh --opencode

# Use Cursor agent
./ralphing.sh --cursor

# Use Codex
./ralphing.sh --codex

# Use z.ai zclaude
./ralphing.sh --zclaude

Z.AI Version (ralphing_z_ai.sh)

# Always uses z.ai zclaude with GLM-4-Flash
# No engine selection needed - it's optimized for z.ai
./ralphing_z_ai.sh

Workflow Options

# Skip tests
./ralphing.sh --no-tests

# Skip linting
./ralphing.sh --no-lint

# Skip both tests and linting (fast mode)
./ralphing.sh --fast

# Limit iterations
./ralphing.sh --max-iterations 5

# Configure retries
./ralphing.sh --max-retries 5 --retry-delay 10

Execution Modes

Sequential Mode (Default)

Runs tasks one at a time in order:

./ralphing.sh

Parallel Mode

Runs multiple tasks concurrently using isolated git worktrees:

# Run 3 tasks in parallel
./ralphing.sh --parallel --max-parallel 3

# Run 5 tasks in parallel with verbose output
./ralphing.sh --parallel --max-parallel 5 --verbose

How Parallel Mode Works:

1. Creates isolated git worktrees for each agent
2. Each agent works independently on a separate task
3. Agents run concurrently without conflicts
4. Completed branches are merged back to base branch
5. Handles merge conflicts with interactive resolution

Git Branch Management

# Create a branch for each task
./ralphing.sh --branch-per-task

# Specify base branch
./ralphing.sh --branch-per-task --base-branch main

# Create PRs automatically
./ralphing.sh --branch-per-task --create-pr

# Create draft PRs
./ralphing.sh --branch-per-task --create-pr --draft-pr

Branch Naming:

• Sequential: ralphing/task-name-slugified
• Parallel: ralphing/agent-N-task-name-slugified

PRD Source Options

Markdown PRD (Default)

./ralphing.sh --prd PRD.md

YAML Task File

./ralphing.sh --yaml tasks.yaml

GitHub Issues

# Fetch tasks from GitHub issues
./ralphing.sh --github owner/repo

# Filter by label
./ralphing.sh --github owner/repo --github-label enhancement

---

PRD Formats

Markdown Format (PRD.md)

# Product Requirements Document

## Phase 1: Core Features

- [ ] Implement user authentication
- [ ] Create database schema for users
- [ ] Build REST API endpoints
- [ ] Add input validation

## Phase 2: Frontend

- [ ] Create login page
- [ ] Build dashboard component
- [ ] Add user profile editing

## Phase 3: Testing

- [ ] Write unit tests for API
- [ ] Add integration tests
- [ ] Set up CI/CD pipeline

Format:

• Use - [ ] for incomplete tasks
• Tasks are automatically marked - [x] when complete
• Supports any heading structure

YAML Format (tasks.yaml)

tasks:
  - title: "Set up project structure"
    completed: false
    parallel_group: 1

  - title: "Create database models"
    completed: false
    parallel_group: 1

  - title: "Build API endpoints"
    completed: false
    parallel_group: 2

  - title: "Add authentication middleware"
    completed: false
    parallel_group: 2

  - title: "Write tests"
    completed: false
    parallel_group: 3

Features:

• title: Task description
• completed: Boolean status
• parallel_group: Optional grouping (tasks with same group run in parallel)

GitHub Issues Format

# All open issues
./ralphing.sh --github myorg/myrepo

# Only issues labeled "ralphy"
./ralphing.sh --github myorg/myrepo --github-label ralphy

Features:

• Fetches open issues from repository
• Closes issues when tasks complete
• Includes issue body as task context

---

Configuration

Environment Variables

# API Keys
export ANTHROPIC_API_KEY="sk-ant-..."     # For Claude Code
export OPENAI_API_KEY="sk-..."            # For OpenCode/Codex
export CURSOR_API_KEY="..."               # For Cursor

# Git Configuration (optional)
export GIT_AUTHOR_NAME="Ralphing Bot"
export GIT_AUTHOR_EMAIL="ralphing@example.com"

File Structure

your-project/
├── PRD.md              # Task list (markdown)
├── progress.txt        # Task progress log
├── ralphing.sh           # The script
├── .git/               # Git repository
└── your-code/          # Your project files

---

Examples

Example 1: Basic Sequential Run

./ralphing.sh --verbose

Output:

[INFO] Found 5 tasks to process
[INFO] Base branch: main

>>> Task 1
    Completed: 0 | Remaining: 5
--------------------------------------------
  ⏺ ⠋ Implementing      │ Add user authentication [00:15]

  === Agent Status Update (0m 30s) ===
  Recent activity:
    Tool: Write
    File: auth.js
    Tool: Edit
    File: server.js
  Current step: Implementing

  ✓ Done               │ Add user authentication

✓ All tasks complete!

Example 2: Parallel Execution

./ralphing.sh --parallel --max-parallel 3 --verbose

Output:

[INFO] Running 3 parallel agents (each in isolated worktree)...
[INFO] Found 6 tasks to process
[INFO] Base branch: main

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Batch 1: Spawning 3 parallel agents
Each agent runs in its own git worktree with isolated workspace
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ◉ Agent 1: Add user authentication
  ◉ Agent 2: Create database schema
  ◉ Agent 3: Build API endpoints

  ⠋ [⏺ ⏺ ⏺ ] 0 setup | 3 running | 0 done | 0 failed | 01:23

  === Parallel Agent Status Update (1m 30s) ===
  Agent 1: ⏺ Running │ Add user authentication
  Agent 2: ⏺ Running │ Create database schema
  Agent 3: ⏺ Running │ Build API endpoints

Batch 1 Results:
  ✓ Agent 1: Add user authentication → ralphing/agent-1-add-user-authentication
  ✓ Agent 2: Create database schema → ralphing/agent-2-create-database-schema
  ✓ Agent 3: Build API endpoints → ralphing/agent-3-build-api-endpoints

Example 3: Branch-per-Task with PRs

./ralphing.sh --branch-per-task --create-pr --base-branch main

Creates:

• Branch: ralphing/add-user-authentication
• PR: "Add user authentication" → main
• Automatic merge after completion

Example 4: GitHub Issues Integration

./ralphing.sh --github myorg/myrepo --github-label sprint-1 --parallel --max-parallel 2

Fetches:

• All open issues labeled "sprint-1"
• Implements each issue
• Closes issues when complete

Example 5: YAML with Parallel Groups

tasks.yaml:

tasks:
  # Group 1 - Independent setup tasks
  - title: "Initialize project structure"
    parallel_group: 1
  - title: "Set up database connection"
    parallel_group: 1

  # Group 2 - Core features (run after group 1)
  - title: "Implement user service"
    parallel_group: 2
  - title: "Implement auth service"
    parallel_group: 2

  # Group 3 - Tests (run after group 2)
  - title: "Write user service tests"
    parallel_group: 3
  - title: "Write auth service tests"
    parallel_group: 3

./ralphing.sh --yaml tasks.yaml --parallel --max-parallel 2

Execution:

• Runs group 1 tasks (2 in parallel)
• Then group 2 tasks (2 in parallel)
• Finally group 3 tasks (2 in parallel)

---

How It Works

Sequential Mode Flow

1. Read PRD: Parses PRD.md/tasks.yaml/GitHub issues
2. Get Next Task: Finds first incomplete task
3. Create Branch (if --branch-per-task): Creates feature branch
4. Build Prompt: Generates instructions for AI including:
   • Task description
   • Testing requirements (if not skipped)
   • Linting requirements (if not skipped)
   • PRD update instructions
   • Progress logging
5. Run AI Agent: Executes chosen AI engine
6. Monitor Progress: Shows colorful spinner with status updates
7. Mark Complete: Script marks task complete in PRD (reliable!)
8. Create PR (if requested): Pushes branch and creates PR
9. Repeat: Goes to next task until all complete

Parallel Mode Flow

1. Read PRD: Gets all pending tasks
2. Group Tasks (YAML only): Groups tasks by parallel_group
3. Create Worktrees: For each parallel agent, creates isolated git worktree
4. Spawn Agents: Runs N agents concurrently (each in own worktree)
5. Monitor All Agents: Shows per-agent status with colorful indicators
6. Collect Results: Waits for all agents to complete
7. Merge Branches: Merges completed branches back to base
8. Conflict Resolution (if needed): Interactive menu for conflicts
9. Cleanup Worktrees: Removes temporary worktrees
10. Repeat Batch: Processes next batch of tasks

Progress Monitoring

Sequential Mode:

⏺ ⠋ Implementing      │ Add user authentication [00:15]

• ⏺: Colorful blinking indicator (rotates through colors)
• ⠋: Spinner animation
• Implementing: Current step (auto-detected from AI output)
• Add user authentication: Task name (truncated)
• [00:15]: Elapsed time

Parallel Mode:

⠋ [⏺ ⏺ ✓ ] 0 setup | 2 running | 1 done | 0 failed | 01:23

• [⏺ ⏺ ✓]: Per-agent indicators
  • ○ = Setting up (colored by agent)
  • ⏺ = Running (colored by agent)
  • ✓ = Done (green)
  • ✗ = Failed (red)
  • · = Waiting (dim)

30-Second Status Updates: Every 30 seconds, detailed status is printed:

=== Agent Status Update (0m 30s) ===
Recent activity:
  Tool: Write
  File: auth.js
  Tool: Edit
  File: server.js
Current step: Implementing

Task Completion Tracking

Reliable Completion (New in 3.1.0):

1. AI completes task and attempts to mark PRD
2. Script ALWAYS marks task complete (doesn't rely on AI)
3. Script verifies PRD was updated correctly
4. If verification fails, uses fallback prefix matching
5. Result: Tasks are never left incomplete

---

Advanced Features

Automatic Step Detection

Ralphing detects what the AI is doing by analyzing its output:

Detected Action	Step Label	Color
Reading files, searching	Reading code	Cyan
Writing/editing files	Implementing	Magenta
Writing test files	Writing tests	Magenta
Running tests	Testing	Yellow
Running linters	Linting	Yellow
Git staging	Staging	Green
Git committing	Committing	Green
Updating PRD	Updating PRD	Blue
Logging progress	Logging	Blue

Token Tracking

Ralphing tracks token usage across all AI engines:

=== Session Summary ===
Tasks completed: 5
Total input tokens: 45,230
Total output tokens: 12,890
Estimated cost: $0.87
Total time: 12m 34s

Cost Calculation:

• Claude (Sonnet): $3/M input, $15/M output
• Actual costs shown for OpenCode (API provides real cost)
• Duration shown for Cursor (instead of tokens)

Retry Logic

Automatic retry on failures:

• Empty responses: Retries up to --max-retries times
• API errors: Retries with --retry-delay seconds between attempts
• Task failures: Can retry failed tasks manually

Conflict Resolution (Parallel Mode)

When parallel branches have conflicts, interactive menu appears:

┌─────────────────────────────────────────────────────────────┐
│  🔀 Merge conflicts detected in 2 branch(es)                │
├─────────────────────────────────────────────────────────────┤
│    • ralphing/agent-1-feature-a                               │
│    • ralphing/agent-2-feature-b                               │
├─────────────────────────────────────────────────────────────┤
│  What would you like to do?                                 │
│                                                             │
│  [1] 🤖 Retry AI resolution for all (safest)                │
│  [2] 🔧 Resolve manually one-by-one (full control)          │
│  [3] 🗑️  Delete all conflicting branches (destructive)      │
│  [4] ↩️  Abort & reset to clean state (preserves branches)  │
│  [5] 📋 Skip - keep branches for later (default)            │
│                                                             │
└─────────────────────────────────────────────────────────────┘
Enter choice [1-5]:

Options:

1. AI Resolution: Ralphing runs AI agent to resolve conflicts automatically
2. Manual Resolution: Opens files in your editor for manual conflict resolution
3. Delete Branches: Removes conflicting branches (destructive)
4. Abort & Reset: Returns to clean state, preserves branches for later
5. Skip: Keeps branches for manual resolution outside Ralphing

---

Troubleshooting

Common Issues

1. "zclaude not found"

# Install Claude Code
npm install -g @anthropic/claude-code

# Verify installation
which zclaude

2. "jq not found"

# macOS
brew install jq

# Linux
sudo apt install jq

3. "No tasks found in PRD"

• Ensure PRD.md exists in current directory
• Check task format: - [ ] Task description
• Verify there are incomplete tasks

4. Tasks not being marked complete

• This should be fixed in v3.1.0 (script marks tasks)
• Check PRD.md format matches - [ ] Task description
• Try with --verbose to see debug output

5. API rate limits

# Slow down execution
./ralphing.sh --max-iterations 3 --retry-delay 10

6. Agent appears stuck

• Wait for 30-second status update to see activity
• Check if AI is waiting for user input (shouldn't happen in autonomous mode)
• Press Ctrl+C to stop and check progress.txt

7. Parallel mode conflicts

• Use conflict resolution menu (option 1 for AI resolution)
• Reduce --max-parallel to avoid conflicts
• Use sequential mode if conflicts persist

Debug Mode

# Run with maximum verbosity
./ralphing.sh --verbose 2>&1 | tee ralphy-debug.log

# Check what AI is doing
tail -f /tmp/ralphy-*.tmp

# Check git status
git status
git log --oneline -10

Log Files

Ralphing creates temporary files during execution:

• /tmp/ralphy-*.tmp: AI output (auto-deleted after task)
• progress.txt: Permanent log of all task completions
• PRD.md.bak: Backup before task marking (auto-deleted)

---

Best Practices

PRD Writing

Good Task Descriptions:

- [ ] Add JWT authentication to login endpoint
- [ ] Create User model with email, password, and createdAt fields
- [ ] Implement password hashing using bcrypt
- [ ] Add input validation for email format

Poor Task Descriptions:

- [ ] Do auth stuff
- [ ] Fix the bug
- [ ] Make it better
- [ ] Add tests

Best Practices:

1. Be specific and actionable
2. One clear objective per task
3. Include acceptance criteria when helpful
4. Keep tasks reasonably sized (1-3 files changed)
5. Order dependencies correctly (DB models before API endpoints)

Running Ralphing

For Development:

# Start with sequential mode, verbose
./ralphing.sh --verbose --max-iterations 1

# Once confident, run more iterations
./ralphing.sh --verbose --max-iterations 5

# When stable, remove --max-iterations for full automation
./ralphing.sh --verbose

For Production PRs:

# Branch-per-task with draft PRs for review
./ralphing.sh --branch-per-task --create-pr --draft-pr --verbose

For Fast Prototyping:

# Parallel mode, skip tests/lint
./ralphing.sh --parallel --max-parallel 5 --fast

Git Workflow

Recommended Setup:

# Work on feature branch
git checkout -b feature/ralphy-automation

# Run Ralphing
./ralphing.sh --branch-per-task --base-branch feature/ralphy-automation

# Review changes
git log --oneline

# Merge to main when ready
git checkout main
git merge feature/ralphy-automation

Cost Management

# Limit iterations to control costs
./ralphing.sh --max-iterations 10

# Use parallel mode to batch API calls
./ralphing.sh --parallel --max-parallel 3

# Skip tests/lint for cheaper runs
./ralphing.sh --fast --max-iterations 20

Testing & Quality

# Always run tests in production
./ralphing.sh

# For prototypes, skip tests
./ralphing.sh --no-tests

# For final iteration, ensure quality
./ralphing.sh --max-iterations 1  # Then review before continuing

---

Project Structure

File Organization

your-project/
├── ralphing.sh           # The main script
├── PRD.md              # Task list (markdown format)
├── progress.txt        # Completion log (auto-generated)
├── .git/               # Git repository
├── backend/
│   ├── api/
│   ├── models/
│   └── tests/
└── frontend/
    ├── components/
    ├── pages/
    └── tests/

Sample PRD.md

See the included PRD.md for a complete example.

Sample tasks.yaml

See examples/tasks.yaml for YAML format examples.

---

Contributing

Reporting Issues

1. Run with --verbose and capture output
2. Check progress.txt for task history
3. Include PRD.md contents (sanitized)
4. Report at: GitHub Issues

Feature Requests

Ralphing is actively developed. Requested features:

• Support for more AI engines
• Web UI for monitoring
• Slack/Discord notifications
• Cost optimization strategies
• Custom prompt templates

---

License

MIT License - See LICENSE file

---

Credits

• Author: Arsalan Amin
• Version: 3.1.0
• Last Updated: January 2026
• AI Engines: Claude (Anthropic), OpenCode, Cursor, Codex

---

Quick Reference

Common Commands

# Quick start
./ralphing.sh

# Parallel mode
./ralphing.sh --parallel --max-parallel 3

# With branches and PRs
./ralphing.sh --branch-per-task --create-pr

# Fast prototyping
./ralphing.sh --fast --parallel --max-parallel 5

# GitHub issues
./ralphing.sh --github owner/repo --github-label sprint-1

# Dry run (test configuration)
./ralphing.sh --dry-run --verbose

Status Indicators

Symbol	Meaning	Color
⏺	Agent running	Rotating colors
○	Agent setting up	Agent-specific
✓	Task complete	Green
✗	Task failed	Red
·	Agent waiting	Dim
⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏	Spinner	Cyan

Exit Codes

Code	Meaning
0	All tasks completed successfully
1	Error occurred (check logs)
2	All tasks already complete
130	User interrupted (Ctrl+C)

---

For more examples, see the examples/ folder.