agent-loop 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 915989d4e9cf002298cd6b27243146113f0b04cab3e759c55e6c5b333cf1b997
+  data.tar.gz: 80cbf0ccdbc645a60af30dc7ab22cdc0f8c54957e0ec8829681a8ab8160da1a4
+SHA512:
+  metadata.gz: 9dab320aafd99d76c6f4204bb8e7ec4063c720c33d341f7f78423bdd766c0ab1892b21e0c4950a545738cf587067db94d3a399b386b0a49fbc9f8796e13e1ded
+  data.tar.gz: '049da19643c2b415967185fb67ed782ef04735e547bde74a8581620842a8aba03b88cf2e83377d582b8ab2465fab2c87cac799ff3562361941303cd483055f1e'

data/Prompt.md

@@ -0,0 +1,15 @@
+# Instructions
+
+You are to execute the following steps:
+1. Take the first unchecked task from the list below
+2. Do the work in that task
+3. Update this Prompt.md and check that task off on the list
+4. Write "done" to the file `${TASK_FILE}`
+
+If there are no unchecked tasks remaining, write the text "done" to the file `${STATUS_FILE}` using the Bash tool.
+
+## Tasks
+- [ ] Make a file
+- [ ] Put a "Hello World" program in the file made from the previous task
+- [ ] Run the program
+

data/Readme.md

@@ -0,0 +1,32 @@
+# Agent Loop
+
+A command line utility that runs Claude Code CLI in a loop to work tasks one by one from a Prompt.md
+
+## Project Goals
+1. Can be cloned down and run with minimal setup
+1. This project can work in existing repos with minimal configuration
+1. Zero dependencies other than Claude Code and bash
+
+## Install
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/BrandonMathis/agent-loop/main/install.sh)
+```
+
+This downloads `start_agent_loop.sh` and `Prompt.md` into your current directory.
+
+## Usage
+1. Edit `Prompt.md` with your tasks
+2. Run agent loop script
+
+**Human Assisted**
+```
+./start_agent_loop.sh
+```
+
+**Fully Automated**
+```
+./start_agent_loop.sh --dangerous
+``` 
+
+When running this script with the `--dangerous` flag you are giving claude code cli [full permission to do whatever it pleases via the `--dangerously-skip-permissions`](https://code.claude.com/docs/en/settings#permission-settings) flag. Please proceed with caution and consider all possible risks.

data/agent-loop.gemspec

@@ -0,0 +1,19 @@
+require_relative "lib/agent_loop/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "agent-loop"
+  spec.version       = AgentLoop::VERSION
+  spec.authors       = ["Brandon Mathis"]
+  spec.summary       = "Run Claude Code CLI in a loop, working tasks one by one from a Prompt.md"
+  spec.homepage      = "https://github.com/BrandonMathis/agent-loop"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.files         = Dir["lib/**/*.rb", "bin/*", "*.md", "*.gemspec"]
+  spec.bindir        = "bin"
+  spec.executables   = ["agent-loop"]
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "thor", "~> 1.2"
+end

data/bin/agent-loop

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "agent_loop"
+
+AgentLoop::CLI.start(ARGV)

data/lib/agent_loop/cli.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "runner"
+
+module AgentLoop
+  class CLI < Thor
+    desc "start", "Run the agent loop in the current directory"
+    long_desc <<~LONGDESC
+      Reads Prompt.md (or the file given by --prompt), expands ${STATUS_FILE}
+      and ${TASK_FILE} placeholders, and runs `claude` in a loop until the
+      agent writes "done" to the status file.
+    LONGDESC
+
+    method_option :dangerous,
+                  type:    :boolean,
+                  default: false,
+                  desc:    "Pass --dangerously-skip-permissions to claude"
+
+    method_option :prompt,
+                  type:    :string,
+                  default: "Prompt.md",
+                  aliases: "-p",
+                  desc:    "Path to the prompt template file"
+
+    method_option :poll_interval,
+                  type:    :numeric,
+                  default: 0.5,
+                  aliases: "-i",
+                  desc:    "Seconds between watcher poll checks"
+
+    def start
+      Runner.new(options).run
+    end
+
+    default_task :start
+
+    def self.exit_on_failure?
+      true
+    end
+  end
+end

data/lib/agent_loop/runner.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require_relative "watcher"
+
+module AgentLoop
+  class Runner
+    DONE = "done"
+
+    def initialize(options = {})
+      @dangerous     = options[:dangerous]     || options["dangerous"]     || false
+      @prompt_file   = options[:prompt]        || options["prompt"]        || "Prompt.md"
+      @poll_interval = (options[:poll_interval] || options["poll_interval"] || 0.5).to_f
+    end
+
+    def run
+      setup_temp_files
+      trap_signals
+
+      loop do
+        break if status_done?
+
+        abort "Error: #{@prompt_file} not found." unless File.exist?(@prompt_file)
+
+        FileUtils.rm_f(@status_file)
+        puts "Running agent loop iteration..."
+
+        run_iteration(expand_prompt)
+
+        break if status_done?
+      end
+
+      puts "AGENT_STATUS is 'done'. Stopping loop."
+    end
+
+    private
+
+    def setup_temp_files
+      loop_id      = Digest::SHA1.hexdigest("#{Dir.pwd}\n")[0, 8]
+      @status_file = "/tmp/AGENT_STATUS_#{loop_id}"
+      @task_file   = "/tmp/AGENT_TASK_#{loop_id}"
+      FileUtils.rm_f([@status_file, @task_file])
+    end
+
+    def trap_signals
+      handler = proc do
+        puts "Interrupted. Stopping loop."
+        exit 1
+      end
+      trap("INT",  handler)
+      trap("TERM", handler)
+    end
+
+    def expand_prompt
+      File.read(@prompt_file)
+          .gsub("${STATUS_FILE}", @status_file)
+          .gsub("${TASK_FILE}",   @task_file)
+    end
+
+    def run_iteration(prompt_text)
+      stdin_r, stdin_w = IO.pipe
+      stdin_w.write(prompt_text)
+      stdin_w.close
+
+      flags     = @dangerous ? ["--dangerously-skip-permissions"] : []
+      agent_pid = spawn("claude", *flags, in: stdin_r)
+      stdin_r.close
+
+      watcher = Watcher.new(
+        status_file:   @status_file,
+        task_file:     @task_file,
+        poll_interval: @poll_interval
+      ).start(agent_pid) do |signal, pid|
+        case signal
+        when :task_done
+          puts "AGENT_TASK is 'done'. Killing agent (PID #{pid})."
+        when :status_done
+          puts "AGENT_STATUS is 'done'. Killing agent (PID #{pid})."
+        end
+        kill_process(pid)
+      end
+
+      _, status = Process.waitpid2(agent_pid)
+      watcher.stop
+
+      if status.exitstatus == 0 && !status_done?
+        puts "Agent exited cleanly. Stopping loop."
+        exit 0
+      end
+    end
+
+    def kill_process(pid)
+      Process.kill("TERM", pid)
+    rescue Errno::ESRCH
+      # Process already gone
+    end
+
+    def status_done?
+      File.exist?(@status_file) && File.read(@status_file).strip == DONE
+    end
+  end
+end

data/lib/agent_loop/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentLoop
+  VERSION = "0.1.0"
+end

data/lib/agent_loop/watcher.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AgentLoop
+  class Watcher
+    DONE = "done"
+
+    def initialize(status_file:, task_file:, poll_interval: 0.5)
+      @status_file   = status_file
+      @task_file     = task_file
+      @poll_interval = poll_interval
+      @thread        = nil
+      @stop          = false
+    end
+
+    # Starts the background watcher thread. Yields :task_done or :status_done
+    # to the block when a signal file is detected.
+    def start(agent_pid, &callback)
+      @stop = false
+      @thread = Thread.new do
+        loop do
+          break if @stop
+
+          if done?(@task_file)
+            File.delete(@task_file) if File.exist?(@task_file)
+            callback.call(:task_done, agent_pid)
+            break
+          end
+
+          if done?(@status_file)
+            callback.call(:status_done, agent_pid)
+            break
+          end
+
+          sleep @poll_interval
+        end
+      end
+      self
+    end
+
+    def stop
+      @stop = true
+      @thread&.join(2)
+    end
+
+    def join
+      @thread&.join
+    end
+
+    private
+
+    def done?(path)
+      File.exist?(path) && File.read(path).strip == DONE
+    end
+  end
+end

data/lib/agent_loop.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "agent_loop/version"
+require_relative "agent_loop/runner"
+require_relative "agent_loop/cli"

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: agent-loop
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brandon Mathis
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description:
+email:
+executables:
+- agent-loop
+extensions: []
+extra_rdoc_files: []
+files:
+- Prompt.md
+- Readme.md
+- agent-loop.gemspec
+- bin/agent-loop
+- lib/agent_loop.rb
+- lib/agent_loop/cli.rb
+- lib/agent_loop/runner.rb
+- lib/agent_loop/version.rb
+- lib/agent_loop/watcher.rb
+homepage: https://github.com/BrandonMathis/agent-loop
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Run Claude Code CLI in a loop, working tasks one by one from a Prompt.md
+test_files: []