ralph-claude-code: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository Overview

Ralph for Claude Code — an autonomous AI development loop system enabling continuous development cycles with intelligent exit detection and rate limiting. See README.md for version info, changelog, and user documentation.

Core Architecture

Main Scripts

• ralph_loop.sh — main autonomous loop that executes Claude Code repeatedly
• ralph_monitor.sh — live monitoring dashboard for tracking loop status
• setup.sh — project initialization for new Ralph projects
• create_files.sh — bootstrap script that creates the entire Ralph system
• ralph_import.sh — converts PRD/spec documents to Ralph format; uses --output-format json with automatic text fallback for older CLI versions
  • GitHub issue import (Issue #69): --github-issue <N> for an exact issue, plus --repo <owner/repo>, --include-comments
  • Fetches via gh into a markdown PRD, then the normal conversion pipeline. Comments off by default (prompt-injection surface); source content is treated as data, not instructions
  • Metadata filtering + selection (Issue #71), implemented in resolve_github_issue_candidates() / select_issue_from_candidates() / preview_issue_matches() (replaced resolve_github_issue_number(); "first match" is now oldest, not gh's newest-first):
    • Combinable primary filters: --github-search <query>, --github-label <labels> (comma = AND), --github-title <pattern> (* wildcard only, rest literal, case-insensitive), --github-assignee <user|@me|none>, --github-milestone <name>, --github-state <open|closed|all>; modifiers (--exclude-label <labels>, --select, --dry-run) require ≥1 primary filter; --github-issue is mutually exclusive with all of them
    • One gh issue list --limit 500 query (server-side where gh supports it; exclude-label and title matching client-side via jq); candidates sorted oldest-first. Cap-hit handling (gh returns newest-first, so a capped set may be missing the true oldest matches): WARN for server-side-only queries; hard ERROR when client-side filters are active (they could pick the wrong issue or report zero matches over a truncated set)
    • --select first|interactive|priority picks among multiple matches: priority understands bare P0–P9 and priority: PN labels (ties → oldest, none → first); interactive falls back to first on non-TTY/EOF. --dry-run previews the match table + would-be selection without importing
  • Completeness assessment + plan generation (Issue #70): issues are scored 0–100 via lib/issue_analyzer.sh; below --completeness-threshold (default 60) an implementation plan is generated via Claude CLI (--plan-model passthrough) and appended to the PRD before conversion, plus saved to .ralph/specs/implementation-plan.md. Flags: --generate-plan (force), --no-generate-plan (fail if below threshold), --plan-model <model>, --completeness-threshold <0-100>, --auto-approve (skip the approval prompt; non-TTY sessions auto-accept)
• ralph_queue.sh — ralph-queue command: batch processing and issue queue management (Issue #72). Builds a persistent queue at .ralph/queue.json of GitHub issues (reuses ralph_import.sh's gh machinery: resolve_github_issue_candidates, fetch_github_issue, format_issue_as_prd) or local PRD specs. Subcommands: add (--github-issues N,N | filter flags | --prd <file>), status [--json], next, remove, clear, reorder, validate, process [--halt-on-failure], resume. The sequential processor stages .ralph/ from each ready item (priority + dependency order), runs the loop via RALPH_LOOP_CMD (default ralph_loop.sh; overridable for tests), commits Fix #N: <title> per issue, skips failures (or halts), and writes .ralph/logs/queue_processing.log. Single branch, no concurrency. See docs/QUEUE_MANAGEMENT.md
• GitHub issue lifecycle (Issue #73): when ralph is run with --github-issue <ref>, it tracks the issue across the loop via lib/github_lifecycle.sh. During development it can post progress comments every N loops (--comment-progress, --comment-interval); on graceful completion it runs a completion workflow — summary comment (--close-summary), PR creation linked with Closes #N (--create-pr --link-issue, optional --draft-pr), grouped follow-up issue from TODO/FIXME markers added during dev (--create-followups --followup-label), and issue close with optional labels (--auto-close --add-label). All steps are opt-in and degrade gracefully (a gh permission failure is logged and the loop continues). State lives in .ralph/.github_lifecycle_state. Uses the gh CLI exclusively (not raw REST/GITHUB_TOKEN)
• ralph_enable.sh — interactive wizard enabling Ralph in existing projects (environment detection, task source selection, generates .ralphrc)
• ralph_enable_ci.sh — non-interactive version for CI/automation; --json output mode; exit codes: 0 (success), 1 (error), 2 (already enabled)