codex_limitless 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 212a5c42dbeafcb4dd6e701576a44b7a16a41fa0a60807dae657d0831b9309e5
+  data.tar.gz: ac5e72f36226a1f4902fbe8eb50654a6315a5254ee0774bcd2413992bee7d730
+SHA512:
+  metadata.gz: b9e3ed810b9e26179ce4b9b55d878a75ee9602868ab6ca58120d8694082b9f1b2d4fa98119a5f5640d02f303837af7ef202b3909a6d112ac1b184136621a535d
+  data.tar.gz: 6f7fb9fe169163eaeec02cbd15a51c6211e4ab75638b54ecc97ad325af7f263b3307daddbb6b62df7de9c8ccad95dd29d26de277cfd7fbb72a170112d55d25dc

data/README.md

@@ -0,0 +1,159 @@
+# codex_limitless
+
+`codex_limitless` provides the `codex-limitless` command for inspecting Codex usage limits from the Codex CLI app-server API.
+
+It can print the current limit snapshot as JSON, wait until the five-hour usage window resets, or automatically wait only when the remaining five-hour percentage is low.
+
+## Installation
+
+Install from RubyGems:
+
+```sh
+gem install codex_limitless
+```
+
+After installation, the `codex-limitless` executable should be available on your shell path:
+
+```sh
+codex-limitless --help
+```
+
+For development, build and install the gem from this checkout:
+
+```sh
+gem build codex_limitless.gemspec
+gem install ./codex_limitless-0.1.0.gem
+```
+
+You can also run the executable directly from the checkout:
+
+```sh
+ruby exe/codex-limitless --help
+```
+
+## Usage
+
+```sh
+codex-limitless -l
+codex-limitless --limits
+
+codex-limitless -w
+codex-limitless --wait
+
+codex-limitless -a
+codex-limitless --auto
+codex-limitless --auto --percentage 20
+
+codex-limitless -h
+codex-limitless --help
+```
+
+### Commands
+
+`-l`, `--limits`
+
+Fetch and print the current Codex limit summary as pretty JSON.
+
+`-w`, `--wait`
+
+Fetch the current Codex limit summary, read `five_hour.resets_at_local`, and poll once per second until the local clock is greater than or equal to that reset time.
+
+`-a`, `--auto`
+
+Fetch the current Codex limit summary and check `five_hour.remaining_percent`. If the remaining percentage is at or below the configured threshold, read `five_hour.resets_at_local` and poll once per second until the local clock is greater than or equal to that reset time. While waiting, re-fetch the limit summary once per minute and update the same status line with the latest five-hour remaining percentage. If the remaining percentage is above the threshold, exit without waiting.
+
+`-h`, `--help`
+
+Print the CLI help text.
+
+`-v`, `--version`
+
+Print the gem version.
+
+## Options
+
+```sh
+codex-limitless --limits --limit-id codex
+codex-limitless --wait --codex-bin /path/to/codex
+codex-limitless --auto --percentage 15
+```
+
+`--limit-id LIMIT_ID`
+
+Inspect a specific Codex rate limit id. Defaults to `codex`.
+
+`--codex-bin PATH`
+
+Use a specific Codex CLI executable. Defaults to `codex`.
+
+`-p`, `--percentage PERCENT`
+
+Remaining percentage threshold for `--auto`. Defaults to `15`.
+
+## AGENTS.md
+
+Add this instruction to the user's `AGENTS.md` file to help prevent long Codex goals from hitting the five-hour limit. At the beginning of every round, `codex-limitless -a` checks the five-hour remaining percentage and waits for the reset only when the remaining percentage is at or below the configured threshold. If it waits, it refreshes the displayed percentage every minute on the same status line.
+
+```md
+- At the beginning of every round, run: "codex-limitless -a". Run it directly with no timeout wrapper. Wait for the command to finish before continuing the round. Ignore output.
+```
+
+## Environment
+
+`CODEX_BIN`
+
+Default Codex CLI executable path when `--codex-bin` is not provided.
+
+`CODEX_LIMIT_ID`
+
+Default limit id when `--limit-id` is not provided.
+
+`CODEX_USAGE_TIMEOUT`
+
+Timeout, in seconds, for Codex app-server requests. Defaults to `30`.
+
+## JSON Output
+
+`--limits` prints an object with the selected limit id, plan details, five-hour window details, weekly window details, and any reset credits returned by Codex.
+
+Example shape:
+
+```json
+{
+  "limit_id": "codex",
+  "limit_name": "Codex",
+  "plan_type": "example",
+  "five_hour": {
+    "window_duration_mins": 300,
+    "used_percent": 80,
+    "remaining_percent": 20,
+    "resets_at": 1781978400,
+    "resets_at_local": "2026-06-20 12:00:00 PM CDT",
+    "resets_at_iso8601": "2026-06-20T12:00:00-05:00"
+  },
+  "weekly": {
+    "window_duration_mins": 10080,
+    "used_percent": 10,
+    "remaining_percent": 90,
+    "resets_at": 1782324000,
+    "resets_at_local": "2026-06-24 12:00:00 PM CDT",
+    "resets_at_iso8601": "2026-06-24T12:00:00-05:00"
+  },
+  "rate_limit_reset_credits": null
+}
+```
+
+## Development
+
+Run basic checks:
+
+```sh
+rake test
+ruby -c lib/codex_limitless.rb
+ruby -c lib/codex_limitless/limits.rb
+ruby -c lib/codex_limitless/cli.rb
+ruby -c exe/codex-limitless
+gem build codex_limitless.gemspec
+```
+
+`rake test` runs the Minitest suite and enforces 100% line coverage for the gem files in `lib/`.

data/exe/codex-limitless

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "codex_limitless/cli"
+
+exit CodexLimitless::CLI.new(ARGV).run

data/lib/codex_limitless/cli.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "time"
+
+require_relative "../codex_limitless"
+
+module CodexLimitless
+  class CLI
+    DEFAULT_PERCENTAGE = 15
+    AUTO_REFRESH_SECONDS = 60
+
+    def initialize(argv, out: $stdout, err: $stderr)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @status_line_width = 0
+    end
+
+    def run
+      options = {
+        codex_bin: ENV.fetch("CODEX_BIN", "codex"),
+        limit_id: ENV.fetch("CODEX_LIMIT_ID", "codex"),
+        percentage: DEFAULT_PERCENTAGE,
+        command: nil
+      }
+      parser = option_parser(options)
+      parser.parse!(@argv)
+
+      case options[:command]
+      when :limits
+        print_limits(options)
+      when :wait
+        wait_for_five_hour_reset(options)
+      when :auto
+        auto_wait_for_five_hour_reset(options)
+      when :version
+        @out.puts VERSION
+      else
+        @out.puts parser
+      end
+
+      0
+    rescue OptionParser::ParseError => e
+      @err.puts "Error: #{e.message}"
+      @err.puts
+      @err.puts option_parser(default_options)
+      1
+    rescue StandardError => e
+      @err.puts "Error: #{e.message}"
+      1
+    end
+
+    private
+
+    def default_options
+      {
+        codex_bin: ENV.fetch("CODEX_BIN", "codex"),
+        limit_id: ENV.fetch("CODEX_LIMIT_ID", "codex"),
+        percentage: DEFAULT_PERCENTAGE,
+        command: nil
+      }
+    end
+
+    def option_parser(options)
+      OptionParser.new do |parser|
+        parser.banner = "Usage: codex-limitless [options]"
+        parser.separator ""
+        parser.separator "Commands:"
+
+        parser.on("-l", "--limits", "Fetch and print Codex limit information as JSON.") do
+          set_command(options, :limits)
+        end
+
+        parser.on("-w", "--wait", "Wait until five_hour.resets_at_local from the fetched JSON.") do
+          set_command(options, :wait)
+        end
+
+        parser.on("-a", "--auto", "Wait when five_hour.remaining_percent is at or below --percentage; refresh every minute.") do
+          set_command(options, :auto)
+        end
+
+        parser.separator ""
+        parser.separator "Options:"
+
+        parser.on("--limit-id LIMIT_ID", "Codex rate limit id to inspect (default: #{options[:limit_id]}).") do |limit_id|
+          options[:limit_id] = limit_id
+        end
+
+        parser.on("--codex-bin PATH", "Codex CLI path (default: #{options[:codex_bin]}).") do |codex_bin|
+          options[:codex_bin] = codex_bin
+        end
+
+        parser.on("-p", "--percentage PERCENT", Integer, "Auto wait threshold percentage (default: #{options[:percentage]}).") do |percentage|
+          raise OptionParser::ParseError, "percentage must be between 0 and 100" unless percentage.between?(0, 100)
+
+          options[:percentage] = percentage
+        end
+
+        parser.on("-v", "--version", "Print the codex_limitless version.") do
+          set_command(options, :version)
+        end
+
+        parser.on("-h", "--help", "Show this help message.") do
+          set_command(options, :help)
+        end
+      end
+    end
+
+    def set_command(options, command)
+      return options[:command] = command if command == :help
+      return if options[:command] == :help
+      return options[:command] = command if options[:command].nil? || options[:command] == command
+
+      raise OptionParser::ParseError, "choose only one command"
+    end
+
+    def print_limits(options)
+      @out.puts JSON.pretty_generate(fetch_summary(options))
+    end
+
+    def wait_for_five_hour_reset(options)
+      summary = fetch_summary(options)
+      wait_until_five_hour_reset(summary)
+    end
+
+    def auto_wait_for_five_hour_reset(options)
+      summary = fetch_summary(options)
+      remaining_percent = five_hour_remaining_percent(summary)
+
+      threshold = options[:percentage]
+      if remaining_percent.to_i > threshold
+        @out.puts "Five-hour remaining is #{remaining_percent}%, above #{threshold}%; not waiting."
+        return
+      end
+
+      current_remaining_percent = remaining_percent
+      status_message = proc do |remaining, reset_text|
+        "Five-hour remaining is #{current_remaining_percent}%, reset at #{reset_text} " \
+          "(#{format_duration(remaining)} remaining)"
+      end
+
+      wait_until_five_hour_reset(
+        summary,
+        refresh_seconds: AUTO_REFRESH_SECONDS,
+        status_message: status_message
+      ) do
+        refreshed = fetch_summary(options)
+        current_remaining_percent = five_hour_remaining_percent(refreshed)
+        refreshed
+      end
+    end
+
+    def wait_until_five_hour_reset(summary, refresh_seconds: nil, status_message: nil, &refresh_summary)
+      reset_text = five_hour_reset_text(summary)
+      reset_at = Time.parse(reset_text)
+      next_refresh_at = refresh_summary ? Time.now + refresh_seconds : nil
+      @out.puts "Waiting until five-hour reset at #{reset_text}." unless status_message
+      print_status_line(status_message.call(seconds_until(reset_at), reset_text)) if status_message
+
+      until Time.now >= reset_at
+        if next_refresh_at && Time.now >= next_refresh_at
+          summary = refresh_summary.call
+          reset_text = five_hour_reset_text(summary)
+          reset_at = Time.parse(reset_text)
+          next_refresh_at = Time.now + refresh_seconds
+        end
+
+        remaining = seconds_until(reset_at)
+        if status_message
+          print_status_line(status_message.call(remaining, reset_text))
+        elsif tty?
+          print_wait_status(remaining)
+        end
+        break if Time.now >= reset_at
+
+        sleep 1
+      end
+
+      status_message ? finish_status_line : (@out.puts if tty?)
+      @out.puts "Five-hour reset reached at #{Time.now.strftime("%Y-%m-%d %I:%M:%S %p %Z")}."
+    end
+
+    def five_hour_remaining_percent(summary)
+      remaining_percent = summary.dig("five_hour", "remaining_percent")
+      raise Error, "five_hour.remaining_percent is missing from the fetched limit JSON" if remaining_percent.nil?
+
+      remaining_percent
+    end
+
+    def five_hour_reset_text(summary)
+      reset_text = summary.dig("five_hour", "resets_at_local")
+      raise Error, "five_hour.resets_at_local is missing from the fetched limit JSON" if reset_text.nil? || reset_text.empty?
+
+      reset_text
+    end
+
+    def fetch_summary(options)
+      Limits.summary(codex_bin: options[:codex_bin], limit_id: options[:limit_id])
+    end
+
+    def print_wait_status(remaining)
+      @out.print "\r#{format_duration(remaining)} remaining"
+      @out.flush
+    end
+
+    def print_status_line(message)
+      padding_width = [@status_line_width - message.length, 0].max
+      prefix = @status_line_width.zero? ? "" : "\r"
+      @out.print "#{prefix}#{message}#{" " * padding_width}"
+      @out.flush
+      @status_line_width = message.length
+    end
+
+    def finish_status_line
+      @out.puts
+      @status_line_width = 0
+    end
+
+    def seconds_until(time)
+      [(time - Time.now).ceil, 0].max
+    end
+
+    def format_duration(seconds)
+      hours = seconds / 3600
+      minutes = (seconds % 3600) / 60
+      secs = seconds % 60
+      format("%02d:%02d:%02d", hours, minutes, secs)
+    end
+
+    def tty?
+      @out.respond_to?(:tty?) && @out.tty?
+    end
+  end
+end

data/lib/codex_limitless/limits.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "time"
+require "timeout"
+
+require_relative "version"
+
+module CodexLimitless
+  unless const_defined?(:Error, false)
+    class Error < StandardError; end
+  end
+
+  class AppServerClient
+    REQUEST_TIMEOUT_SECONDS = Integer(ENV.fetch("CODEX_USAGE_TIMEOUT", "30"))
+
+    def initialize(codex_bin)
+      @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(codex_bin, "app-server", "--stdio")
+      @stderr_reader = Thread.new { @stderr.read }
+      @next_id = 0
+    rescue Errno::ENOENT
+      raise Error, "Could not find `#{codex_bin}`. Set CODEX_BIN to the Codex CLI path."
+    end
+
+    def request(method, params: nil)
+      id = next_request_id
+      payload = { "jsonrpc" => "2.0", "id" => id, "method" => method }
+      payload["params"] = params unless params.nil?
+
+      @stdin.puts(JSON.generate(payload))
+      @stdin.flush
+
+      read_response(id)
+    end
+
+    def close
+      @stdin.close unless @stdin.closed?
+
+      Timeout.timeout(2) { @wait_thread.value }
+    rescue Timeout::Error
+      Process.kill("TERM", @wait_thread.pid)
+      @wait_thread.value
+    ensure
+      @stderr_reader&.join(0.2)
+    end
+
+    private
+
+    def next_request_id
+      @next_id += 1
+    end
+
+    def read_response(id)
+      deadline = Time.now + REQUEST_TIMEOUT_SECONDS
+
+      loop do
+        line = read_line(deadline)
+        message = JSON.parse(line)
+        next unless message["id"] == id
+
+        raise response_error(message) if message["error"]
+
+        return message["result"]
+      end
+    end
+
+    def read_line(deadline)
+      remaining = deadline - Time.now
+      raise Timeout::Error, "Timed out waiting for Codex app-server" if remaining <= 0
+
+      line = Timeout.timeout(remaining) { @stdout.gets }
+      return line if line
+
+      stderr = @stderr_reader&.value.to_s.strip
+      details = stderr.empty? ? "" : ": #{stderr}"
+      raise Error, "Codex app-server exited before responding#{details}"
+    end
+
+    def response_error(message)
+      error = message["error"]
+      code = error["code"] || "unknown"
+      text = error["message"] || error.inspect
+      Error.new("Codex app-server request failed (#{code}): #{text}")
+    end
+  end
+
+  module Limits
+    module_function
+
+    def summary(codex_bin:, limit_id:)
+      rate_limits = fetch_rate_limits(codex_bin)
+      snapshot = select_limit_snapshot(rate_limits, limit_id)
+      raise Error, "No rate limit snapshot found for limit id `#{limit_id}`" unless snapshot
+
+      {
+        "limit_id" => snapshot["limitId"] || limit_id,
+        "limit_name" => snapshot["limitName"],
+        "plan_type" => snapshot["planType"],
+        "five_hour" => window_summary(select_window(snapshot, 300, "primary")),
+        "weekly" => window_summary(select_window(snapshot, 10_080, "secondary")),
+        "rate_limit_reset_credits" => rate_limits["rateLimitResetCredits"]
+      }
+    end
+
+    def fetch_rate_limits(codex_bin)
+      client = AppServerClient.new(codex_bin)
+      client.request(
+        "initialize",
+        params: {
+          "clientInfo" => {
+            "name" => "codex-limitless",
+            "title" => nil,
+            "version" => VERSION
+          },
+          "capabilities" => {
+            "experimentalApi" => true,
+            "requestAttestation" => false,
+            "optOutNotificationMethods" => []
+          }
+        }
+      )
+      client.request("account/rateLimits/read")
+    ensure
+      client&.close
+    end
+
+    def select_limit_snapshot(rate_limits, limit_id)
+      by_id = rate_limits["rateLimitsByLimitId"] || {}
+      by_id[limit_id] || rate_limits["rateLimits"]
+    end
+
+    def select_window(snapshot, duration_mins, fallback_key)
+      windows = [snapshot["primary"], snapshot["secondary"]].compact
+      windows.find { |window| window["windowDurationMins"].to_i == duration_mins } || snapshot[fallback_key]
+    end
+
+    def window_summary(window)
+      used_percent = window&.fetch("usedPercent", nil)
+      remaining_percent = used_percent.nil? ? nil : [[100 - used_percent.to_i, 0].max, 100].min
+      resets_at = window&.fetch("resetsAt", nil)
+
+      {
+        "window_duration_mins" => window&.fetch("windowDurationMins", nil),
+        "used_percent" => used_percent,
+        "remaining_percent" => remaining_percent,
+        "resets_at" => resets_at,
+        "resets_at_local" => resets_at ? Time.at(resets_at).strftime("%Y-%m-%d %I:%M:%S %p %Z") : nil,
+        "resets_at_iso8601" => resets_at ? Time.at(resets_at).iso8601 : nil
+      }
+    end
+  end
+end

data/lib/codex_limitless/version.rb

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

data/lib/codex_limitless.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "codex_limitless/version"
+
+module CodexLimitless
+  class Error < StandardError; end
+end
+
+require_relative "codex_limitless/limits"

metadata

@@ -0,0 +1,44 @@
+--- !ruby/object:Gem::Specification
+name: codex_limitless
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Adam
+bindir: exe
+cert_chain: []
+date: 2026-06-20 00:00:00.000000000 Z
+dependencies: []
+description: A CLI gem that reads Codex app-server rate limit data and waits for five-hour
+  reset times.
+executables:
+- codex-limitless
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/codex-limitless
+- lib/codex_limitless.rb
+- lib/codex_limitless/cli.rb
+- lib/codex_limitless/limits.rb
+- lib/codex_limitless/version.rb
+licenses: []
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Inspect Codex usage limits and wait for reset windows.
+test_files: []