Ralph Driven Development using OpenCode SDK and OpenTUI
npm install @hona/ralph-cliAI agent loop for autonomous task execution. Reads a plan, picks one task, completes it, commits, repeats.
``bashInstall stable release
bun install -g @hona/ralph-cli
$3
`bash
git clone https://github.com/hona/opencode-ralph.git
cd opencode-ralph
bun install
bun run build:single # compiles for current platform
`What is Ralph?
Ralph-driven development forces an AI agent to re-read full context every iteration, eliminating context drift. Each loop:
1. Read
plan.md
2. Pick ONE task
3. Complete it
4. Commit (updating the plan in the same commit)
5. Repeat until doneThe agent never pushes—only commits—so you maintain review control.
Why it works:
- Deterministic failures are debuggable. When Ralph fails, fix the prompt.
-
AGENTS.md accumulates wisdom so future iterations don't rediscover fire.
- Human review checkpoint before anything goes live.See: ghuntley.com/ralph · lukeparker.dev/stop-chatting-with-ai-start-loops-ralph-driven-development
Usage
`bash
ralph # uses plan.md in current directory
ralph --plan BACKLOG.md # different plan file
ralph --model anthropic/claude-opus-4 # different model
ralph --reset # start fresh, ignore previous state
`| Option | Default | Description |
|--------|---------|-------------|
|
--plan, -p | plan.md | Plan file path |
| --model, -m | opencode/claude-opus-4-5 | Model (provider/model format) |
| --prompt | see below | Custom prompt ({plan} placeholder) |
| --reset, -r | false | Reset state |Default prompt:
`
READ all of {plan}. Pick ONE task. If needed, verify via web/code search (this applies to packages, knowledge, deterministic data - NEVER VERIFY EDIT TOOLS WORKED OR THAT YOU COMMITED SOMETHING. BE PRAGMATIC ABOUT EVERYTHING). Complete task. Commit change (update the plan.md in the same commit). ONLY do one task unless GLARINGLY OBVIOUS steps should run together. Update {plan}. If you learn a critical operational detail, update AGENTS.md. When ALL tasks complete, create .ralph-done and exit. NEVER GIT PUSH. ONLY COMMIT.
`Keybindings
| Key | Action |
|-----|--------|
|
p | Pause/resume |
| q / Ctrl+C | Quit |Files
| File | Purpose |
|------|---------|
|
.ralph-state.json | Persisted state for resume after Ctrl+C |
| .ralph-lock | Prevents multiple instances |
| .ralph-done | Agent creates this when all tasks complete |
| .ralph-pause | Created by p key to pause loop |Add to
.gitignore:
`
.ralph-*
`Architecture
`
src/
├── index.ts # CLI entry, wires TUI to loop
├── loop.ts # Main agent loop (prompt → events → commit)
├── app.tsx # Solid.js TUI root component
├── state.ts # State types and persistence
├── plan.ts # Plan file parser (checkbox counting)
├── git.ts # Git operations (hash, diff, commits)
├── lock.ts # Lock file management
├── prompt.ts # User confirmation prompts
├── components/ # TUI components (header, log, footer)
└── util/ # Helpers (time formatting, logging)
`Data flow:
index.ts starts the TUI (app.tsx) and the loop (loop.ts) in parallel. The loop sends callbacks to update TUI state. State persists to .ralph-state.json for resume capability.Writing Plans
The plan is everything. Invest time here.
`markdown
Project Plan
Phase 1: Setup
- [ ] Initialize project with bun init
- [ ] Add TypeScript configuration
- [ ] Create src/index.ts entry pointPhase 2: Core Features
- [ ] Implement user authentication
- [ ] Add database connection
`Guidelines:
- Small, isolated tasks—one commit each
- Chronological order (dependencies first)
- Use
- [ ] checkboxes (Ralph parses these)
- 1000+ lines is normal; more detail = fewer hallucinationsAGENTS.md
Ralph writes operational learnings here. Future iterations read it.
`markdown
AGENTS.md
Build
- Run bun install before bun run devPitfalls
- Never import from solid-js, use @opentui/solid
`When Ralph makes a mistake, add a sign to prevent it recurring.
Testing
`bash
bun test # run all tests
bun test --watch # watch mode
bun test --coverage # with coverage
``
tests/
├── unit/ # Module isolation tests
├── integration/ # Full workflow tests
├── fixtures/ # Test plan files
└── helpers/ # Mock factories, temp file utils
``- Bun v1.0+
- OpenCode CLI running
MIT