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:

1. Read Instructions - Loads PROMPT.md with your project requirements
2. Execute Claude Code - Runs Claude Code with current context and priorities
3. Track Progress - Updates task lists and logs execution results
4. Evaluate Completion - Checks for exit conditions and project completion signals
5. 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:

1. completion_indicators >= 2 (heuristic detection from natural language patterns)
2. 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