ralph-sandbox

Ralph Sandbox

Autonomous coding loops with Docker AI Sandboxes. A custom sandbox template with pre-installed plugin for plan-driven development.

What It Does

• Plan-driven workflow: Define tasks in prd.json, Claude executes them one at a time
• Promise tags: FEATURE_COMPLETE, ALL_COMPLETE, BLOCKED signal iteration status
• Two modes: Supervised (/ralph-once) or autonomous (/ralph-loop)
• Pre-installed tooling: Code review, TDD, build-fix, verification loops, continuous learning

Quick Start

# 1. Build the sandbox template
cd ralph-sandbox
docker build -t ralph-sandbox -f docker/Dockerfile .

# 2. Enter sandbox in your project
docker sandbox run --template ralph-sandbox /path/to/project claude

# 3. Initialize ralph scripts (one time per project)
/ralph-init

# 4. Exit and run interactively from terminal
./ralph/ralph-once.sh

Architecture

┌─────────────────────────────────────────────────────────┐
│              Docker Sandbox (ralph-sandbox)             │
│                                                         │
│  ~/.claude/commands/  ← Plugin commands auto-installed  │
│  ~/.claude/skills/    ← Plugin skills auto-installed    │
│  ~/.claude/agents/    ← Plugin agents auto-installed    │
│  ~/.claude/rules/     ← Plugin rules auto-installed     │
│                                                         │
│  ┌────────────────────────────────────────────────────┐ │
│  │         Claude (with full plugin tooling)          │ │
│  │                                                    │ │
│  │  /ralph-once  → single task, user approves commit  │ │
│  │  /ralph-loop  → autonomous until complete/blocked  │ │
│  └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Commands

Command	Description
/ralph-init	Install ralph scripts to project for terminal use
/ralph-once	Run single task (supervised, approves commits)
/ralph-loop	Run autonomous loop until complete or blocked
/health-check	Verify project has required plan structure
/tdd	Test-driven development workflow
/code-review	Run code review on changes
/build-fix	Fix build/lint/type errors
/verify	Run verification loop
/learn	Capture learnings to learnings.md
/refactor-clean	Refactor and clean code

Project Scripts (after /ralph-init)

./ralph/ralph-once.sh           # Run single iteration (launches sandbox)
./ralph/ralph-once.sh my-plan   # Specify plan name
./ralph/sandbox.sh              # Enter sandbox interactively

Plan Structure

your-project/
├── plans/
│   └── <plan-name>/
│       ├── CLAUDE.md      # Project guidance (required)
│       ├── prd.json       # Task definitions (required)
│       ├── learnings.md    # Decisions & context (optional)
│       ├── PLAN.md        # Implementation overview (optional)
│       ├── DESIGN.md      # Visual specs (optional)
│       └── API.md         # API docs (optional)
└── ralph/                 # Created by /ralph-init
    ├── ralph-once.sh
    └── sandbox.sh

prd.json Format

{
  "planName": "my-feature",
  "description": "What this plan accomplishes",
  "tasks": [
    {
      "id": "task-001",
      "category": "feature",
      "description": "What to build",
      "status": "pending",
      "context": "Problem/solution context",
      "filesToModify": ["src/file.ts"],
      "implementation": {
        "approach": "How to implement",
        "considerations": ["Edge cases", "Dependencies"]
      },
      "steps": ["Step 1", "Step 2"],
      "passes": false
    }
  ]
}

Promise Tags

Claude outputs these to signal iteration status:

<promise>FEATURE_COMPLETE</promise>  <!-- Task done, continue loop -->
<promise>ALL_COMPLETE</promise>       <!-- All tasks done, stop -->
<promise>BLOCKED</promise>            <!-- Need human help, stop -->

Execution Modes

Mode	How	Permissions	Use Case
Interactive	./ralph/ralph-once.sh	acceptEdits	Terminal, supervised
Command	/ralph-once	acceptEdits	In sandbox, supervised
Autonomous	/ralph-loop	dangerously-skip	In sandbox, unattended

Plugin Contents

Agents (9)

• code-reviewer, security-reviewer, tdd-guide, planner, architect
• build-error-resolver, refactor-cleaner, doc-updater, e2e-runner

Skills (7)

• new-plan, plan-prd, tdd-workflow, coding-standards
• security-review, verification-loop, continuous-learning-v2

Commands (10)

• /ralph-init, /ralph-once, /ralph-loop, /health-check
• /tdd, /code-review, /build-fix, /verify, /learn, /refactor-clean

Rules (7)

• agents, coding-style, commit-conventions, hooks
• patterns, performance, security

File Structure