{"id":37229310,"url":"https://github.com/daydemir/ralph","last_synced_at":"2026-01-17T23:25:52.262Z","repository":{"id":331730169,"uuid":"1131915947","full_name":"daydemir/ralph","owner":"daydemir","description":"Autonomous PRD execution loop for Claude Code","archived":false,"fork":false,"pushed_at":"2026-01-11T07:10:02.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T08:16:31.330Z","etag":null,"topics":["ai-coding","autonomous-agent","claude","claude-code","prd"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daydemir.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-11T00:06:32.000Z","updated_at":"2026-01-11T07:10:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daydemir/ralph","commit_stats":null,"previous_names":["daydemir/ralph"],"tags_count":14,"template":true,"template_full_name":null,"purl":"pkg:github/daydemir/ralph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daydemir%2Fralph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daydemir%2Fralph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daydemir%2Fralph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daydemir%2Fralph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daydemir","download_url":"https://codeload.github.com/daydemir/ralph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daydemir%2Fralph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","autonomous-agent","claude","claude-code","prd"],"created_at":"2026-01-15T03:32:08.947Z","updated_at":"2026-01-15T03:32:09.523Z","avatar_url":"https://github.com/daydemir.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ralph GSD\n\n\u003e [!WARNING]\n\u003e **Claude Code Required** — This tool requires an active Claude Code subscription.\n\u003e\n\u003e **Cost Warning** — Running plans consumes Claude API usage. Autonomous loops can use significant quota.\n\u003e\n\u003e **Auto-Accept Mode** — Ralph runs Claude with `--dangerously-skip-permissions` enabled. It will make changes without confirmation prompts.\n\u003e\n\u003e **Recommendation** — Start with `ralph run` (single plan) to observe behavior before using `ralph run --loop`.\n\n\u003e Built on [Get Shit Done (GSD)](https://github.com/glittercowboy/get-shit-done) planning and inspired by the [original Ralph concept](https://ghuntley.com/ralph/) by Geoffrey Huntley.\n\nRalph executes your development plans automatically. You define what to build, Ralph breaks it into phases, creates detailed task plans, and executes them with verification. Each run preserves learnings in a `## Progress` section within the PLAN.md file for the next run.\n\n## Table of Contents\n- [How It Works](#how-it-works)\n- [When to Use Ralph](#when-to-use-ralph)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Commands](#commands)\n- [Configuration](#configuration)\n- [Troubleshooting](#troubleshooting)\n\n**Planning is mandatory** - Ralph enforces that you properly understand and plan work before executing.\n\n## How It Works\n\nRalph uses a **phase-by-phase workflow**. You don't plan everything upfront - you work through one phase at a time:\n\n```\n┌───────────────────────────────────────────────────────────┐\n│  ONE-TIME SETUP                                           │\n│                                                           │\n│  ralph init  →  ralph map  →  ralph roadmap               │\n│                                                           │\n└───────────────────────────────────────────────────────────┘\n                          │\n                          ▼\n┌───────────────────────────────────────────────────────────┐\n│  PER-PHASE LOOP (repeat for each phase)                   │\n│                                                           │\n│  ┌──────────┐     ┌──────────┐    ┌─────────┐    ┌─────┐  │\n│  │ discover │  →  │ discuss  │ →  │  plan   │ →  │ run │  │\n│  │(optional)│     │(optional)│    │         │    │     │  │\n│  └──────────┘     └──────────┘    └─────────┘    └─────┘  │\n│                                                           │\n│  Phase 1 → Phase 2 → Phase 3 → ... → Done                 │\n│                                                           │\n└───────────────────────────────────────────────────────────┘\n\n         At any time: ralph status (see where you are)\n```\n\n## When to Use Ralph\n\n**Good for:**\n- Greenfield projects building from scratch\n- Major refactors with clear phases\n- Feature development with sequential steps\n- Any work that can be broken into verifiable tasks\n\n**Not for:**\n- Quick one-off changes (use Claude directly)\n- Exploratory work where scope is unclear\n- Work requiring constant human judgment\n- Debugging sessions or investigations\n\n## Ralph vs GSD\n\n| Component | Role |\n|-----------|------|\n| **GSD** | Planning brain - interactive workflows for project setup, roadmapping, and plan creation |\n| **Ralph** | Execution engine - autonomous execution with verification, looping, and progress tracking |\n\nRalph wraps GSD commands in a simpler CLI (`ralph plan` calls `/gsd:plan-phase`, etc.) and adds:\n- Verification after each task\n- Autonomous looping across plans\n- Progress tracking via `ralph status`\n- Inactivity timeout protection\n\nYou can use GSD directly within Claude Code for interactive planning, or use Ralph for automated execution.\n\n## Checking Progress: `ralph status`\n\nRun `ralph status` anytime to see your current position:\n\n```bash\n$ ralph status\n\nRalph v2.0.0 - My Project\n\n📦 Project Artifacts:\n  ✓ PROJECT.md          Project vision and requirements\n  ✓ ROADMAP.md          10 phases defined\n  ✓ Codebase Maps       7 analysis documents\n  ✓ STATE.md            Tracking execution\n  ✓ Plans               3/10 phases have plans\n\nProgress: [████░░░░░░░░░░░░░░░░] 20% (4/20 plans)\n\n📍 Current Position:\n  Phase: 2 of 10\n  Plan:  01-02-PLAN.md\n  Status: Ready to execute\n\n🎯 Suggested Next Actions:\n  ralph run              Execute next incomplete plan\n  ralph run --loop 5     Execute up to 5 plans autonomously\n```\n\nUse `ralph status -v` (verbose) to see all phases and their plans:\n\n```bash\n$ ralph status -v\n...\nPhases:\n  ✓ Phase 1: Feature Verification (3/3)\n      ✓ 01-01-PLAN.md\n      ✓ 01-02-PLAN.md\n      ✓ 01-03-PLAN.md\n  ◐ Phase 2: Mix World Media (1/2)\n      ✓ 02-01-PLAN.md\n      ○ 02-02-PLAN.md\n  ○ Phase 3: Story Adaptation (0/0)\n  ...\n```\n\nUse `ralph list` for a compact view of all phases and plans.\n\n## Installation\n\n### Prerequisites\n\n1. **Claude Code CLI** - [Install Claude Code](https://claude.ai/code)\n2. **GSD (Get Shit Done)** - Required for planning:\n   ```bash\n   npm install -g get-shit-done-cc\n   ```\n\n### Install Ralph\n\n**Homebrew (recommended):**\n```bash\nbrew tap daydemir/tap\nbrew install ralph\n```\n\n**From source:**\n```bash\ngo install github.com/daydemir/ralph/cmd/ralph@latest\n```\n\n## Quick Start\n\n```bash\n# One-time setup\nralph init              # Create PROJECT.md\nralph map               # Analyze existing codebase (brownfield projects)\nralph roadmap           # Create ROADMAP.md with phases\n\n# Per-phase cycle\nralph discover 1        # Research external APIs/docs (optional)\nralph discuss 1         # Align on scope and approach (optional)\nralph plan 1            # Create executable PLAN.md files\nralph run               # Execute plans (or: ralph run --loop 5)\n```\n\n## Workflow Example\n\nHere's a complete cycle for one phase:\n\n```bash\n# Phase 1: Authentication\nralph discover 1        # → Creates .planning/phases/01-auth/RESEARCH.md\n                        #   Researches OAuth providers, JWT libraries, etc.\n\nralph discuss 1         # → Creates .planning/phases/01-auth/CONTEXT.md\n                        #   Alignment conversation about scope, edge cases\n\nralph plan 1            # → Creates .planning/phases/01-auth/01-01-PLAN.md, etc.\n                        #   Breaks phase into executable task files\n\nralph run --loop        # Executes all plans for phase 1\n                        # STATE.md updates automatically\n\n# Phase 1 complete → now repeat for Phase 2\nralph discover 2\nralph discuss 2\nralph plan 2\nralph run --loop\n```\n\n## Pre-Planning: Discover vs Discuss\n\nBefore planning a phase, you can optionally run **discover** and/or **discuss** to build context:\n\n| Command | Purpose | Output | When to Use |\n|---------|---------|--------|-------------|\n| `ralph discover N` | Research external docs, APIs, ecosystem options | `RESEARCH.md` | Unfamiliar domain, new libraries, API integrations |\n| `ralph discuss N` | Alignment conversation about scope/approach | `CONTEXT.md` | Complex decisions, unclear requirements, multiple approaches |\n\n**Guidelines:**\n- **Familiar domain?** Skip discover, maybe run discuss for alignment\n- **New technology?** Run discover to research options first\n- **Complex phase?** Run both - discover first, then discuss with that context\n- **Simple phase?** Skip both and go straight to `ralph plan`\n\nBoth commands are optional but recommended for non-trivial phases. The context they generate helps `ralph plan` create better plans.\n\n## Interactive Session Workflow\n\nCommands `ralph discover`, `ralph discuss`, and `ralph plan` open **interactive Claude sessions**. Here's how to use them:\n\n1. **Run the command** - A Claude conversation starts\n2. **Discuss with Claude** - Work through the topic until Claude indicates completion\n3. **Look for the completion signal** - Claude will say something like:\n   - \"I've updated CONTEXT.md with our discussion\"\n   - \"I've created the PLAN.md files\"\n   - \"RESEARCH.md has been saved\"\n4. **Exit the session** - Type `/exit` or press `Ctrl+C`\n5. **Check progress** - Run `ralph status` to see your updated state\n\n**Tip:** These sessions are conversational. Ask follow-up questions, request changes, or explore alternatives before Claude finalizes the output. Once Claude confirms the file has been written, your work is saved and you can safely exit.\n\n## Commands\n\n### Setup Commands (One-Time)\n\n| Command | Description |\n|---------|-------------|\n| `ralph init` | Initialize project with GSD (creates PROJECT.md) |\n| `ralph roadmap` | Create phase breakdown (creates ROADMAP.md) |\n| `ralph map` | Analyze existing codebase structure |\n\n### Pre-Planning Commands (Optional)\n\n| Command | Description |\n|---------|-------------|\n| `ralph discover [N]` | Research phase N - external docs, APIs, options → RESEARCH.md |\n| `ralph discuss [N]` | Discuss phase N - scope and approach alignment → CONTEXT.md |\n\n### Planning Commands\n\n| Command | Description |\n|---------|-------------|\n| `ralph plan [N]` | Create executable PLAN.md files for phase N |\n\n### Execution Commands\n\n| Command | Description |\n|---------|-------------|\n| `ralph run` | Execute the next incomplete plan |\n| `ralph run --loop [N]` | Autonomous loop up to N plans (default 10) |\n| `ralph run --model MODEL` | Use specific model (sonnet, opus, haiku) |\n| `ralph status` | Dashboard: current phase, progress, suggested actions |\n\nModel options:\n- **sonnet** (default): Best balance of speed and capability\n- **opus**: More capable but slower, for complex phases\n- **haiku**: Fastest, for simple repetitive tasks\n| `ralph status -v` | Verbose: show all phases and plans with completion status |\n| `ralph list` | Compact list of all phases and plans |\n\n### Roadmap Modification\n\n| Command | Description |\n|---------|-------------|\n| `ralph add-phase \"desc\"` | Add phase to end of roadmap |\n| `ralph insert-phase N \"desc\"` | Insert urgent work as phase N.1 |\n| `ralph remove-phase N` | Remove phase N and renumber |\n\n**Planning is mandatory** - Ralph enforces that you properly understand and plan work before executing.\n\n## Workspace Structure\n\nRalph creates two directories:\n\n```\n.ralph/\n└── config.yaml         # Ralph configuration (optional)\n\n.planning/              # Created by GSD\n├── PROJECT.md          # Project vision and requirements\n├── ROADMAP.md          # Phase breakdown\n├── STATE.md            # Current position and progress\n├── codebase/           # Codebase analysis (from ralph map)\n│   ├── STACK.md\n│   ├── ARCHITECTURE.md\n│   └── ...\n└── phases/\n    ├── 01-foundation/\n    │   ├── RESEARCH.md       # From ralph discover (optional)\n    │   ├── CONTEXT.md        # From ralph discuss (optional)\n    │   ├── 01-01-PLAN.md\n    │   ├── 01-01-SUMMARY.md\n    │   └── 01-02-PLAN.md\n    └── 02-authentication/\n        └── ...\n```\n\n## Execution with Verification\n\nEach PLAN.md contains tasks with verification commands:\n\n```xml\n\u003ctask type=\"auto\"\u003e\n  \u003cname\u003eCreate user model\u003c/name\u003e\n  \u003caction\u003eCreate User struct with fields\u003c/action\u003e\n  \u003cverify\u003e\n    \u003ccommand\u003ego build ./...\u003c/command\u003e\n    \u003cexpect\u003eexit 0\u003c/expect\u003e\n  \u003c/verify\u003e\n\u003c/task\u003e\n```\n\nRalph runs verification after each task. If verification fails, execution stops immediately and reports what failed.\n\n### Inactivity Timeout\n\nRalph monitors for 60 minutes of **inactivity** (no output), not total duration. Long builds and tests are fine as long as there's activity.\n\n### Context Management\n\nClaude's context degrades after ~100K tokens. Ralph uses a hybrid approach:\n\n1. **Progress tracking**: Claude updates a `## Progress` section in each PLAN.md after completing tasks\n2. **Self-monitoring**: Claude is instructed to bail out gracefully at ~100K tokens\n3. **Safety net**: Ralph terminates at 120K tokens if Claude hasn't bailed out\n\nWhen context runs low, Ralph preserves learnings in the PLAN.md file so the next run can continue where it left off.\n\n## Autonomous Loop\n\n`ralph run --loop` executes multiple plans with:\n- Fresh Claude context per plan (200k tokens)\n- Automatic verification between plans\n- Immediate stop on failure\n- Progress tracking in STATE.md\n\n```bash\n$ ralph run --loop 5\n=== Ralph Autonomous Loop ===\n\nIteration 1/5: 01-01-PLAN.md\n[12:34:56] Executing: Foundation setup\n[12:35:12] ✓ Task 1/3 complete\n[12:36:01] ✓ Task 2/3 complete\n[12:37:15] ✓ Task 3/3 complete\n✓ Complete (2m 19s)\n\nIteration 2/5: 01-02-PLAN.md\n...\n```\n\n### Retry Behavior\n\nWhen a plan exits unexpectedly (soft failure), Ralph will automatically retry:\n- **Default retries:** Same as `--loop` count (e.g., `--loop 20` = 20 retries per plan)\n- **Override:** Use `--max-retries N` to set a specific limit\n\n```bash\nralph run --loop 20                    # 20 iterations, 20 retries per plan\nralph run --loop 20 --max-retries 3    # 20 iterations, max 3 retries per plan\n```\n\nOn retry, Ralph:\n1. Analyzes what happened (checks Progress section, SUMMARY.md existence)\n2. Provides context about previous attempts to Claude\n3. Instructs Claude to log progress before each action (to capture state if interrupted again)\n\n### Manual Checkpoints\n\nPlans can contain manual tasks (`type=\"manual\"`) that require human action (e.g., adding files in Xcode, clicking through UI flows). Ralph handles these automatically:\n\n1. **At phase start:** Ralph scans all plans and bundles manual tasks into `XX-99-manual-PLAN.md`\n2. **During execution:** Claude skips manual tasks and records them as observations\n3. **At phase end:** The manual plan runs last, presenting all human tasks in one place\n\nThis keeps automation flowing while collecting human work for batch completion.\n\n**Example manual task bundling:**\n```\nPhase 2 has plans: 02-01, 02-02, 02-03 (with 2 manual tasks), 02-04\n\nRalph creates:\n- 02-00-decisions-PLAN.md (runs first, if decisions exist)\n- 02-99-manual-PLAN.md (runs last, contains the 2 manual tasks)\n\nExecution order: 02-00 → 02-01 → 02-02 → 02-03 → 02-04 → 02-99\n```\n\n## Post-Plan Analysis\n\nAfter each plan completes, Ralph runs an **analysis agent** that reviews discoveries and can adjust subsequent plans.\n\n### What It Does\n\nThe analysis agent:\n- Reads `## Discoveries` section from the completed PLAN.md\n- Reviews all remaining plans in the current and future phases\n- Updates plans based on findings (adds context, blockers, notes)\n- Runs even on failures to help diagnose issues\n\n### Discovery Types\n\nDuring execution, Claude records discoveries in XML format:\n\n| Type | Description |\n|------|-------------|\n| `bug` | Existing bug found in codebase |\n| `stub` | Tests or code that are placeholders |\n| `api-issue` | External API behaving unexpectedly |\n| `insight` | Useful pattern or approach discovered |\n| `blocker` | Something preventing progress |\n| `technical-debt` | Code quality issue found |\n| `tooling-friction` | Build/test quirks learned through trial-and-error |\n| `assumption` | Decision made without full information |\n| `scope-creep` | Work discovered that wasn't in the plan |\n| `dependency` | Unexpected dependency between tasks |\n| `questionable` | Suspicious code or pattern worth reviewing |\n\n### When Analysis Runs\n\nThe analysis agent runs:\n- After successful plan completion\n- After soft failures (context exhaustion, bailout with progress)\n- After hard failures (task/verification failure) - to diagnose issues\n\n### Skipping Analysis\n\nUse `--skip-analysis` to disable post-plan analysis:\n\n```bash\nralph run --skip-analysis\nralph run --loop 5 --skip-analysis\n```\n\n## Configuration\n\nEdit `.ralph/config.yaml`:\n\n```yaml\nllm:\n  backend: claude      # LLM backend to use\n  model: sonnet        # Model: sonnet, opus, or haiku\n\nclaude:\n  binary: claude       # Path to Claude CLI binary\n  allowed_tools:       # Tools Claude can use during execution\n    - Read\n    - Write\n    - Edit\n    - Bash\n    - Glob\n    - Grep\n    - Task\n    - TodoWrite\n    - WebFetch\n    - WebSearch\n\nbuild:\n  default_loop_iterations: 10    # Default max iterations for --loop\n  signals:\n    iteration_complete: \"###ITERATION_COMPLETE###\"\n    ralph_complete: \"###RALPH_COMPLETE###\"\n```\n\nRalph uses sensible defaults if no config file exists.\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| \"GSD not installed\" error | Run `npm install -g get-shit-done-cc` to install GSD |\n| \"No ROADMAP.md found\" | Run `ralph init` then `ralph roadmap` first |\n| Plan execution fails | Run `ralph status -v` to see current state, check the PLAN.md file for issues, fix manually then retry |\n| \"Context exceeded\" errors | Plan may be too large - break the phase into smaller sub-phases |\n| Claude hangs or times out | Check network connection; Ralph has 60-minute inactivity timeout (not total time) |\n| Wrong phase executing | Check STATE.md in `.planning/` - manually edit if needed to reset position |\n| Ralph was interrupted mid-plan | Run `ralph status` to see state, then `ralph run` to resume |\n\n## Previous Version\n\nThe v0.x PRD-based system is archived in `archive/v0-shell/`.\n\n## Development\n\n### Building from Source\n\n```bash\n# Clone and build\ngit clone https://github.com/daydemir/ralph.git\ncd ralph\ngo build -o ralph ./cmd/ralph\n\n# Install to $GOPATH/bin\ngo install ./cmd/ralph\n```\n\n### Releasing a New Version\n\nRalph uses [GoReleaser](https://goreleaser.com/) to build binaries and update the Homebrew formula.\n\n```bash\n# 1. Commit your changes\ngit add .\ngit commit -m \"feat: your feature description\"\n\n# 2. Tag the new version\ngit tag -a v0.X.0 -m \"Release description\"\n\n# 3. Push with tags\ngit push origin main --tags\n\n# 4. Run GoReleaser (requires GitHub token)\nGITHUB_TOKEN=$(gh auth token) goreleaser release --clean\n```\n\n**Note:** The `gh auth token` command uses the GitHub CLI to get your token. You need `gh auth login` first with `repo` scope.\n\nGoReleaser will:\n- Build binaries for darwin/linux (amd64/arm64)\n- Create a GitHub release with changelog\n- Update the Homebrew formula in `daydemir/homebrew-tap`\n\n### Local Development Install\n\n```bash\n# Install with version (for testing before release)\ngo install -ldflags \"-X github.com/daydemir/ralph/internal/cli.Version=dev\" ./cmd/ralph\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaydemir%2Fralph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaydemir%2Fralph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaydemir%2Fralph/lists"}