ralph.rb 1.2.4355354345 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ac20f5a142fc020fb06842aa4b6ba550460362fa7e29170162fedc80eb520de
-  data.tar.gz: 1b0b501cec69940980f1133f86e3ab4bebd09e2e8e5b4e44b36604e27a4cc700
+  metadata.gz: 5554c13454fc43d04f41b7f969653cb7d51243eb40df245aefad31d82b38ab3a
+  data.tar.gz: 97909bf34b37d86ed11815c332f6ef6ba747c82c5ae60ded0e4b184a1d4a8120
 SHA512:
-  metadata.gz: 2baaf26526ba2219005f4c15280539c9208fa15b233ddc6957cb9ed3052bf78579be8b406c61f9f573bd1e73b5589e1c14f903e5eb8761780068f62941f4fbbd
-  data.tar.gz: 06bfc404d6c736d81c0422240dbbe9edb733a885bac815b91be0640744ecdb6905252bd846290684876aee51c6ce1918e785058eec8c901993edf350242b74f6
+  metadata.gz: 6cab0f8e38f76a14251de705f0404ed443b9d597ddd93c3ba51a4a46f8ba8db5849d5819570034c95d70e9fbe95a4a4bf576df35564d0405c393eaaf7a1765e5
+  data.tar.gz: 2c9e36d50e6f304a018cac0deaba455421f67b5199e36b756dcffe9adb35fb443f9eaf09d8279231c3c85df10adbff1b88407a4d826cb2f3a7acb0a594c339ff

data/.github/workflows/gem-push.yml

@@ -2,9 +2,9 @@ name: Ruby Gem
 
 on:
   push:
-    branches: ["ruby"]
+    branches: ["ruby2"]
   pull_request:
-    branches: ["ruby"]
+    branches: ["ruby2"]
 
 jobs:
   build:

data/Gemfile

@@ -2,7 +2,7 @@
 
 source "https://rubygems.org"
 
-gemspec
+gemspec name: "ralph.rb"
 
 group :development do
   #gem "minitest", "~> 5.0"

data/Gemfile.lock

@@ -0,0 +1,53 @@
+PATH
+  remote: .
+  specs:
+    ralph.rb (2.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    json (2.18.1)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    minitest (5.27.0)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rubocop (1.84.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  ralph.rb!
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.7.2

data/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <h1 align="center">Open Ralph Wiggum</h1>
-  <h3 align="center">Autonomous Agentic Loop for Claude Code, Codex & OpenCode</h3>
+  <h1 align="center">Ralph.rb</h1>
+  <h3 align="center">Autonomous Agentic Loop for OpenCode</h3>
 </p>
 
 <p align="center">
-  <img src="screenshot.webp" alt="Open Ralph Wiggum - Iterative AI coding loop for Claude Code and Codex" />
+  <img src="ralph.jpg" alt="Ralph Wiggum - Iterative AI coding loop for Opencode" />
 </p>
 
 <p align="center">
@@ -13,11 +13,6 @@
   <em>Based on the <a href="https://ghuntley.com/ralph/">Ralph Wiggum technique</a> by Geoffrey Huntley</em>
 </p>
 
-<p align="center">
-  <a href="https://github.com/Th0rgal/ralph-wiggum/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
-  <a href="https://github.com/Th0rgal/ralph-wiggum"><img src="https://img.shields.io/badge/built%20with-Bun%20%2B%20TypeScript-f472b6.svg" alt="Built with Bun + TypeScript"></a>
-  <a href="https://github.com/Th0rgal/ralph-wiggum/releases"><img src="https://img.shields.io/github/v/release/Th0rgal/ralph-wiggum?include_prereleases" alt="Release"></a>
-</p>
 
 <p align="center">
   <a href="#supported-agents">Supported Agents</a> •

data/lib/ralph/cli.rb

@@ -1,222 +1,140 @@
 # frozen_string_literal: true
 
 module Ralph
+  # Command-line interface for ralph. Parses subcommands (build/plan),
+  # arguments, reads stdin when piped, and launches the Loop.
+  #
+  # Usage:
+  #   ralph build "focus on auth" --model=opus-4.5 --max-iterations=10
+  #   ralph plan "user authentication system"
+  #   ralph --max-iterations=10  # equivalent to: ralph build --max-iterations=10
+  #   cat prompt.md | ralph build --model=opus-4.5
   class CLI
-    def initialize(argv = ARGV)
-      @config = Config.new
-
-      @parser = OptionParser.new do |o|
-        o.banner = <<~BANNER
-          Ralph Wiggum Loop - Iterative AI development with AI agents
-
-          Usage:
-            ralph "<prompt>" [options]
-
-          Commands:
-            --status            Show current Ralph loop status and history
-            --add-context TEXT  Add context for the next iteration
-            --clear-context     Clear any pending context
-            --list-tasks        Display the current task list with indices
-            --add-task "desc"   Add a new task to the list
-            --remove-task N     Remove task at index N (including subtasks)
-
-          Options:
-        BANNER
-
-        o.on("--agent AGENT", Agents.valid_agent_names, "AI agent: #{Agents.valid_agent_names.join(', ')} (default: opencode)") do |v|
-          @config.chosen_agent = v
-        end
-
-        o.on("--min-iterations N", Integer, "Minimum iterations before completion (default: 1)") do |v|
-          @config.min_iterations = v
-        end
-
-        o.on("--max-iterations N", Integer, "Maximum iterations before stopping (default: unlimited)") do |v|
-          @config.max_iterations = v
-        end
-
-        o.on("--completion-promise TEXT", "Phrase that signals completion (default: COMPLETE)") do |v|
-          @config.completion_promise = v
-        end
-
-        o.on("-t", "--tasks", "Enable Tasks Mode for structured task tracking") do
-          @config.tasks_mode = true
-        end
-
-        o.on("--task-promise TEXT", "Phrase that signals task completion (default: READY_FOR_NEXT_TASK)") do |v|
-          @config.task_promise = v
-        end
-
-        o.on("--model MODEL", "Model to use (agent-specific)") do |v|
-          @config.model = v
-        end
-
-        o.on("--[no-]stream", "Stream agent output in real-time (default: on)") do |v|
-          @config.stream_output = v
-        end
+    SUBCOMMANDS = %w[build plan].freeze
+
+    attr_reader :subcommand
+
+    def initialize(argv)
+      @argv = argv.dup
+      @subcommand = extract_subcommand
+      @options = {
+        model: nil,
+        max_iterations: nil,
+        duration: nil,
+        max_context: nil,
+        completion: nil
+      }
+    end
 
-        o.on("--verbose-tools", "Print every tool line (disable compact summary)") do
-          @config.verbose_tools = true
-        end
+    def run
+      parse_options
+      prompt_object = build_prompt_object
+      @options[:prompt] = prompt_object
 
-        o.on("--no-plugins", "Disable non-auth OpenCode plugins (opencode only)") do
-          @config.disable_plugins = true
-        end
+      Ralph::Loop.new(@options).run
 
-        o.on("--[no-]allow-all", "Auto-approve all tool permissions (default: on)") do |v|
-          @config.allow_all_permissions = v
-        end
+    rescue OptionParser::InvalidOption, OptionParser::MissingArgument => error
+      $stderr.puts "Error: #{error.message}"
+      $stderr.puts parser.help
+      exit 1
+    end
 
-        # Subcommands -- these set a command to dispatch after parsing
-        o.on("-v", "--version", "Show version") do
-          puts "ralph #{VERSION}"
-          exit 0
-        end
+    private
 
-        o.on("--status", "Show current loop status and history") do
-          Output::Status.call(options: @config.to_h)
-          exit 0
+      def extract_subcommand
+        if @argv.first && SUBCOMMANDS.include?(@argv.first)
+          @argv.shift
+        else
+          "build"
         end
+      end
 
-        o.on("--add-context TEXT", "Add context for the next iteration") do |context_text|
-
-          Storage::Context.new.append(
-            "\n## Context added at #{Time.now.utc.iso8601}\n#{context_text}\n"
-          )
-
-          puts "✅ Context added for next iteration"
-          puts "   File: #{Storage::Context.new.path}"
-
-          Storage::State.load.then do |state|
-            if state&.active
-              puts "   Will be picked up in iteration #{state.iteration + 1}"
-            else
-              puts "   Will be used when loop starts"
-            end
+      def parse_options
+        parser.parse!(@argv)
+      end
+      
+      def parser
+        @parser ||= OptionParser.new do |option_parser|
+          option_parser.banner = "Usage: ralph [build|plan] [text] [options]"
+          option_parser.separator ""
+          option_parser.separator "Subcommands:"
+          option_parser.separator "  build    Implement tasks from the plan (default)"
+          option_parser.separator "  plan     Gap analysis and plan generation"
+          option_parser.separator ""
+          option_parser.separator "Options:"
+
+          option_parser.on("--model=MODEL", "Model to use (e.g. opus-4.5)") do |value|
+            @options[:model] = value
           end
 
-          exit 0
-        end
-
-        o.on("--clear-context", "Clear any pending context") do
-          Storage::Context.new.then do |context|
-            if context.present?
-              context.clear
-              puts "✅ Context cleared"
-            else
-              puts "ℹ️  No pending context to clear"
-            end
+          option_parser.on("--max-iterations=N", Integer, "Maximum number of iterations") do |value|
+            @options[:max_iterations] = value
           end
 
-          exit 0
-        end
+          option_parser.on("--duration=SECONDS", Integer, "Maximum total duration in seconds") do |value|
+            @options[:duration] = value
+          end
 
-        o.on("--list-tasks", "Display the current task list") do
-          begin
-            Storage::Tasks.new.load_tasks.then do |tasks|
-              if tasks
-                tasks.display_with_indices
-              else
-                puts "No tasks file found. Use --add-task to create your first task."
-              end
-            end
-          rescue StandardError => e
-            $stderr.puts "Error reading tasks file: #{e}"
-            exit 1
+          option_parser.on("--max-context=N", Integer, "Maximum context tokens before iteration restart") do |value|
+            @options[:max_context] = value
           end
 
-          exit 0
-        end
+          option_parser.on("--completion=STRING", "Completion string the agent emits when done") do |value|
+            @options[:completion] = value
+          end
 
-        o.on("--add-task DESC", "Add a new task to the list") do |description|
-          begin
-            Storage::Tasks.new.add_task(description)
-            puts "✅ Task added: \"#{description}\""
-          rescue StandardError => e
-            $stderr.puts "Error adding task: #{e}"
-            exit 1
+          option_parser.on("-h", "--help", "Show this help message") do
+            puts option_parser
+            exit 0
           end
 
-          exit 0
+          option_parser.on("-v", "--version", "Show version") do
+            puts "ralph #{Ralph::VERSION}"
+            exit 0
+          end
         end
+      end
 
-        o.on("--remove-task N", Integer, "Remove task at index N") do |task_index|
-          begin
-            Storage::Tasks.new.remove_task(task_index)
-            puts "✅ Removed task #{task_index} and its subtasks"
-          rescue IndexError => e
-            $stderr.puts "Error: #{e.message}"
-            exit 1
-          rescue RuntimeError => e
-            $stderr.puts "Error: #{e.message}"
-            exit 1
-          rescue StandardError => e
-            $stderr.puts "Error removing task: #{e}"
-            exit 1
-          end
+      def read_user_text
+        parts = []
 
-          exit 0
+        # Read from stdin if data is being piped in
+        unless $stdin.tty?
+          stdin_content = $stdin.read
+          parts << stdin_content if stdin_content && !stdin_content.strip.empty?
         end
 
-        o.separator ""
-        o.separator "Examples:"
-        o.separator '  ralph "Build a REST API for todos"'
-        o.separator '  ralph "Fix the auth bug" --max-iterations 10'
-        o.separator '  ralph "Add tests" --completion-promise "ALL TESTS PASS" --model openai/gpt-5.1'
-        o.separator '  ralph --status'
-        o.separator '  ralph --add-context "Focus on the auth module first"'
-        o.separator ""
-        o.separator "How it works:"
-        o.separator "  1. Sends your prompt to the selected AI agent"
-        o.separator "  2. AI agent works on the task"
-        o.separator "  3. Checks output for completion promise"
-        o.separator "  4. If not complete, repeats with same prompt"
-        o.separator "  5. AI sees its previous work in files"
-        o.separator "  6. Continues until promise detected or max iterations"
-        o.separator ""
-        o.separator "To stop manually: Ctrl+C"
-        o.separator "Learn more: https://ghuntley.com/ralph/"
+        # Remaining positional arguments are the inline text
+        parts << @argv.join(" ") if @argv.any?
+
+        parts.join("\n\n") if parts.any?
       end
 
-    end
+      def build_prompt_object
+        user_text = read_user_text
+        completion = @options[:completion]
 
-    def run(argv = ARGV.dup)
-      @user_prompt = @parser.parse(argv).then do |remaining_args|
-        if $stdin.tty?
-          remaining_args.join(" ").strip
+        if @subcommand == "plan"
+          build_plan_prompt(user_text, completion)
         else
-          [$stdin.read, remaining_args.join(" ")].join("\n").strip
+          build_build_prompt(user_text, completion)
         end
       end
 
-      if @user_prompt.empty?
-        abort "
-          Error: No prompt provided
-          Usage: ralph 'Your task description' [options]
-          Run 'ralph --help' for more information
-        "
+      def build_plan_prompt(user_text, completion)
+        Hash.new.then do |plan_options|
+          plan_options[:goal] = user_text if user_text
+          plan_options[:all_done] = completion if completion
+          Prompt::Plan.new(**plan_options)
+        end
       end
 
-      tasks   = Storage::Tasks.new
-      context = Storage::Context.new
-
-      PromptTemplate.inject(@user_prompt, context: context, tasks: tasks).then do |prompt|
-        @config.prompt = prompt
-
-        if @config.max_iterations > 0 && @config.min_iterations > @config.max_iterations
-          abort "Error: --min-iterations (#{@config.min_iterations}) cannot be greater than --max-iterations (#{@config.max_iterations})"
+      def build_build_prompt(user_text, completion)
+        Hash.new.then do |build_options|
+          build_options[:context] = user_text if user_text
+          build_options[:all_done] = completion if completion
+          Prompt::Build.new(**build_options)
         end
-
-        state   = Storage::State.from_config(@config, prompt: prompt)
-        history = Storage::History.new
-
-        Ralph::Loop.new(@config, state, history, context, tasks).run
       end
-
-    rescue StandardError => e
-      $stderr.puts "Fatal error: #{e}"
-      Storage::State.clear
-      exit 1
-    end
   end
 end

data/lib/ralph/display.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Ralph
+  # Handles all terminal output for the loop -- iteration status, metrics,
+  # agent text, and summary information.
+  class Display
+    SEPARATOR = "-" * 60
+
+    def initialize(loop_engine)
+      @loop_engine = loop_engine
+    end
+
+    def show_start(prompt)
+      puts SEPARATOR
+      puts "ralph -- autonomous agentic loop"
+      puts SEPARATOR
+      puts "Prompt: #{prompt[0, 200]}#{"..." if prompt.length > 200}"
+      puts SEPARATOR
+    end
+
+    def show_iteration_start
+      puts
+      puts "#{SEPARATOR}"
+      puts "Iteration #{@loop_engine.iteration_number} | " \
+           "elapsed: #{format_duration(@loop_engine.elapsed_seconds)} | " \
+           "context: #{format_tokens(@loop_engine.metrics.current_context)} | " \
+           "tokens: #{format_tokens(@loop_engine.metrics.tokens_consumed)}"
+      puts SEPARATOR
+    end
+
+    def show_event(event)
+      if event.is_a?(Events::Text) && event.text
+        print event.text
+        $stdout.flush
+      end
+
+      if event.is_a?(Events::ToolUse)
+        puts
+        puts "  [tool] #{event.tool} (#{event.status})"
+      end
+
+      if event.is_a?(Events::StepFinish)
+        puts
+        puts "  [step] context=#{format_tokens(event.context_size)} " \
+             "output=#{format_tokens(event.output_tokens)} " \
+             "cache_r=#{format_tokens(event.cache_read)} " \
+             "cache_w=#{format_tokens(event.cache_write)}"
+      end
+    end
+
+    def show_iteration_end
+      puts
+      puts "  Iteration #{@loop_engine.iteration_number} complete | " \
+           "steps: #{@loop_engine.metrics.step_count} | " \
+           "iteration tokens: #{format_tokens(@loop_engine.metrics.iteration_tokens)}"
+    end
+
+    def show_iteration_cancelled(reason)
+      puts
+      puts "  ** Iteration cancelled: #{reason}"
+    end
+
+    def show_iteration_error(message)
+      puts
+      puts "  ** Iteration error: #{message}"
+    end
+
+    def show_termination(reason)
+      puts
+      puts "  ** Loop terminated: #{reason}"
+    end
+
+    def show_summary
+      metrics = @loop_engine.metrics
+      puts
+      puts SEPARATOR
+      puts "SUMMARY"
+      puts SEPARATOR
+      puts "  Status:      #{@loop_engine.completed ? "COMPLETED" : "TERMINATED"}"
+      puts "  Iterations:  #{@loop_engine.iteration_number}"
+      puts "  Duration:    #{format_duration(@loop_engine.elapsed_seconds)}"
+      puts "  Steps:       #{metrics.step_count}"
+      puts "  Tokens:      #{format_tokens(metrics.tokens_consumed)}"
+      puts "  Context:     #{format_tokens(metrics.current_context)}"
+      puts SEPARATOR
+    end
+
+    private
+
+    def format_duration(seconds)
+      minutes = (seconds / 60).to_i
+      remaining_seconds = (seconds % 60).to_i
+      if minutes > 0
+        "#{minutes}m #{remaining_seconds}s"
+      else
+        "#{remaining_seconds}s"
+      end
+    end
+
+    def format_tokens(count)
+      if count >= 1_000_000
+        format("%.1fM", count / 1_000_000.0)
+      elsif count >= 1_000
+        format("%.1fk", count / 1_000.0)
+      else
+        count.to_s
+      end
+    end
+  end
+end

data/lib/ralph/events.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Events
+    # Base event wrapping the common fields from opencode JSON stream lines
+    class Base
+      attr_reader :type, :timestamp, :session_id, :part
+
+      def initialize(data)
+        @type = data["type"]
+        @timestamp = data["timestamp"]
+        @session_id = data["sessionID"]
+        @part = data["part"] || {}
+      end
+    end
+
+    # Emitted when a new LLM step begins
+    class StepStart < Base
+      def snapshot
+        part["snapshot"]
+      end
+    end
+
+    # Emitted when the model streams text content
+    class Text < Base
+      def text
+        part["text"]
+      end
+    end
+
+    # Emitted when the model invokes a tool
+    class ToolUse < Base
+      def tool
+        part["tool"]
+      end
+
+      def call_id
+        part["callID"]
+      end
+
+      def state
+        part["state"] || {}
+      end
+
+      def status
+        state["status"]
+      end
+
+      def input
+        state["input"]
+      end
+
+      def output
+        state["output"]
+      end
+    end
+
+    # Emitted when a step completes -- carries the token usage data
+    class StepFinish < Base
+      def reason
+        part["reason"]
+      end
+
+      def tokens
+        part["tokens"] || {}
+      end
+
+      def input_tokens
+        tokens["input"] || 0
+      end
+
+      def output_tokens
+        tokens["output"] || 0
+      end
+
+      def reasoning_tokens
+        tokens["reasoning"] || 0
+      end
+
+      def cache
+        tokens["cache"] || {}
+      end
+
+      def cache_read
+        cache["read"] || 0
+      end
+
+      def cache_write
+        cache["write"] || 0
+      end
+
+      # Total context size for this step: input + cache.read + cache.write
+      def context_size
+        input_tokens + cache_read + cache_write
+      end
+    end
+
+    EVENT_TYPES = {
+      "step_start" => StepStart,
+      "text" => Text,
+      "tool_use" => ToolUse,
+      "step_finish" => StepFinish
+    }.freeze
+
+    # Parse a single JSON line into the appropriate event object.
+    # Returns nil for unknown event types or malformed JSON.
+    def self.parse(line)
+      data = JSON.parse(line)
+      event_class = EVENT_TYPES[data["type"]]
+      if event_class
+        event_class.new(data)
+      end
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end