ralph.rb 1.2.435535439

data/lib/ralph/agents/base.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ralph
+  module Agents
+    class Base
+      include ::Ralph::Helpers
+
+      # Result of executing an agent process
+      ExecutionResult = Struct.new(:stdout_text, :stderr_text, :tool_counts, :exit_code, keyword_init: true) do
+        def combined_output
+          "#{stdout_text}\n#{stderr_text}"
+        end
+      end
+
+      def type        = raise NotImplementedError
+      def command     = raise NotImplementedError
+      def config_name = raise NotImplementedError
+
+      def parse_tool_output(_line) = raise NotImplementedError
+      def build_args(_prompt, _model, _options) = raise NotImplementedError
+
+      def build_env(_options) = ENV.to_h.dup
+
+      def execute(prompt, options = {})
+        command_args = build_args(prompt, options[:model],
+                                  { allow_all_permissions: options[:allow_all_permissions] })
+        environment = build_env(
+          filter_plugins: options[:disable_plugins],
+          allow_all_permissions: options[:allow_all_permissions]
+        )
+        full_command = [command] + command_args
+
+        if options[:stream_output]
+          execute_streaming(environment, full_command, options[:on_line])
+        else
+          execute_captured(environment, full_command)
+        end
+      rescue StandardError => agent_error
+        Agents::Base::ExecutionResult.new(
+          stdout_text: "", stderr_text: agent_error.to_s, tool_counts: {}, exit_code: -1
+        )
+      end
+
+      # Collects tool usage counts from output text.
+      # Delegates to parse_tool_output for each line.
+      def collect_tool_counts(text)
+        Hash.new(0).tap do |counts|
+          text.each_line do |line|
+            tool = parse_tool_output(line)
+            counts[tool] += 1 if tool
+          end
+        end
+      end
+
+      # Returns a fatal error message if one is detected in the output,
+      # or nil if no fatal error is found. Subclasses may override.
+      def detect_fatal_error(_output) = nil
+
+      # Extracts error patterns from agent output. Subclasses may override
+      # for agent-specific error formats.
+      def extract_errors(output)
+        errors = []
+        output.each_line do |line|
+          lower = line.downcase
+          if lower.include?("error:") ||
+             lower.include?("failed:") ||
+             lower.include?("exception:") ||
+             lower.include?("typeerror") ||
+             lower.include?("syntaxerror") ||
+             lower.include?("referenceerror") ||
+             (lower.include?("test") && lower.include?("fail"))
+            cleaned = line.strip[0, 200]
+            errors << cleaned if cleaned && !cleaned.empty? && !errors.include?(cleaned)
+          end
+        end
+        errors.first(10)
+      end
+
+      def validate!
+        path = which(command)
+        unless path
+          $stderr.puts "Error: #{config_name} CLI ('#{command}') not found."
+          exit 1
+        end
+      end
+
+      private
+
+        def execute_streaming(environment, full_command, on_line)
+          tool_counts = Hash.new(0)
+          stdout_text = +""
+          stderr_text = +""
+          mutex = Mutex.new
+
+          stdin, stdout, stderr, wait_thread = Open3.popen3(environment, *full_command)
+          stdin.close
+
+          stdout_reader = Threads::StreamReader.new(
+            stdout, stdout_text, mutex, tool_counts, on_line, false, method(:parse_tool_output)
+          )
+          stderr_reader = Threads::StreamReader.new(
+            stderr, stderr_text, mutex, tool_counts, on_line, true, method(:parse_tool_output)
+          )
+
+          stdout_reader.join
+          stderr_reader.join
+          exit_status = wait_thread.value
+
+          ExecutionResult.new(
+            stdout_text: stdout_text,
+            stderr_text: stderr_text,
+            tool_counts: tool_counts,
+            exit_code: exit_status.exitstatus || 1
+          )
+        end
+
+        def execute_captured(environment, full_command)
+          stdout, stderr, status = Open3.capture3(environment, *full_command, stdin_data: "")
+          tool_counts = collect_tool_counts("#{stdout}\n#{stderr}")
+
+          ExecutionResult.new(
+            stdout_text: stdout,
+            stderr_text: stderr,
+            tool_counts: tool_counts,
+            exit_code: status.exitstatus || 1
+          )
+        end
+    end
+  end
+end

data/lib/ralph/agents/claude_code.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Agents
+    class ClaudeCode < Base
+
+      def type = :claude_code
+      def command = "claude"
+      def config_name = "Claude Code"
+
+      def build_args(prompt, model, options)
+        args = ["-p", prompt]
+        args.push("--model", model) if model && !model.empty?
+        args.push("--dangerously-skip-permissions") if options && options[:allow_all_permissions]
+        args
+      end
+
+      def parse_tool_output(line)
+        match = strip_ansi(line).match(/(?:Using|Called|Tool:)\s+([A-Za-z0-9_-]+)/i)
+        match ? match[1] : nil
+      end
+    end
+  end
+end

data/lib/ralph/agents/codex.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Agents
+    class Codex < Base
+
+      def type = :codex
+      def command = "codex"
+      def config_name = "Codex"
+
+      def build_args(prompt, model, options)
+        args = ["exec"]
+        args.push("--model", model) if model && !model.empty?
+        args.push("--full-auto") if options && options[:allow_all_permissions]
+        args.push(prompt)
+        args
+      end
+
+      def parse_tool_output(line)
+        match = strip_ansi(line).match(/(?:Tool:|Using|Calling|Running)\s+([A-Za-z0-9_-]+)/i)
+        match ? match[1] : nil
+      end
+    end
+  end
+end

data/lib/ralph/agents/open_code.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Agents
+    class OpenCode < Base
+
+      def type = :opencode
+      def command = "opencode"
+      def config_name = "OpenCode"
+
+      def build_args(prompt, model, _options)
+        args = ["run"]
+        args.push("-m", model) if model && !model.empty?
+        args.push(prompt)
+        args
+      end
+
+      def parse_tool_output(line)
+        match = strip_ansi(line).match(/^\|\s{2}([A-Za-z0-9_-]+)/)
+        match ? match[1] : nil
+      end
+
+      def detect_fatal_error(output)
+        if output.include?("ralph-wiggum is not yet ready for use. This is a placeholder package.")
+          "Placeholder plugin error detected"
+        end
+      end
+    end
+  end
+end

data/lib/ralph/agents.rb

@@ -0,0 +1,24 @@
+module Ralph
+  module Agents
+
+    module_function
+
+    AGENT_NAME_MAP = {
+      "opencode" => :opencode,
+      "claude-code" => :claude_code,
+      "codex" => :codex
+    }.freeze
+
+    def valid_agent_names = AGENT_NAME_MAP.keys
+
+    def resolve(name_str)
+      AGENT_NAME_MAP[name_str].then do |sym|
+        case sym
+        when :opencode    then OpenCode.new
+        when :claude_code then ClaudeCode.new
+        when :codex       then Codex.new
+        else nil          end
+      end
+    end
+  end
+end

data/lib/ralph/cli.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Ralph
+  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
+
+        o.on("--verbose-tools", "Print every tool line (disable compact summary)") do
+          @config.verbose_tools = true
+        end
+
+        o.on("--no-plugins", "Disable non-auth OpenCode plugins (opencode only)") do
+          @config.disable_plugins = true
+        end
+
+        o.on("--[no-]allow-all", "Auto-approve all tool permissions (default: on)") do |v|
+          @config.allow_all_permissions = v
+        end
+
+        # Subcommands -- these set a command to dispatch after parsing
+        o.on("-v", "--version", "Show version") do
+          puts "ralph #{VERSION}"
+          exit 0
+        end
+
+        o.on("--status", "Show current loop status and history") do
+          Output::Status.call(options: @config.to_h)
+          exit 0
+        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
+          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
+          end
+
+          exit 0
+        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
+          end
+
+          exit 0
+        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
+          end
+
+          exit 0
+        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
+
+          exit 0
+        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/"
+      end
+
+    end
+
+    def run(argv = ARGV.dup)
+      @user_prompt = @parser.parse(argv).then do |remaining_args|
+        if $stdin.tty?
+          remaining_args.join(" ").strip
+        else
+          [$stdin.read, remaining_args.join(" ")].join("\n").strip
+        end
+      end
+
+      if @user_prompt.empty?
+        abort "
+          Error: No prompt provided
+          Usage: ralph 'Your task description' [options]
+          Run 'ralph --help' for more information
+        "
+      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})"
+        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/config.rb

@@ -0,0 +1,40 @@
+module Ralph
+  class Config
+    # Single source of truth for config option names and their defaults.
+    # Use a lambda for mutable defaults to avoid shared state.
+    OPTIONS = {
+      prompt:                -> { PromptTemplate.new("") },
+      min_iterations:        1,
+      max_iterations:        0,
+      completion_promise:    "COMPLETE",
+      tasks_mode:            false,
+      task_promise:          "READY_FOR_NEXT_TASK",
+      model:                 "",
+      chosen_agent:            "opencode",
+      disable_plugins:       false,
+      allow_all_permissions: true,
+      stream_output:         true,
+      verbose_tools:         false,
+    }.freeze
+
+    attr_accessor(*OPTIONS.keys)
+
+    # Runtime state (not constructor args, not in to_h).
+    attr_accessor :current_pid, :stopping
+
+    def initialize(**opts)
+      OPTIONS.each do |key, default|
+        value = opts.fetch(key) { default.respond_to?(:call) ? default.call : default }
+        instance_variable_set(:"@#{key}", value)
+      end
+      @current_pid = nil
+      @stopping    = false
+    end
+
+    # Returns a hash of options suitable for passing to Loop#call.
+    # Excludes runtime state (current_pid, stopping).
+    def to_h
+      OPTIONS.keys.map { |k| [k, send(k)] }.to_h
+    end
+  end
+end

data/lib/ralph/git/file_snapshot.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ralph
+  module Git
+    # Captures and compares file state via git for change detection
+    class FileSnapshot
+      attr_reader :files
+
+      def initialize(files)
+        @files = files
+      end
+
+      # Capture a snapshot of all tracked/modified files and their git hashes
+      def self.capture
+        files = {}
+        begin
+          status, _, _ = Open3.capture3("git", "status", "--porcelain")
+          tracked, _, _ = Open3.capture3("git", "ls-files")
+
+          all_files = Set.new
+          status.strip.each_line do |line|
+            name = line[3..]&.strip
+            all_files.add(name) if name && !name.empty?
+          end
+          tracked.strip.each_line do |file|
+            f = file.strip
+            all_files.add(f) unless f.empty?
+          end
+
+          all_files.each do |file|
+            begin
+              hash, _, _ = Open3.capture3("git", "hash-object", file)
+              files[file] = hash.strip unless hash.strip.empty?
+            rescue StandardError
+              # skip
+            end
+          end
+        rescue StandardError
+          # git not available
+        end
+        new(files)
+      end
+
+      # Return list of files that changed between this snapshot and a later one
+      def modified_since(other)
+        Array.new.tap do |changed|
+          other.files.each do |file, hash|
+            changed << file if files[file] != hash
+          end
+
+          files.each_key do |file|
+            changed << file unless other.files.key?(file)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ralph/helpers.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Ralph
+  module Helpers
+    def strip_ansi(input)
+      input.gsub(/\x1B\[[0-9;]*m/, "")
+    end
+
+    def escape_regex(str)
+      Regexp.escape(str)
+    end
+
+    def format_duration(ms)
+      total_seconds = [0, (ms / 1000).floor].max
+      hours = total_seconds / 3600
+      minutes = (total_seconds % 3600) / 60
+      seconds = total_seconds % 60
+
+      if hours > 0
+        "#{hours}:#{minutes.to_s.rjust(2, '0')}:#{seconds.to_s.rjust(2, '0')}"
+      else
+        "#{minutes}:#{seconds.to_s.rjust(2, '0')}"
+      end
+    end
+
+    def format_duration_long(ms)
+      total_seconds = [0, (ms / 1000).floor].max
+      hours = total_seconds / 3600
+      minutes = (total_seconds % 3600) / 60
+      seconds = total_seconds % 60
+
+      if hours > 0
+        "#{hours}h #{minutes}m #{seconds}s"
+      elsif minutes > 0
+        "#{minutes}m #{seconds}s"
+      else
+        "#{seconds}s"
+      end
+    end
+
+    def format_tool_summary(tool_counts, max_items = 6)
+      if tool_counts.empty?
+        ""
+      else
+        entries = tool_counts.sort_by { |_, v| -v }
+        shown = entries.first(max_items)
+        remaining = entries.length - shown.length
+
+        shown.map { |name, count| "#{name} #{count}" }
+          .tap { |parts| parts << "+#{remaining} more" if remaining > 0 }
+          .then { |parts| parts.join(" • ") }
+      end
+    end
+
+    def check_completion(output, promise)
+      pattern = /<promise>\s*#{escape_regex(promise)}\s*<\/promise>/i
+      output.match?(pattern)
+    end
+
+    # Cross-platform which
+    def which(cmd)
+      exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [""]
+      ENV["PATH"].split(File::PATH_SEPARATOR).each do |path|
+        exts.each do |ext|
+          exe = File.join(path, "#{cmd}#{ext}")
+          return exe if File.executable?(exe) && !File.directory?(exe)
+        end
+      end
+      nil
+    end
+
+    def now_ms
+      (Time.now.to_f * 1000).to_i
+    end
+  end
+end