Ralph-Lisa Loop

Turn-based dual-agent collaboration: Ralph codes, Lisa reviews, consensus required.

Quick Start

npm i -g ralph-lisa-loop
cd your-project
ralph-lisa init
ralph-lisa start "implement login feature"

How It Works

Ralph writes → Lisa reviews → Consensus → Next step
     ↑                                        |
     └────────────────────────────────────────┘

• Ralph (Claude Code): Lead developer — researches, plans, codes, tests
• Lisa (Codex): Code reviewer — reviews diffs, checks edge cases
• You: Tech lead — architecture, scope, tiebreaking

Key Features

• Turn Control — Only one agent works at a time; submissions pass the turn automatically
• Tag System — [PLAN], [CODE], [FIX], [PASS], [NEEDS_WORK], [CHALLENGE], [CONSENSUS]
• Consensus Protocol — Both agents must agree before proceeding; advisory verdicts, not commands
• Policy Layer — Configurable warn/block mode for submission quality checks
• Auto Mode — tmux-based automation with file watcher for hands-off operation
• Round 1 Mandatory Plan — Ralph must submit [PLAN] first for Lisa to verify understanding
• Goal Guardian — Lisa checks for direction drift before every review
• Mid-Session Task Update — Change direction without restarting
• Deadlock Detection — After 8 consecutive [NEEDS_WORK] rounds, watcher auto-pauses for user intervention
• Minimal Init — Zero-intrusion mode with plugin/global config architecture

Essential Commands

# Setup
ralph-lisa init [dir]                    # Initialize project
ralph-lisa start "task"                  # Launch both agents
ralph-lisa auto "task"                   # Auto mode (tmux)

# Turn control
ralph-lisa whose-turn                    # Check whose turn
ralph-lisa submit-ralph --file f.md      # Ralph submits
ralph-lisa submit-lisa --file f.md       # Lisa submits

# Information
ralph-lisa status                        # Current status
ralph-lisa read work.md                  # Ralph's latest
ralph-lisa read review.md                # Lisa's latest
ralph-lisa history                       # Full history

# Flow control
ralph-lisa step "phase-name"             # Enter new step
ralph-lisa update-task "new direction"   # Change task mid-session

# Diagnostics
ralph-lisa doctor                        # Check dependencies

Requirements

• Node.js >= 18
• Claude Code — for Ralph
• Codex CLI — for Lisa
• tmux — for auto mode (brew install tmux / apt install tmux)

Documentation

Full documentation on GitHub:

• User Guide — Setup, workflows, configuration
• Command Reference — All CLI commands
• FAQ — Common questions and troubleshooting
• Changelog — Version history
• Design Philosophy — Why dual-agent works

Other languages: 日本語 | 中文

License

MIT