Claude自主开发工作流

- .ralph/specs/requirements.md (technical specs)

Configure your project requirements manually

Importing Existing Requirements

Ralph can convert existing PRDs, specifications, or requirement documents into the proper Ralph format using Claude Code.

Prerequisites

• GitHub CLI (gh) installed: brew install gh or sudo apt install gh (see https://cli.github.com)
• Authenticated: gh auth login
• jq installed (used to parse issue JSON)

Process all ready pending items in priority/dependency order

ralph --process-queue ralph-queue process

System Requirements

• Bash 4.0+ - For script execution
• Claude Code CLI - npm install -g @anthropic-ai/claude-code (or use npx — set CLAUDE_CODE_CMD in .ralphrc)
• tmux - Terminal multiplexer for integrated monitoring (recommended)
• jq - JSON processing for status tracking
• Git - Version control (projects are initialized as git repos)
• GNU coreutils - For the timeout command (execution timeouts)
• Linux: Pre-installed on most distributions
• macOS: Install via brew install coreutils (provides gtimeout)
• Standard Unix tools - grep, date, etc.

Testing Requirements (Development)

See TESTING.md for the comprehensive testing guide.

If you want to run the test suite:

```bash

Install dependencies and run tests

npm install npm test && npm run test:e2e # All 784 tests must pass ```

Phase 1: Install Ralph (One Time Only)

Install Ralph globally on your system:

git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

This adds ralph, ralph-monitor, ralph-setup, ralph-import, ralph-queue, ralph-migrate, ralph-enable, and ralph-enable-ci commands to your PATH.

Note: You only need to do this once per system. After installation, you can delete the cloned repository if desired.

Ongoing Usage (After Setup)

Once Ralph is installed and your project is initialized:

```bash

Uninstalling Ralph

To completely remove Ralph from your system:

```bash

Run the uninstall script

./uninstall.sh

Building a queue

```bash

Docker Sandbox Execution

Run Claude Code inside an isolated Docker container instead of directly on your machine (Issue #74). Ralph's loop, rate limiting, and monitoring stay on the host; only Claude's execution — the part that edits files and runs commands autonomously — is containerized. The project directory is bind-mounted read-write at /workspace, so changes land on the host directly and ralph-monitor works unchanged.

Setup

```bash

...or build it yourself (from a source checkout, or ~/.ralph after install)

docker build -t ralph-sandbox . ```

Setup

pip install e2b                       # official E2B Python SDK (the transport)
export E2B_API_KEY="e2b_..."          # or: store in ~/.ralph/e2b_api_key (chmod 600)

Install BATS testing framework

npm install -g bats bats-support bats-assert

Installing tmux

```bash

Installing GNU coreutils (macOS)

Ralph uses the timeout command for execution timeouts. On macOS, you need to install GNU coreutils:

```bash

Install coreutils (provides gtimeout)

brew install coreutils

Verify installation

gtimeout --version ```

Ralph automatically detects and uses gtimeout on macOS. No additional configuration is required after installation.

Installation Commands (Run Once)

./install.sh              # Install Ralph globally
./uninstall.sh            # Remove Ralph from system (dedicated script)
./install.sh uninstall    # Alternative: Remove Ralph from system
./install.sh --help       # Show installation help
ralph-migrate             # Migrate existing project to .ralph/ structure

Quick Start

Ralph has two phases: one-time installation and per-project setup.

INSTALL ONCE              USE MANY TIMES
+-----------------+          +----------------------+
| ./install.sh    |    ->    | ralph-setup project1 |
|                 |          | ralph-enable         |
| Adds global     |          | ralph-import prd.md  |
| commands        |          | ...                  |
+-----------------+          +----------------------+

Usage Examples

```bash

Usage Examples

```bash

Usage

ralph --sandbox docker                          # Default image, 4g RAM, 2 CPUs, bridge network
ralph --sandbox docker --sandbox-image node:20  # Any image with `claude` on PATH
ralph --sandbox docker --sandbox-memory 8g --sandbox-cpus 4
ralph --sandbox docker --sandbox-network none   # Full network isolation (blocks the Claude API —
                                                # only for images with their own auth/proxy setup)
ralph --monitor --sandbox docker                # Works with tmux monitoring

Equivalent .ralphrc settings: SANDBOX_PROVIDER, SANDBOX_DOCKER_IMAGE, SANDBOX_DOCKER_MEMORY, SANDBOX_DOCKER_CPUS, SANDBOX_DOCKER_NETWORK (CLI flags override).

Usage

```bash ralph --sandbox e2b # base template; claude CLI auto-bootstrapped ralph --sandbox e2b --sandbox-template my-template # custom template with claude preinstalled ralph --sandbox e2b --sandbox-timeout 7200 # 2h session timeout (expired sandboxes auto-recreate) ralph --sandbox e2b --sandbox-max-cost 5.00 --sandbox-cost-alert 2.00 # budget controls ralph --sandbox e2b --sandbox-keep-alive # leave it running; reuse with --sandbox-id <id> ralph --monitor --sandbox e2b # works with tmux monitoring (cost shown in the dashboard)

Check current usage (shows calls and tokens used this hour)

ralph --status

Rate limiting supports two independent limits — both reset hourly:

| Setting | Default | Description |
|---------|---------|-------------|
| `MAX_CALLS_PER_HOUR` | `100` | Max Claude invocations per hour |
| `MAX_TOKENS_PER_HOUR` | `0` (disabled) | Max cumulative tokens per hour |

Token tracking extracts `input_tokens + output_tokens` from each Claude response. A single call can consume 100k+ tokens, so `MAX_TOKENS_PER_HOUR` provides cost control that `MAX_CALLS_PER_HOUR` alone cannot.

The circuit breaker automatically:
- Detects API errors and rate limit issues with advanced two-stage filtering
- Opens circuit after 3 loops with no progress or 5 loops with same errors
- Eliminates false positives from JSON fields containing "error"
- Accurately detects stuck loops with multi-line error matching
- Gradually recovers with half-open monitoring state
- **Auto-recovers** after cooldown period (default: 30 minutes) — OPEN → HALF_OPEN → CLOSED
- Provides detailed error tracking and logging with state history

**Auto-recovery options:**

Quick Start

```bash

Optional

- [ ] Frontend integration # does NOT block exit - [ ] SMS notifications # does NOT block exit ```

Unchecked items under Optional, Future, Future Enhancements, or Nice to Have headings (and their subsections) are ignored by the completion check. Customize the section names with OPTIONAL_SECTIONS in .ralphrc (comma-separated, case-insensitive). This resolves the deadlock where Claude treats low-priority items as skippable while Ralph waits for them.

Configuration

Project Configuration (.ralphrc)

Each Ralph project can have a .ralphrc configuration file:

```bash

.ralphrc - Ralph project configuration

PROJECT_NAME="my-project" PROJECT_TYPE="typescript"

whose PATH or env vars are only set in their shell's init file)

#RALPH_SHELL_INIT_FILE="~/.zshrc"

Loop settings

MAX_CALLS_PER_HOUR=100 CLAUDE_TIMEOUT_MINUTES=15 CLAUDE_OUTPUT_FORMAT="json"

Combine with other options

ralph --monitor --verbose --timeout 30 ```

Ralph Loop Options

ralph [OPTIONS]
  -h, --help              Show help message
  -c, --calls NUM         Set max calls per hour (default: 100)
  -p, --prompt FILE       Set prompt file (default: .ralph/PROMPT.md)
  -s, --status            Show current status and exit
  -m, --monitor           Start with tmux session and live monitor
  -v, --verbose           Show detailed progress updates during execution
  -l, --live              Enable live streaming output (real-time Claude Code visibility)
  -t, --timeout MIN       Set Claude Code execution timeout in minutes (1-120, default: 15)
  --dry-run               Simulate loop execution without making actual Claude API calls
  -n, --notify            Enable desktop notifications for key events
  -b, --backup            Enable automatic git backup branch before each loop (requires git)
  --rollback [BRANCH]     Roll back to a backup branch (lists available branches if none given)
  --show-tool-args        Show tool arguments (commands, file paths) in live streaming output
  --output-format FORMAT  Set output format: json (default) or text
  --allowed-tools TOOLS   Set allowed Claude tools (default: granular git subcommands + npm/pytest)
  --no-continue           Disable session continuity (start fresh each loop)
  --session-expiry HOURS  Set session expiration time in hours (default: 24)
  --reset-circuit         Reset the circuit breaker
  --circuit-status        Show circuit breaker status
  --auto-reset-circuit    Auto-reset circuit breaker on startup (bypasses cooldown)
  --reset-session         Reset session state manually
  --queue-status          Show the issue queue and exit
  --process-queue         Process pending queued issues sequentially (--halt-on-failure to stop on first failure)
  --resume-queue          Resume processing the remaining pending issues
  --queue-next            Print the id of the next ready queued issue
  --queue-clear           Remove all items from the queue
  --queue-remove <id|N>   Remove one item from the queue

Full reference: every flag is documented in depth, with examples and .ralphrc patterns, in docs/CLI_OPTIONS.md.

Convert a JSON API spec

ralph-import api-spec.json backend-service

Claude Code CLI command (auto-detected, override if needed)

CLAUDE_CODE_CMD="claude"

Claude API 5-Hour Limit

When Claude's 5-hour usage limit is reached, Ralph: 1. Detects the limit using three-layer verification (timeout guard → structural JSON → filtered text fallback) 2. Prompts you to choose: - Option 1: Wait 60 minutes for the limit to reset (with countdown timer) - Option 2: Exit gracefully 3. Unattended mode: Auto-waits on prompt timeout (30s) instead of exiting 4. Prevents false positives from echoed file content mentioning "5-hour limit"

Command Reference

Run unit + integration tests (771 tests)

npm test

CLAUDE_CODE_CMD="npx @anthropic-ai/claude-code" # Alternative: use npx

Troubleshooting

• "GitHub CLI (gh) is not installed" — install it from https://cli.github.com
• "GitHub CLI is not authenticated" — run gh auth login