ralph-wiggum-copilot

v3.1.0

Published

12 days ago

Autonomous AI development loop powered by GitHub Copilot SDK with intelligent exit detection, model selection, and circuit breaker protection

0High
0Medium
0Low

mlbishnoi

copilot github-copilot copilot-sdk ai autonomous development agent ralph-wiggum loop automation agentic model-selection

🤖 Ralph Wiggum Copilot

Autonomous AI Development Loop powered by the GitHub Copilot SDK (@github/copilot-sdk)

Ralph Wiggum Copilot is a production-grade autonomous AI agent that drives GitHub Copilot through iterative development loops. Define your requirements, pick a model, and Ralph works through them autonomously — with intelligent exit detection, circuit breaker protection, session continuity, and auto-commit.

✨ Features

| Feature | Description | |---------|-------------| | 🎯 Natural Language Planning | ralph plan "fix auth bug" — describe intent, get structured plan | | ⚡ Quick Fix Mode | ralph fix "tests failing" — zero-config, capped iterations | | 🚀 Pre-flight Check | ralph doctor — validates environment before first run | | 🎨 Interactive Setup | ralph init — guided .ralphrc wizard with smart defaults | | 🔄 Autonomous Loop | Iterates until all tasks complete or circuit breaker triggers | | 🎯 Model Selection | GPT-4.1, GPT-5, Claude Opus/Sonnet, Gemini, o3, o4-mini, and more | | 🛡️ Circuit Breaker | Three-state (CLOSED→HALF_OPEN→OPEN) with cooldown recovery | | 🧠 Intelligent Exit | Multi-signal detection: status blocks, task completion, heuristics | | 📺 Live Dashboard | Real-time TUI showing task progress, tokens, circuit breaker state | | 🔗 Session Continuity | Resume sessions across loops with automatic expiration | | 📦 Auto-Commit | Git auto-commit on progress with configurable prefixes | | 🛡️ Protected Paths | User-defined off-limits files (migrations, lock files, prod configs) | | 📁 File Integrity | Validates critical Ralph files before each loop iteration | | ⚡ Rate Limiting | Per-hour call limits to prevent API overuse | | 📊 Status Reporting | Structured RALPH_STATUS blocks for machine-readable analysis | | 🔧 Three-Tier Config | CLI flags > env vars > .ralphrc > defaults | | 💻 Cross-Platform | Windows, macOS, and Linux |

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         CLI (cli.ts)                            │
│  ralph --live -m claude-opus-4.6 -n 20                         │
├─────────────────────────────────────────────────────────────────┤
│                    Config Loader (config.ts)                     │
│  CLI flags > ENV vars > .ralphrc > defaults                     │
├─────────────┬───────────────────────────────────┬───────────────┤
│  Session    │        Loop Engine                │   Circuit     │
│  Manager    │   ┌─────────────────────────┐     │   Breaker     │
│             │   │ for each iteration:     │     │               │
│  create     │   │   1. Build prompt       │     │  CLOSED       │
│  resume     │   │   2. Send to Copilot SDK│     │  HALF_OPEN    │
│  expire     │   │   3. Stream response    │     │  OPEN         │
│  reset      │   │   4. Analyze response   │     │               │
│             │   │   5. Check exit signals │     │  no-progress  │
│             │   │   6. Record circuit CB  │     │  same-error   │
│             │   │   7. Auto-commit        │     │  test-only    │
│             │   └─────────────────────────┘     │               │
├─────────────┴───────────────────────────────────┴───────────────┤
│                  @github/copilot-sdk                            │
│  CopilotClient → createSession → sendAndWait / streaming       │
└─────────────────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

Node.js 18+ — Download
GitHub Copilot Subscription — Required for SDK access

Install

# Clone and install
git clone https://github.com/mangilal_microsoft/ralph-wiggum-copilot.git
cd ralph-wiggum-copilot
npm install
npm run build
npm link

# Or use the install script
./install.sh        # Linux/macOS
.\install.ps1       # Windows

Use in Projects

Fastest Path: Quick Fix (Zero Config)

cd my-existing-project
ralph fix "the tests in auth.test.ts are failing because of the mock setup"
# → Auto-creates .ralph/, runs max 10 iterations, auto-exits on fix

Standard Path: Plan → Execute

cd my-existing-project
ralph plan "fix the auth bug, add rate limiting, and bump Node to 22"
# → Generates structured fix_plan.md from your intent
# → Interactive review: approve, edit, or refine with feedback
# → On approve: starts automation loop automatically

Full Setup: Init → Plan → Execute

cd my-existing-project
ralph init              # Interactive .ralphrc wizard
ralph doctor            # Pre-flight validation
ralph plan "build a REST API for user management"
ralph --live            # Or: automation runs after plan approval

New Project

ralph-setup my-project --type node-ts
cd my-project
ralph plan "implement the user authentication module"

📖 Usage

Commands

# ── Getting Started (new features!) ────────────────
ralph plan "fix the auth bug"         # Generate plan from natural language
ralph plan "add retry" --scope src/api/ # Scoped context for large repos
ralph fix "tests failing in auth.ts"   # Zero-config quick fix mode
ralph doctor                           # Pre-flight environment check
ralph init                             # Interactive .ralphrc wizard

# ── Core loop ────────────────────────────────
ralph                                   # Run with defaults
ralph --live                            # Live streaming output
ralph --live -m claude-opus-4.6         # Live + specific model
ralph -m gpt-5 -n 10                   # GPT-5, max 10 iterations
ralph --once                            # Single iteration only

# ── Model selection ──────────────────────────
ralph --models                          # List all available models

# ── Status & recovery ────────────────────────
ralph --status                          # Show project status
ralph-status                            # Detailed status view
ralph --reset-circuit                   # Reset circuit breaker
ralph --reset-session                   # Reset session state

# ── Project setup ────────────────────────────
ralph-setup my-api --type node-ts       # Create new project
ralph-enable                            # Enable in existing project

`ralph plan` — Intent to Plan

Converts natural language into a structured fix_plan.md using Copilot SDK:

# Simple
ralph plan "fix the login endpoint that returns 500 when user doesn't exist"

# Multi-task
ralph plan "fix auth bug, add retry logic to API client, bump Node to 22"

# Scoped for large codebases (only injects context from specified dirs)
ralph plan "refactor the payment module" --scope src/payments/ src/billing/

# Preview without saving
ralph plan --dry-run "add rate limiting"

# Auto-approve for CI/scripts
ralph plan -y "implement caching layer"

# Save plan but don't start loop
ralph plan --no-run "add WebSocket support"

The interactive review lets you:

A — Approve and save the plan
E — Edit in your $EDITOR
Q — Quit without saving
Or type feedback — Refine conversationally ("also add a circuit breaker")

`ralph fix` — Quick Fix Mode

Zero-config mode for simple, single-task problems:

ralph fix "the tests in auth.test.ts are failing because of the mock setup"
ralph fix "fix the lint error in src/api.ts line 42"
ralph fix "the build is broken because of a missing import" --live

Auto-creates .ralph/ structure if needed
Generates focused 1-item plan + PROMPT.md optimized for the fix
Caps at 10 iterations (configurable with -n)
Auto-exits when fix is complete

`ralph doctor` — Pre-flight Check

ralph doctor

  🩺 Ralph Doctor — Pre-flight Check
  ═══════════════════════════════════

  Git
  ─────
  ✓ Git repository detected
  ℹ Branch: main

  Project
  ─────────
  ✓ Project type: node-ts ("my-project")
  ✓ Test directory found
  ℹ Project file count: ~142

  Shell Environment
  ──────────────────
  ✓ bash: /usr/bin/bash
  ⚠ pwsh.exe not installed — Ralph will use bash instead

  Ralph Files
  ─────────────
  ✓ .ralph/ directory
  ✓ PROMPT.md
  ✗ fix_plan.md not found → Run `ralph plan` to create one

  Circuit Breaker
  ────────────────
  ✓ Circuit breaker: CLOSED

  ──────── Summary ────────
  ✓ 8 passed   ⚠ 1 warning   ✗ 1 issue

`ralph init` — Configuration Wizard

ralph init

  🤖 Ralph Wiggum Copilot — Setup Wizard
  ═══════════════════════════════════════

  Detected project: my-api (node-ts)

  Select AI model:
    → 1. gpt-4.1 — Latest GPT-4 variant (128k ctx)
      2. claude-sonnet-4 — Anthropic Claude Sonnet 4 (200k ctx)
      3. claude-opus-4.6 — Strongest model (1M ctx)
      4. gpt-5 — Next generation reasoning (256k ctx)
      5. gemini-2.5-pro — Google Gemini 2.5 Pro (1M ctx)
  Max iterations per run? [50]:
  Timeout per iteration (minutes)? [30]:
  Enable streaming responses? [Y/n]:
  Auto-commit changes on progress? [Y/n]:
  Define protected paths? [y/N]:
  ✓ Configuration saved to .ralphrc

All CLI Options

| Option | Description | Default | |--------|-------------|---------| | -m, --model <model> | AI model ID | gpt-4.1 | | -n, --max-iterations <n> | Max loop iterations | 50 | | -t, --timeout <min> | Timeout per iteration | 30 | | --calls <n> | Max calls per hour | 200 | | --live | Live streaming output | off | | --once | Single iteration only | — | | --no-streaming | Disable streaming | — | | --no-commit | Disable auto-commit | — | | --no-session | Disable session continuity | — | | -v, --verbose | Verbose logging | off | | -p, --project <path> | Project directory | cwd | | --task-file <file> | Task file name | RALPH_TASK.md |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | RALPH_MODEL | AI model override | gpt-4.1 | | RALPH_MAX_ITERATIONS | Max iterations | 50 | | RALPH_TIMEOUT_MINUTES | Timeout per iteration | 30 | | RALPH_VERBOSE | Verbose mode | false | | RALPH_LIVE_OUTPUT | Live output mode | false | | RALPH_STREAMING | Enable streaming | true | | RALPH_AUTO_COMMIT | Auto-commit | true |

🎨 Available Models

| Model ID | Provider | Context | Description | |----------|----------|---------|-------------| | gpt-4.1 ★ | OpenAI | 128k | Latest GPT-4 variant — fast and capable | | gpt-4o | OpenAI | 128k | Optimized GPT-4 for multi-modal | | gpt-5 | OpenAI | 256k | GPT-5 — next generation reasoning | | gpt-5.1-codex | OpenAI | 256k | GPT-5.1 Codex — optimized for code | | o3 | OpenAI | 200k | o3 reasoning model | | o4-mini | OpenAI | 200k | o4-mini — fast reasoning | | claude-sonnet-4 | Anthropic | 200k | Claude Sonnet 4 | | claude-sonnet-4.5 | Anthropic | 200k | Claude Sonnet 4.5 | | claude-opus-4.6 | Anthropic | 1M | Claude Opus 4.6 — strongest model | | gemini-2.5-pro | Google | 1M | Gemini 2.5 Pro | | gemini-3-pro-preview | Google | 2M | Gemini 3 Pro Preview |

★ = Recommended default. Unknown model IDs are passed through to the SDK.

📁 Project Structure

your-project/
├── .ralph/                    # Ralph configuration
│   ├── PROMPT.md             # AI instructions (system prompt)
│   ├── fix_plan.md           # Task checklist (priority-ordered)
│   ├── AGENT.md              # Build/test commands
│   ├── specs/                # Detailed requirements & specs
│   │   └── requirements.md
│   ├── logs/                 # Execution logs
│   │   └── ralph.log
│   ├── status.json           # Machine-readable status
│   ├── .session.json         # Session state
│   └── .circuit_breaker.json # Circuit breaker state
├── .ralphrc                   # Per-project configuration
├── RALPH_TASK.md             # Current task (optional)
└── src/                      # Your source code

Workflow

PROMPT.md (high-level goals & format instructions)
    ↓
specs/ (detailed requirements when needed)
    ↓
fix_plan.md (priority-ordered checklist Ralph executes)
    ↓
AGENT.md (build/test commands — auto-maintained)

⚙️ Configuration (.ralphrc)

Create a .ralphrc file in your project root:

# Model
MODEL=gpt-4.1

# Loop
MAX_ITERATIONS=50
TIMEOUT_MINUTES=30
MAX_CALLS_PER_HOUR=200

# Streaming
STREAMING=true
LIVE_OUTPUT=false
VERBOSE=false

# Session
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24

# Git
AUTO_COMMIT=true
COMMIT_PREFIX=[ralph]

# Circuit Breaker
CB_NO_PROGRESS_THRESHOLD=3
CB_SAME_ERROR_THRESHOLD=5
CB_TEST_ONLY_THRESHOLD=3
CB_PERMISSION_DENIAL_THRESHOLD=2
CB_COOLDOWN_MINUTES=30

# Token Management
WARN_TOKEN_THRESHOLD=70000
ROTATE_TOKEN_THRESHOLD=80000

# Protected Paths (comma-separated globs — AI will never modify these)
# PROTECTED_PATHS=src/database/migrations/**,*.lock,docker-compose.prod.yml

Configuration priority: CLI flags > Environment variables > .ralphrc > Defaults

🧠 Intelligent Exit Detection

Ralph uses multi-signal exit detection to decide when to stop:

| Signal | Priority | Description | |--------|----------|-------------| | Permission Denied | Highest | Halts immediately on permission denials | | Test Saturation | High | 3+ consecutive test-only loops | | Completion Signals | High | 2+ explicit EXIT_SIGNAL=true | | Safety Breaker | High | 5+ EXIT_SIGNAL=true in a row | | Plan Complete | Medium | All fix_plan.md items marked [x] + EXIT_SIGNAL | | High Confidence | Medium | EXIT_SIGNAL + confidence ≥ 80% |

RALPH_STATUS Block Format

The agent is instructed to include this at the end of every response:

---RALPH_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
TASKS_COMPLETED_THIS_LOOP: 2
FILES_MODIFIED: 5
TESTS_STATUS: PASSING | FAILING | NOT_RUN
WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
EXIT_SIGNAL: false | true
RECOMMENDATION: Continue with API integration
COMMIT CURRENT CHANGE: Implement user authentication module
---END_RALPH_STATUS---

🛡️ Circuit Breaker

Three-state protection against agent thrashing:

CLOSED ──→ HALF_OPEN ──→ OPEN (on threshold breach)
  ↑                         │
  ├─ progress detected ─────┘ (recovery in HALF_OPEN)
  └─────────────────────────┘ (cooldown timer: OPEN → HALF_OPEN → CLOSED)

| Condition | Default Threshold | Behavior | |-----------|-------------------|----------| | No Progress | 3 iterations | CLOSED → HALF_OPEN → OPEN | | Same Error | 5 repetitions | Opens circuit | | Test-Only | 3 iterations | Opens circuit | | Permission Denied | 2 consecutive | Opens circuit immediately | | Cooldown Recovery | 30 minutes | OPEN → HALF_OPEN automatically |

📊 Sample Execution

ralph --live -m claude-opus-4.6

╔══════════════════════════════════════════════════════════╗
║          Ralph Wiggum Copilot                            ║
║          GitHub Copilot SDK — Model: claude-opus-4.6     ║
╚══════════════════════════════════════════════════════════╝

[INFO] Max iterations: 50
[INFO] Timeout: 30m per iteration
[INFO] Streaming: true
[INFO] Session: ralph-1739145463-x8k2m
────────────────────────────────────────────────────────────
[LOOP] === Loop #1/50 ===
━━━━━━━━━━━━━━━━ Copilot Output ━━━━━━━━━━━━━━━━

I'll start by reading fix_plan.md to understand the current priorities.

⚡ [Read]

The fix_plan shows 3 high priority items. Let me implement the first one...

⚡ [Edit]

⚡ [Write]

⚡ [Bash]

All tests pass. Marking task complete and continuing.

⚡ [Edit]

---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 3
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Continue with next high-priority task
COMMIT CURRENT CHANGE: Implement user authentication module
---END_RALPH_STATUS---

━━━━━━━━━━━━━━━━ End of Output ━━━━━━━━━━━━━━━━━
[SUCCESS] ✅ Loop #1 completed
╔══════════════════════════════════════════════════════════╗
║           Response Analysis — Loop #1                    ║
╚══════════════════════════════════════════════════════════╝
  Exit Signal:      false
  Confidence:       50%
  Status:           IN_PROGRESS
  Work Type:        IMPLEMENTATION
  Files Changed:    3
  Tasks Completed:  1
  Tests:            PASSING
  Recommendation:   Continue with next high-priority task
[INFO] 📦 Auto-committed 3 file(s): [ralph] Loop #1: Implement user auth
[LOOP] === Loop #2/50 ===
...

🔌 Programmatic API

import { runLoop, loadConfig, onEvent, AVAILABLE_MODELS } from 'ralph-wiggum-copilot';

// List models
console.log(AVAILABLE_MODELS);

// Subscribe to events
onEvent((event) => {
  if (event.type === 'stream:delta') process.stdout.write(event.content);
  if (event.type === 'exit:detected') console.log('Exit:', event.reason);
});

// Run the loop
const config = loadConfig(process.cwd(), { model: 'claude-opus-4.6', liveOutput: true });
const result = await runLoop(config);

console.log(result);
// { exitReason: 'complete', iterations: 5, totalTokens: 45000, tasksCompleted: 8 }

🧱 Module Structure

| Module | Purpose | |--------|---------| | cli.ts | CLI entry point + subcommand routing (plan/fix/doctor/init) | | config.ts | Three-tier configuration loader + protected paths | | loop-engine.ts | Core autonomous loop using Copilot SDK | | prompt-builder.ts | Prompt construction with type guards + protected files | | response-analyzer.ts | RALPH_STATUS parsing + exit detection + confidence | | exit-detector.ts | Multi-signal exit decision engine | | circuit-breaker.ts | Three-state circuit breaker with HALF_OPEN + cooldown | | session-manager.ts | Session lifecycle + transition history | | file-protection.ts | File integrity validation each loop | | repo-context.ts | Repo context builder for plan generation | | live-dashboard.ts | Real-time TUI dashboard with task progress | | task-parser.ts | Markdown checkbox parser | | git.ts | Git change detection + auto-commit | | project-detector.ts | Project type auto-detection | | status.ts | Status reporting + persistence | | logger.ts | Structured colored logging | | event-logger.ts | JSONL event logging | | shell-detector.ts | Shell/tool availability detection | | pwsh-shim.ts | PowerShell 7 shim for Windows | | types.ts | Canonical type definitions | | Commands | | | commands/plan.ts | ralph plan — intent → structured plan | | commands/fix.ts | ralph fix — zero-config quick fix | | commands/doctor.ts | ralph doctor — pre-flight validation | | commands/init.ts | ralph init — interactive .ralphrc wizard | | commands/enable.ts | ralph-enable — enable in existing project | | commands/setup.ts | ralph-setup — scaffold new project |

📄 License

MIT