> ralphy.sh
🎯 Quick Start
Option 1: VS Code Extension
code --install-extension ralphy-sh-1.5.24.vsix
# Press Ctrl+Alt+R to start Ralph Loop
# Install skills from terminal (via agentic-skills)
npx agentic-skills install vercel-react-best-practices
npx agentic-skills list
Option 3: Bash Script (Standalone)
chmod +x ralphy.sh
./ralphy.sh --json tasks.json
📋 Table of Contents
- What It Does
- Installation
- Task Formats
- Usage Guide
- Configuration
- Features
- Commands Reference
- Integration
- Troubleshooting
What It Does
🤖 Ralph Loop (Autonomous Agents)
- Load PRD → Extract tasks → Execute autonomously → Track progress
- Context-aware with smart resets
- Full transparency in
.agent/ folder
- Markdown (.md): Simple checklist format
- YAML (.yaml): Structured with parallel groups
- JSON (.json): LLM-optimized, fully featured
- GitHub Issues: Live project management
🔄 PRD to Tasks Converter
- Convert PRD.md to structured task formats
- Quick format selection dialog (3 options)
- Outputs: tasks.md, tasks.json, or tasks.yaml
- Auto-opens converted file for review
🔄 Parallel Execution
- Run multiple AI agents simultaneously
- Each in isolated git worktree
- Auto-merge or create PRs
🛡️ Auto-Accept Automation
- Automatically click "Accept", "Run", "Apply" buttons
- Multi-tab processing (Background Mode)
- Dangerous command blocklist
🧭 AGENTS.md Guidelines
- Unified instructions for AI agents (Copilot, Cursor, etc.)
- standardized root/fallback priority logic
- Robust template for project-specific conventions
🆕 What's New in v1.5.24
✨ AGENTS.md Sample Generator
- New "Generate AGENTS.md" button in the dashboard.
- Automatically scans your tech stack (React, Next.js, Tailwind, etc.) to create tailored AI instructions.
- Generates
-AGENTS-sample.md at the project root with one click.
🆕 What's New in v1.5.23
🧭 Robust AGENTS.md Guideline
- Unified instructions for AI agents (GitHub Copilot, Cursor, Claude, etc.)
- Standardized root/fallback logic (checks root, then
.ralphy/AGENTS.md).
- Integrated into the Ralph Loop context for improved precision.
🆕 What's New in v1.5.0
🛡️ Never-Touch Boundaries
- Define sensitive files or folders that Ralph should NEVER modify in
.agent/config.json.
- Pattern matching for
node_modules, .env, and critical configuration files.
💰 Real-Time Cost Estimation
- Track AI costs per million tokens for active models (e.g., GPT-4o, Claude 3.5 Sonnet).
- Live session and lifetime cost reporting on the Dashboard.
💾 Session Persistence & Resume
- Never lose progress! Agent state is saved to
.agent/session.json.
- Resume long-running tasks across VS Code restarts.
🪝 Lifecycle Hooks
- Custom shell scripts can run at key points:
pre-task, post-task, pre-iteration, post-iteration.
- Found in
.agent/hooks/ for custom CI/CD or notification workflows.
📈 Story Quality Scoring
- PRD Reviewer now scores for "Story Quality" to ensure requirements are autonomous-ready.
- Evaluates technical clarity and non-ambiguity.
🆕 What's New in v1.4.2
🎭 Persona System
- 6 Built-in Personas: Coder, Architect, Debugger, Reviewer, Writer, Analyst
- Custom Personas: Create your own with skill selection
- Context Filtering: Personas filter context for their expertise
📦 Skill Marketplace (NEW!)
- Browse & Install: Download skills from GitHub or marketplace
- 3-Tier System: Core, Official, Community skills
- Security Validation: Automatic checks for dangerous patterns
- Update Checker: Get notified when skills have updates
🔧 Three-Mode System
- Manual: Full control, prompt-by-prompt
- Assisted: AI suggestions with approval checkpoints
- Autonomous: Full auto-execution within guardrails
📊 Enhanced Analytics
- Session metrics: actions, success rate, time saved
- Persona usage tracking
- Visual analytics dashboard
🧠 Memory & Context
- Persistent memory storage
- Semantic search for relevant context
- Token budgeting per persona
⚙️ Settings & Onboarding
- New user onboarding wizard
- Settings migration from old format
- Consolidated
ralphy.* configuration
Installation
VS Code Extension
From VSIX
code --install-extension ralphy-sh-1.5.24.vsix
From Marketplace (Coming Soon)
Search: "ralphy.sh" or "auto accept"
Bash Script (Standalone)
Dependencies Required
- One of:
claude, opencode, codex, or agent (Cursor)
jq for JSON parsingyq for YAML parsing (if using YAML format)gh for GitHub integration (if using GitHub Issues or PRs)git for branch management
Installation
# Download or clone ralphy.sh
chmod +x ralphy.sh
# Verify installation
./ralphy.sh --help
# Test AI CLI
claude --version # or opencode, codex, agent
📄 Markdown (PRD.md)
Best for: Simple projects, quick setup
# Feature: User Authentication
## Requirements
- [ ] Create user model
- [ ] Implement login form
- [ ] Add OAuth integration
- [ ] Create registration endpoint
## Notes
- Use TypeScript
- JWT tokens for auth
How to Use:
# Bash script
./ralphy.sh --prd PRD.md
# VS Code extension
Command Palette → Agent Ralph → Load PRD Document
📝 YAML (tasks.yaml)
Best for: Structured projects, parallel execution
version: "1.0"
projectName: "User Authentication"
description: "Implement user authentication system"
tasks:
- title: "Create user model"
description: "Define User entity with relationships"
priority: CRITICAL
completed: false
phase: "Backend"
parallel_group: 1
files:
- "src/models/User.ts"
- "src/database.ts"
- title: "Create post model"
description: "Define Post entity with user relationship"
priority: HIGH
completed: false
phase: "Backend"
parallel_group: 1
files:
- "src/models/Post.ts"
- title: "Add user authentication"
description: "Implement login and registration endpoints"
priority: CRITICAL
completed: false
phase: "Backend"
parallel_group: 2
dependencies:
- "Create user model"
- "Create post model"
files:
- "src/api/auth.ts"
- "src/middleware/auth.ts"
How to Use:
# Bash script
./ralphy.sh --yaml tasks.yaml
# VS Code extension
Command Palette → Agent Ralph → Load YAML Tasks
🔧 JSON (tasks.json)
Best for: LLM generation, complex projects, full control
{
"version": "1.0",
"projectName": "User Authentication",
"description": "Implement user authentication system",
"tasks": [
{
"id": "TASK-001",
"title": "Create user model",
"description": "Define User entity with relationships",
"priority": "CRITICAL",
"status": "pending",
"phase": "Backend",
"parallelGroup": 1,
"dependencies": [],
"filesToModify": [
"src/models/User.ts",
"src/database.ts"
],
"estimatedComplexity": "medium"
},
{
"id": "TASK-002",
"title": "Create post model",
"description": "Define Post entity with user relationship",
"priority": "HIGH",
"status": "pending",
"phase": "Backend",
"parallelGroup": 1,
"dependencies": [],
"filesToModify": [
"src/models/Post.ts"
],
"estimatedComplexity": "low"
},
{
"id": "TASK-003",
"title": "Add user authentication",
"description": "Implement login and registration endpoints",
"priority": "CRITICAL",
"status": "pending",
"phase": "Backend",
"parallelGroup": 2,
"dependencies": [
"TASK-001",
"TASK-002"
],
"filesToModify": [
"src/api/auth.ts",
"src/middleware/auth.ts"
],
"estimatedComplexity": "medium"
}
]
}
How to Use:
# Bash script
./ralphy.sh --json tasks.json
# VS Code extension
Command Palette → Agent Ralph → Load JSON Tasks
🐙 GitHub Issues
Best for: Team collaboration, issue tracking
# Usage
./ralphy.sh --github owner/repo --github-label "ready"
# Uses open issues from repository
# Auto-closes issues on completion
How to Use:
# Bash script
./ralphy.sh --github myorg/myrepo --github-label "ready"
# VS Code extension
Command Palette → Agent Ralph → Load GitHub Issues
| Feature |
Markdown |
YAML |
JSON |
GitHub |
| Simplicity |
⭐⭐⭐⭐⭐ |
⭐⭐⭐ |
⭐⭐ |
⭐⭐⭐⭐ |
| Structure |
⭐⭐ |
⭐⭐⭐⭐ |
⭐⭐⭐⭐⭐ |
⭐⭐⭐ |
| LLM-Friendly |
⭐⭐⭐ |
⭐⭐⭐⭐ |
⭐⭐⭐⭐⭐ |
⭐⭐⭐ |
| Dependencies |
❌ |
✅ |
✅ |
❌ |
| Parallel Groups |
❌ |
✅ |
✅ |
❌ |
| Auto-Sync |
❌ |
❌ |
❌ |
✅ |
Usage Guide
VS Code Extension Workflow
1. Load Tasks
Command Palette (Ctrl+Shift+P)
→ Agent Ralph → Load PRD (Markdown)
→ Agent Ralph → Load JSON Tasks
→ Agent Ralph → Load YAML Tasks
→ Agent Ralph → Load GitHub Issues
// settings.json
{
"agentAutomation.ralph.parallelMode": false,
"agentAutomation.ralph.branchPerTask": false,
"agentAutomation.ralph.autoCreatePR": false
}
3. Start Loop
Press Ctrl+Alt+R (or Cmd+Alt+R on Mac)
4. Monitor Progress
Open Dashboard: View → Agent Dashboard
View Agent Folder: .agent/TASKS.md
Bash Script Workflow
Basic Usage
# Markdown format (default)
./ralphy.sh --prd PRD.md
# JSON format (recommended for LLMs)
./ralphy.sh --json tasks.json
# YAML format
./ralphy.sh --yaml tasks.yaml
# GitHub Issues
./ralphy.sh --github owner/repo
Parallel Execution
# 3 agents (default)
./ralphy.sh --json tasks.json --parallel
# Custom agent count
./ralphy.sh --json tasks.json --parallel --max-parallel 5
# With parallel groups (from YAML/JSON)
./ralphy.sh --yaml tasks.yaml --parallel
Branch Workflow
# Branch per task
./ralphy.sh --json tasks.json --branch-per-task
# Create PRs automatically
./ralphy.sh --json tasks.json --branch-per-task --create-pr
# Draft PRs
./ralphy.sh --json tasks.json --branch-per-task --create-pr --draft-pr
# Set base branch
./ralphy.sh --json tasks.json --branch-per-task --base-branch develop
AI Engine Selection
# Claude Code (default)
./ralphy.sh --json tasks.json
# OpenCode
./ralphy.sh --json tasks.json --opencode
# Cursor
./ralphy.sh --json tasks.json --cursor
# Codex
./ralphy.sh --json tasks.json --codex
Workflow Options
# Skip tests
./ralphy.sh --json tasks.json --no-tests
# Skip linting
./ralphy.sh --json tasks.json --no-lint
# Skip both (fast mode)
./ralphy.sh --json tasks.json --fast
# Max iterations
./ralphy.sh --json tasks.json --max-iterations 10
# Retry settings
./ralphy.sh --json tasks.json --max-retries 5 --retry-delay 10
# Dry run (preview)
./ralphy.sh --json tasks.json --dry-run
# Verbose output
./ralphy.sh --json tasks.json --verbose
Configuration
VS Code Extension Settings
{
// Task Format Selection
"agentAutomation.ralph.taskFormat": "json",
"agentAutomation.ralph.taskFile": "tasks.json",
// Execution Mode
"agentAutomation.ralph.parallelMode": false,
"agentAutomation.ralph.maxParallel": 3,
// Git Workflow
"agentAutomation.ralph.branchPerTask": false,
"agentAutomation.ralph.autoCreatePR": false,
"agentAutomation.ralph.baseBranch": "",
"agentAutomation.ralph.draftPR": false,
// Retry Logic
"agentAutomation.ralph.maxRetries": 3,
"agentAutomation.ralph.retryDelay": 5,
"agentAutomation.ralph.maxIterations": 0,
// GitHub Integration
"agentAutomation.ralph.githubRepo": "",
"agentAutomation.ralph.githubLabel": "",
// Cost Tracking
"agentAutomation.ralph.costTracking": true
}
Bash Script Options
Task Source Options:
--prd FILE # PRD markdown file (default: PRD.md)
--yaml FILE # YAML task file
--json FILE # JSON task file (recommended)
--github REPO # GitHub repository (owner/repo)
--github-label TAG # Filter GitHub issues by label
AI Engine Options:
--claude # Use Claude Code CLI (default)
--opencode # Use OpenCode CLI
--cursor/--agent # Use Cursor agent
--codex # Use Codex CLI
Execution Options:
--parallel # Run tasks in parallel
--max-parallel N # Max concurrent agents (default: 3)
--max-iterations N # Stop after N tasks (0 = unlimited)
--max-retries N # Retries per task (default: 3)
--retry-delay N # Seconds between retries (default: 5)
--dry-run # Preview without executing
--no-tests # Skip writing/running tests
--no-lint # Skip linting
--fast # Skip both tests and linting
Git Workflow Options:
--branch-per-task # Create feature branch per task
--base-branch NAME # Base branch (default: current)
--create-pr # Create pull request after each task
--draft-pr # Create PRs as drafts
Other Options:
-v, --verbose # Show debug output
-h, --help # Show help
--version # Show version
Features
Supported Formats:
- ✅ Markdown (.md) - Simple checklist format
- ✅ YAML (.yaml) - Structured with parallel groups
- ✅ JSON (.json) - LLM-optimized, fully featured
- ✅ GitHub Issues - Live sync with project management
Features by Format:
| Feature |
Markdown |
YAML |
JSON |
GitHub |
| Simple syntax |
✅ |
✅ |
✅ |
N/A |
| Structured metadata |
❌ |
✅ |
✅ |
✅ |
| Dependencies |
❌ |
✅ |
✅ |
❌ |
| Parallel groups |
❌ |
✅ |
✅ |
❌ |
| Auto-sync |
❌ |
❌ |
❌ |
✅ |
| LLM-generated |
Possible |
Possible |
✅ Optimal |
N/A |
⚡ Parallel Execution
What It Does:
- Runs multiple AI agents simultaneously
- Each agent works in isolated git worktree
- Tasks with same
parallelGroup run together
- Automatic coordination and cleanup
How It Works:
┌─────────────────────────────────────────────────┐
│ Base Branch: main │
└─────────────────┬─────────────────────────────┘
│
┌─────────┴─────────┬─────────┐
│ │ │
┌───▼───┐ ┌──▼──┐ ┌▼──┐
│Agent 1 │ │Agent 2│ │A3 │
│Worktree│ │Worktree│ │... │
└───┬───┘ └───┬──┘ └──┬─┘
│ │ │
Branch: Branch: Branch:
ralph/agent-1- ralph/ ralph/
task-name agent-2- agent-N-
task-name task-name
Usage:
./ralphy.sh --json tasks.json --parallel --max-parallel 4
🌿 Branch Workflow
Branch Per Task:
./ralphy.sh --json tasks.json --branch-per-task
Auto-Create PR:
./ralphy.sh --json tasks.json --branch-per-task --create-pr
Result:
- Each task creates feature branch:
ralphy/task-name
- Commits are made on task branch
- Option to merge back or create PR for review
- Clean git history with isolated changes
💰 Cost Tracking
Tracks:
- Input tokens per task
- Output tokens per task
- Estimated/actual cost (depending on AI engine)
- Duration for Cursor (no token tracking)
View Report:
# Bash script - shown at completion
# VS Code extension
Command Palette → Agent Ralph → Show Costs
Example Output:
Tasks completed: 5
Input tokens: 45,230
Output tokens: 89,150
Estimated cost: $1.47
🔄 Retry Logic
Configurable:
--max-retries N # Retries per task (default: 3)
--retry-delay N # Seconds between retries (default: 5)
Handles:
- Empty responses
- API errors
- Network failures
- Task execution failures
📊 Progress Monitoring
Real-time Display:
⠙ Implementing │ Create user model [02:15]
Step Detection:
- Thinking - AI is planning
- Reading code - AI is analyzing codebase
- Implementing - AI is writing code
- Writing tests - AI is creating tests
- Testing - Tests are running
- Linting - Linting in progress
- Staging - Git add in progress
- Committing - Git commit in progress
🔔 Notifications
Cross-Platform:
- macOS: Notification Center + sound
- Linux: notify-send + paplay
- Windows: PowerShell system sounds
Events:
- All tasks completed
- Fatal errors
Commands Reference
VS Code Commands
Agent Automation (Auto-Accept):
| Command |
Shortcut |
Description |
| Agent: Start |
Ctrl+Alt+A |
Start automation |
| Agent: Stop |
Ctrl+Alt+S |
Stop automation |
| Agent: Toggle Auto-Accept |
— |
Enable/disable auto-click |
| Agent: Toggle Background Mode |
— |
Enable/disable multi-tab |
| Agent: Configure Banned Commands |
— |
Edit blocklist |
| Agent: Adjust Polling Speed |
— |
Set interval |
| Agent: Toggle Stuck Recovery |
— |
Enable/disable |
| Agent: Show Dashboard |
— |
View analytics |
Agent Ralph (Autonomous Loop):
| Command |
Shortcut |
Description |
| Agent Ralph: Load PRD Document |
— |
Load markdown PRD |
| Agent Ralph: Convert PRD to Tasks |
— |
Convert PRD to tasks.md/json/yaml |
| Agent Ralph: Load JSON Tasks |
— |
Load JSON task file |
| Agent Ralph: Load YAML Tasks |
— |
Load YAML task file |
| Agent Ralph: Load GitHub Issues |
— |
Fetch from GitHub |
| Agent Ralph: Start Ralph Loop |
Ctrl+Alt+R |
Start execution |
| Agent Ralph: Pause Ralph Loop |
— |
Pause execution |
| Agent Ralph: Resume Ralph Loop |
— |
Resume execution |
| Agent Ralph: Stop Ralph Loop |
— |
Stop execution |
| Agent Ralph: Show Ralph Status |
— |
Show current status |
| Agent Ralph: Reset Context Window |
— |
Force context reset |
| Agent Ralph: Toggle Parallel |
— |
Enable/disable parallel |
| Agent Ralph: Show Costs |
— |
View cost report |
Bash Script Commands
# Help & Version
./ralphy.sh --help
./ralphy.sh --version
# Basic Execution
./ralphy.sh --json tasks.json
./ralphy.sh --yaml tasks.yaml
./ralphy.sh --prd PRD.md
./ralphy.sh --github owner/repo
# Advanced Options
./ralphy.sh --json tasks.json --parallel --max-parallel 5
./ralphy.sh --json tasks.json --branch-per-task --create-pr
./ralphy.sh --json tasks.json --opencode --fast
./ralphy.sh --json tasks.json --dry-run --verbose
Integration
Shared State Between Extension & Bash Script
Both use the same state structure:
.agent/ # Agent state folder (shared)
├── STATUS.md # Current mode & active task
├── TASKS.md # Generated task list with checkboxes
├── DECISIONS.md # Architectural decisions
├── GUARDRAILS.md # Patterns & anti-patterns
├── HISTORY.md # Append-only action log
└── cache/ # Temporary data
PRD.md # Markdown tasks (if used)
tasks.yaml # YAML tasks (if used)
tasks.json # JSON tasks (if used) - RECOMMENDED
progress.txt # Progress log
Extension vs Bash Script
| Feature |
Extension |
Bash Script |
| GUI Dashboard |
✅ |
❌ |
| VS Code Integration |
✅ |
❌ |
| Auto-startup |
✅ |
❌ |
| Multi-AI Engines |
❌ |
✅ |
| Standalone |
❌ |
✅ |
| CI/CD Ready |
❌ |
✅ |
| Cost Tracking |
✅ |
✅ |
| Parallel Execution |
✅ (Planned) |
✅ |
| Branch Workflow |
✅ (Planned) |
✅ |
| Progress Monitoring |
✅ |
✅ |
Recommendation: Use both! They share state and complement each other:
- Use extension for GUI and VS Code integration
- Use bash script for CI/CD pipelines and multi-AI workflows
Troubleshooting
Common Issues
Issue: "AI CLI not found"
Solution:
# Check which AI CLIs are installed
which claude opencode codex agent
# Install missing CLI
# Claude Code: https://github.com/anthropics/claude-code
# OpenCode: https://opencode.ai/docs/
# Cursor: https://cursor.com
Issue: "jq not found"
Solution:
# macOS
brew install jq
# Ubuntu/Debian
sudo apt-get install jq
# Windows (via Chocolatey)
choco install jq
Issue: "yq not found"
Solution:
# macOS
brew install yq
# Ubuntu/Debian
sudo snap install yq
# Or use JSON format instead (no yq needed)
./ralphy.sh --json tasks.json
Issue: "tasks.json not found"
Solution:
# Create sample tasks.json
cat > tasks.json << 'EOF'
{
"version": "1.0",
"tasks": [
{
"title": "My first task",
"priority": "HIGH",
"status": "pending"
}
]
}
EOF
Issue: "Git worktree error"
Solution:
# Check git version
git --version # Must be 2.5.0 or higher
# Enable worktree
git config core.repositoryFormatVersion 1
Issue: "Agent gets stuck"
Solution:
# Increase retry delay
./ralphy.sh --json tasks.json --retry-delay 10
# Enable stuck recovery in extension
# settings.json: "agentAutomation.stuckRecovery": true
Issue: "High token costs"
Solution:
# Use YAML or JSON format (more structured)
# Enables AI to understand context better
./ralphy.sh --json tasks.json
# Add more detail to task descriptions
# Reduces need for multiple clarifications
Issue: "Parallel agents conflict"
Solution:
# Use parallel groups in YAML/JSON
tasks:
- title: "Task 1"
parallel_group: 1
- title: "Task 2"
parallel_group: 1 # Runs with Task 1
- title: "Task 3"
parallel_group: 2 # Runs after Group 1 completes
FAQ
Q: Which task format should I use?
A:
- Markdown: Quick start, simple projects, no dependencies needed
- YAML: Structured projects, parallel execution, moderate complexity
- JSON: Complex projects, LLM generation, full control with dependencies
- GitHub: Team collaboration, issue tracking, auto-sync
Recommendation: Use JSON for new projects (LLM-friendly).
Q: Can I use both extension and bash script?
A: Yes! They share state in .agent/ folder. You can:
- Load tasks in extension
- Run bash script for CI/CD
- Both track progress in same files
Q: How does parallel mode work?
A: Each agent runs in isolated git worktree:
- Prevents file conflicts
- Independent branches:
ralphy/agent-1-task-name, etc.
- Tasks with same
parallelGroup run together
- Lower-numbered groups complete first
Q: What's the difference between YAML and JSON?
A:
- YAML: More human-readable, simpler syntax
- JSON: Better for LLMs, supports dependencies, structured
- Both support: parallel groups, phases, metadata
- Choose based on your workflow
Q: Can I mix formats in one project?
A: No, choose one format per session. However:
- You can have multiple files (PRD.md, tasks.json, tasks.yaml)
- Use different format for different projects
- Extension and bash script support all formats
Q: How do dependencies work in JSON?
A: In tasks.json:
{
"id": "TASK-002",
"dependencies": ["TASK-001"]
}
AI will automatically:
- Task 001 completes first
- Task 002 waits for Task 001
- Ensures correct execution order
Q: What happens if a task fails?
A:
- Bash script: Retries up to
--max-retries times
- Extension: Pauses with error notification
- Check
.agent/HISTORY.md for details
- Fix issue and resume
Q: How do I create PRs?
A:
# Bash script
./ralphy.sh --json tasks.json --branch-per-task --create-pr
# Requires: GitHub CLI (gh)
# Optional: --draft-pr for draft PRs
Q: Can I use custom AI models?
A:
- Extension: Settings → agentAutomation.ai.modelId
- Bash Script: Set via AI CLI (varies by tool)
Q: Is this safe?
A: Yes! Safety features:
- Built-in dangerous command blocklist
- Only clicks visible, enabled buttons
- Context resets prevent token overflow
- Full transparency in
.agent/ folder
- Dry-run mode available
Q: Does it work offline?
A:
- Extension: Needs VS Code LM API or API keys
- Bash Script: Depends on AI CLI (may need internet)
License
MIT - Free to use, modify, and distribute forever.
Built with ❤️ for developers who value their time.
✅ Auto-Accept Verification
- Verified on: 2026-01-23
- Status: Working (Last tested: 2026-01-23)
