Molt Pi Maker
Your AI guide for Molt Pi Maker.
What It Does
- Generates Python code for GPIO, sensors, cameras
- Explains wiring pin-by-pin
- Troubleshoots when things break
- Teaches as you build
Quick Start
from gpiozero import LED
led = LED(17)
led.blink()
Includes
- GPIO pinout reference
- Common libraries guide
- Beginner → Advanced projects
- Troubleshooting tips
Project Status
Version: v0.9.9 - Active Development
Core Features: Working and tested
Test Coverage: 308 tests, 100% pass rate
What's Working Now
- Autonomous development loops with intelligent exit detection
- Dual-condition exit gate: Requires BOTH completion indicators AND explicit EXIT_SIGNAL
- Rate limiting with hourly reset (100 calls/hour, configurable)
- Circuit breaker with advanced error detection (prevents runaway loops)
- Response analyzer with semantic understanding and two-stage error filtering
- JSON output format support with automatic fallback to text parsing
- Session continuity with
--continue flag for context preservation
- Session expiration with configurable timeout (default: 24 hours)
- Modern CLI flags:
--output-format, --allowed-tools, --no-continue
- Multi-line error matching for accurate stuck loop detection
- 5-hour API limit handling with user prompts
- tmux integration for live monitoring
- PRD import functionality
- CI/CD pipeline with GitHub Actions
- Dedicated uninstall script for clean removal
- 308 passing tests across 11 test files
Recent Improvements
v0.9.9 - EXIT_SIGNAL Gate & Uninstall Script
- Fixed premature exit bug: completion indicators now require Claude's explicit
EXIT_SIGNAL: true
- Added dual-condition check preventing exits when Claude reports work in progress
- Added
response_analyzer.sh fix to respect explicit EXIT_SIGNAL over heuristics
- Added dedicated
uninstall.sh script for clean Ralph removal
- Session expiration with configurable timeout (default: 24 hours)
- Added 32 new tests for EXIT_SIGNAL behavior and session expiration
- Test count: 308 (up from 276)
v0.9.8 - Modern CLI for PRD Import
- Modernized
ralph_import.sh to use Claude Code CLI JSON output format
- JSON output format support with
--output-format json for structured responses
- Enhanced error handling with structured JSON error messages
- Improved file verification with JSON-derived status information
- Backward compatibility with older CLI versions (automatic text fallback)
- Added 11 new tests for modern CLI features
v0.9.7 - Session Lifecycle Management
- Complete session lifecycle management with automatic reset triggers
- Session auto-reset on: circuit breaker open, manual interrupt, project completion
- Added
--reset-session CLI flag for manual session reset
- Session history tracking (last 50 transitions) for debugging
- Added 26 new tests for session continuity features
v0.9.6 - JSON Output & Session Management
- Extended
parse_json_response() to support Claude Code CLI JSON format
- Added session management functions:
store_session_id(), get_last_session_id(), should_resume_session()
- Cross-platform epoch time utilities in date_utils.sh
- Added 16 new tests covering Claude CLI format and session management
v0.9.5 - PRD Import Tests
- Added 22 comprehensive tests for
ralph_import.sh PRD conversion script
- Tests cover: file format support, output file creation, project naming, error handling
v0.9.4 - Project Setup Tests
- Added 36 comprehensive tests for
setup.sh project initialization script
- Tests cover: directory creation, template copying, git initialization
v0.9.3 - Installation Tests
- Added 14 comprehensive tests for
install.sh global installation script
- Tests cover: directory creation, command installation, dependency detection
v0.9.2 - Prompt File Fix
- Fixed critical bug: replaced non-existent
--prompt-file CLI flag with -p flag
- Modern CLI mode now correctly passes prompt content via
-p "$(cat file)"
- Added error handling for missing prompt files in
build_claude_command()
v0.9.1 - Modern CLI Commands (Phase 1.1)
- JSON output format support with
--output-format json (default)
- Session continuity using
--continue flag for cross-loop context
- Tool permissions via
--allowed-tools flag
- CI/CD pipeline with kcov coverage reporting
v0.9.0 - Circuit Breaker Enhancements
- Fixed multi-line error matching in stuck loop detection
- Eliminated JSON field false positives (e.g.,
"is_error": false)
- Added two-stage error filtering for accurate detection
In Progress
- Expanding test coverage
- Log rotation functionality
- Dry-run mode
- Configuration file support (.ralphrc)
- Metrics and analytics tracking
- Desktop notifications
- Git backup and rollback system
Timeline to v1.0: ~4 weeks | Full roadmap | Contributions welcome!
Features
- Autonomous Development Loop - Continuously executes Claude Code with your project requirements
- Intelligent Exit Detection - Dual-condition check requiring BOTH completion indicators AND explicit EXIT_SIGNAL
- Session Continuity - Preserves context across loop iterations with automatic session management
- Session Expiration - Configurable timeout (default: 24 hours) with automatic session reset
- Rate Limiting - Built-in API call management with hourly limits and countdown timers
- 5-Hour API Limit Handling - Detects Claude's 5-hour usage limit and offers wait/exit options
- Live Monitoring - Real-time dashboard showing loop status, progress, and logs
- Task Management - Structured approach with prioritized task lists and progress tracking
- Project Templates - Quick setup for new projects with best-practice structure
- Comprehensive Logging - Detailed execution logs with timestamps and status tracking
- Configurable Timeouts - Set execution timeout for Claude Code operations (1-120 minutes)
- Verbose Progress Mode - Optional detailed progress updates during execution
- Response Analyzer - AI-powered analysis of Claude Code responses with semantic understanding
- Circuit Breaker - Advanced error detection with two-stage filtering, multi-line error matching, and automatic recovery
- CI/CD Integration - GitHub Actions workflow with automated testing
- Clean Uninstall - Dedicated uninstall script for complete removal
Quick Start
Ralph has two phases: one-time installation and per-project setup.
INSTALL ONCE USE MANY TIMES
+-----------------+ +----------------------+
| ./install.sh | -> | ralph-setup project1 |
| | | ralph-setup project2 |
| Adds global | | ralph-setup project3 |
| commands | | ... |
+-----------------+ +----------------------+
Phase 1: Install Ralph (One Time Only)
Install Ralph globally on your system:
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh
This adds ralph, ralph-monitor, and ralph-setup commands to your PATH.
Note: You only need to do this once per system. After installation, you can delete the cloned repository if desired.
Phase 2: Initialize New Projects (Per Project)
For each new project you want Ralph to work on:
Option A: Import Existing PRD/Specifications
# Convert existing PRD/specs to Ralph format (recommended)
ralph-import my-requirements.md my-project
cd my-project
# Review and adjust the generated files:
# - PROMPT.md (Ralph instructions)
# - @fix_plan.md (task priorities)
# - specs/requirements.md (technical specs)
# Start autonomous development
ralph --monitor
Option B: Manual Project Setup
# Create blank Ralph project
ralph-setup my-awesome-project
cd my-awesome-project
# Configure your project requirements manually
# Edit PROMPT.md with your project goals
# Edit specs/ with detailed specifications
# Edit @fix_plan.md with initial priorities
# Start autonomous development
ralph --monitor
Ongoing Usage (After Setup)
Once Ralph is installed and your project is initialized:
# Navigate to any Ralph project and run:
ralph --monitor # Integrated tmux monitoring (recommended)
# Or use separate terminals:
ralph # Terminal 1: Ralph loop
ralph-monitor # Terminal 2: Live monitor dashboard
Uninstalling Ralph
To completely remove Ralph from your system:
# Run the uninstall script
./uninstall.sh
# Or if you deleted the repo, download and run:
curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash
How It Works
Ralph operates on a simple but powerful cycle:
- Read Instructions - Loads
PROMPT.md with your project requirements
- Execute Claude Code - Runs Claude Code with current context and priorities
- Track Progress - Updates task lists and logs execution results
- Evaluate Completion - Checks for exit conditions and project completion signals
- Repeat - Continues until project is complete or limits are reached
Intelligent Exit Detection
Ralph uses a dual-condition check to prevent premature exits during productive iterations:
Exit requires BOTH conditions:
completion_indicators >= 2 (heuristic detection from natural language patterns)- Claude's explicit
EXIT_SIGNAL: true in the RALPH_STATUS block
Example behavior:
Loop 5: Claude outputs "Phase complete, moving to next feature"
→ completion_indicators: 3 (high confidence from patterns)
→ EXIT_SIGNAL: false (Claude says more work needed)
→ Result: CONTINUE (respects Claude's explicit