lux-hammer 0.3.15 → 0.3.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a61994d8f82b575a019cfb1171935b334b840cdb5561fcc56e9ba2c141a314d2
-  data.tar.gz: a4d4d730c830b4d30de13dc9e0c27e9cc2fa3902c9297154d4fe81ba5365fe94
+  metadata.gz: b3fcc893fd7391f6b7cdd1694fd243729b3319344727a88bcf8599cdd1d23e6d
+  data.tar.gz: f722dd982a954141f551832b8d742ba317d5aff3430611929dd2a261df550545
 SHA512:
-  metadata.gz: 0e4c0a5f1fbf47550df2929670e647cf7e1e390e7b3aab0b71932dc5f9557295953c39cdf9fafc6ac719d53b94ed14058bd1a2bb32bcaf9bb79ff3b2198fee16
-  data.tar.gz: b0012fd33259c5ea63af2d3ea0040c4a618292042f842dbda523f462d90fbc9138c04217c3c86a7d52fd56a6b650249ab2dd9bb6f070e1f1a24497ab68e6dbe2
+  metadata.gz: 43d2baaf2c2451279d8d9ffb1d78209cff145471781858401efa313c274914795ec03aa078be8b1b083d7ed89bf6fe327b8d592c6e4a25ed6744e1d15b382fe7
+  data.tar.gz: 37e28dc827e1492f3ac5efd346edd2bdafac3bd6d53a6e267f8f4a49937813d46ca514ecf9a2bb0f39ec6b52e8b098ee04f4dc58633948c9bf5e042e3512707c

data/.version

@@ -1 +1 @@
-0.3.15
+0.3.17

data/AGENTS.md

@@ -313,7 +313,7 @@ Task contracts:
   `hammer/cron_web.rb` - no webrick, keep it dependency-free): jobs
   table, per-job log tail, POST run-now, `/json` status. Flags:
   `--port`, `--pass` (HTTP basic auth on every route, any username,
-  constant-time compare; falls back to `HAMMER_CRON_PASS` env),
+  constant-time compare; falls back to `CRON_HTTP_PASS` env),
   `--list` (print jobs + next runs, exit), `--service` (print launchd
   plist / systemd unit, carries `--pass` when set, install hints on
   stderr).

data/README.md

@@ -683,11 +683,11 @@ On a shared machine, protect the UI with HTTP basic auth - useful since
 "run now" executes tasks:
 
 ```sh
-hammer h:cron --pass=secret        # or: HAMMER_CRON_PASS=secret hammer h:cron
+hammer h:cron --pass=secret        # or: CRON_HTTP_PASS=secret hammer h:cron
 curl -u :secret http://127.0.0.1:4267/json   # any username, password checked
 ```
 
-Prefer the `HAMMER_CRON_PASS` env var when other users can read your
+Prefer the `CRON_HTTP_PASS` env var when other users can read your
 process list (`ps` shows flag values). A `--service` unit generated
 while `--pass` is set carries the flag along, so keep that file private.
 Note this is plain HTTP - credentials are encoded, not encrypted; for

data/lib/hammer/builtins.rb

@@ -135,7 +135,7 @@ class Hammer
           example 'h:cron --list'
           example 'h:cron --service > ~/.config/systemd/user/hammer-cron.service'
           opt :port,    type: :integer, default: 4267, desc: 'web UI port (binds 127.0.0.1 only)'
-          opt :pass,    type: :string,  desc: 'HTTP basic-auth password for the web UI (or HAMMER_CRON_PASS env)'
+          opt :pass,    type: :string,  desc: 'HTTP basic-auth password for the web UI (or CRON_HTTP_PASS env)'
           opt :list,    type: :boolean, desc: 'print scheduled jobs + next runs, then exit'
           opt :service, type: :boolean, desc: 'print a launchd plist (macOS) / systemd unit (linux)'
           proc do |opts|
@@ -144,7 +144,7 @@ class Hammer
             end
             require_relative 'cron_server'
             server = Hammer::CronServer.new(self.class.root, port: opts[:port],
-                                            pass: opts[:pass] || ENV['HAMMER_CRON_PASS'])
+                                            pass: opts[:pass] || ENV['CRON_HTTP_PASS'])
             if opts[:service]
               server.print_service_unit
             elsif opts[:list]

data/lib/hammer/cron_server.rb

@@ -265,41 +265,11 @@ class Hammer
     def print_service_unit
       if RUBY_PLATFORM.include?('darwin')
         label = "com.lux-hammer.cron.#{File.basename(@root_dir)}"
-        puts <<~XML
-          <?xml version="1.0" encoding="UTF-8"?>
-          <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-          <plist version="1.0">
-          <dict>
-            <key>Label</key><string>#{label}</string>
-            <key>ProgramArguments</key>
-            <array>
-              <string>#{@hammer_bin}</string>
-              <string>h:cron</string>
-              <string>--port=#{@port}</string>#{@pass ? "\n    <string>--pass=#{@pass}</string>" : ''}
-            </array>
-            <key>WorkingDirectory</key><string>#{@root_dir}</string>
-            <key>RunAtLoad</key><true/>
-            <key>KeepAlive</key><true/>
-            <key>StandardOutPath</key><string>#{@root_dir}/log/hammer/cron-server.log</string>
-            <key>StandardErrorPath</key><string>#{@root_dir}/log/hammer/cron-server.log</string>
-          </dict>
-          </plist>
-        XML
+        puts launchd_service_unit(label)
         warn Shell.paint("# save to ~/Library/LaunchAgents/#{label}.plist, then:", :gray)
         warn Shell.paint("#   launchctl load ~/Library/LaunchAgents/#{label}.plist", :gray)
       else
-        puts <<~UNIT
-          [Unit]
-          Description=hammer h:cron job server (#{File.basename(@root_dir)})
-
-          [Service]
-          ExecStart=#{@hammer_bin} h:cron --port=#{@port}#{" --pass=#{@pass}" if @pass}
-          WorkingDirectory=#{@root_dir}
-          Restart=on-failure
-
-          [Install]
-          WantedBy=default.target
-        UNIT
+        puts systemd_service_unit
         warn Shell.paint('# save to ~/.config/systemd/user/hammer-cron.service, then:', :gray)
         warn Shell.paint('#   systemctl --user enable --now hammer-cron', :gray)
       end
@@ -326,6 +296,71 @@ class Hammer
 
     private
 
+    def launchd_service_unit(label = "com.lux-hammer.cron.#{File.basename(@root_dir)}")
+      args = [@hammer_bin, 'h:cron', "--port=#{@port}"]
+      args << "--pass=#{@pass}" if @pass
+      arguments = args.map { |arg| "    <string>#{xml_escape(arg)}</string>" }.join("\n")
+      log_path = File.join(@root_dir, 'log/hammer/cron-server.log')
+
+      <<~XML
+        <?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+          <key>Label</key><string>#{xml_escape(label)}</string>
+          <key>ProgramArguments</key>
+          <array>
+        #{arguments}
+          </array>
+          <key>WorkingDirectory</key><string>#{xml_escape(@root_dir)}</string>
+          <key>RunAtLoad</key><true/>
+          <key>KeepAlive</key><true/>
+          <key>StandardOutPath</key><string>#{xml_escape(log_path)}</string>
+          <key>StandardErrorPath</key><string>#{xml_escape(log_path)}</string>
+        </dict>
+        </plist>
+      XML
+    end
+
+    def systemd_service_unit
+      args = [@hammer_bin, 'h:cron', "--port=#{@port}"]
+      args << "--pass=#{@pass}" if @pass
+
+      <<~UNIT
+        [Unit]
+        Description=#{systemd_quote("hammer h:cron job server (#{File.basename(@root_dir)})")}
+
+        [Service]
+        ExecStart=#{args.map { |arg| systemd_quote(arg) }.join(' ')}
+        WorkingDirectory=#{systemd_quote(@root_dir)}
+        Restart=on-failure
+
+        [Install]
+        WantedBy=default.target
+      UNIT
+    end
+
+    def xml_escape(value)
+      value.to_s.gsub('&', '&amp;').gsub('<', '&lt;').gsub('>', '&gt;')
+           .gsub('"', '&quot;').gsub("'", '&apos;')
+    end
+
+    def systemd_quote(value)
+      escaped = value.to_s.gsub(/[\x00-\x1f\x7f%$\\"]/) do |char|
+        case char
+        when '%'  then '%%'
+        when '$'  then '$$'
+        when '\\' then '\\\\'
+        when '"'  then '\\"'
+        when "\n" then '\\n'
+        when "\r" then '\\r'
+        when "\t" then '\\t'
+        else format('\\x%02x', char.ord)
+        end
+      end
+      %Q{"#{escaped}"}
+    end
+
     # Refuse to start when the state file points at another live h:cron -
     # two schedulers would double-fire every job. Best-effort (no lock
     # file): kill(0) tells us whether that pid is still alive.

data/recipes/lib/llm/usage.rb

@@ -0,0 +1,507 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'open3'
+require 'shellwords'
+require 'time'
+
+module LlmUsage
+  UsageRow = Struct.new(
+    :name,
+    :session_pct,
+    :session_reset,
+    :week_pct,
+    :week_reset,
+    :month_pct,
+    :month_reset,
+    keyword_init: true
+  )
+
+  CACHE_TTL       ||= 180
+  CACHE_DIR       ||= File.expand_path('~/.cache/llm')
+  GROK_LOG_PATH   ||= File.expand_path('~/.grok/logs/unified.jsonl')
+  CODEX_INIT_RPC  ||= '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"llm-usage","version":"1.0"}}}'
+  CODEX_LIMITS_RPC ||= '{"jsonrpc":"2.0","id":2,"method":"account/rateLimits/read","params":{}}'
+  module_function
+
+  def collect_rows(period: nil, providers: nil, now: Time.now, cache: true)
+    wanted = normalize_providers(providers)
+    rows = []
+    notes = []
+    label = period_label(period)
+
+    if wanted.include?(:claude)
+      data, note = fetch_cached(:claude, cache) { fetch_claude_usage }
+      notes << note if note
+      notes << 'claude: month billing requires OAuth API (not available locally)' if label == 'month'
+      rows.concat(parse_claude(data, now: now)) if data
+    end
+
+    if wanted.include?(:codex)
+      data, note = fetch_cached(:codex, cache) { fetch_codex_usage }
+      notes << note if note
+      row = parse_codex(data, now: now)
+      rows << row if row
+    end
+
+    if wanted.include?(:grok)
+      data, note = fetch_cached(:grok, cache) { fetch_grok_usage }
+      notes << note if note
+      row = parse_grok(data, now: now)
+      rows << row if row
+    end
+
+    [rows, notes, label]
+  end
+
+  def render_table(rows, period: nil)
+    return '' if rows.empty?
+
+    headers = table_headers(period)
+    widths = column_widths(rows, headers)
+    lines = []
+    lines << format_row(headers, widths, align: headers.map { :left })
+    rows.each do |row|
+      lines << format_row(row_cells(row, period), widths)
+    end
+    lines.join("\n")
+  end
+
+  def rows_to_json(rows, period: nil, notes: [])
+    {
+      period: period_label(period),
+      rows: rows.map { |row| row_to_hash(row, period: period) },
+      notes: notes
+    }
+  end
+
+  def format_pct(value)
+    return '-' if value.nil?
+    "#{value.round}%"
+  end
+
+  def format_reset_short(at, now: Time.now)
+    target = parse_time(at)
+    return '-' unless target
+
+    remaining = (target - now).to_i
+    return '-' if remaining <= 0
+
+    days, rem = remaining.divmod(86_400)
+    if days >= 1
+      hours = rem / 3600
+      parts = ["#{days}d"]
+      parts << "#{hours}h" if hours.positive?
+      return parts.join(' ')
+    end
+
+    hours, hour_rem = remaining.divmod(3600)
+    if hours >= 1
+      mins = hour_rem / 60
+      parts = ["#{hours}h"]
+      parts << "#{mins}m" if mins.positive?
+      return parts.join(' ')
+    end
+
+    mins = remaining / 60
+    return '-' if mins <= 0
+
+    "#{mins}m"
+  end
+
+  def parse_claude(data, now: Time.now)
+    return [] unless data.is_a?(Hash)
+
+    five = data['five_hour']
+    session_pct = five&.dig('utilization')
+    session_reset = five&.dig('resets_at')
+    month = claude_month_fields(data['extra_usage'])
+
+    opus = data['seven_day_opus']
+    sonnet = data['seven_day_sonnet']
+    rows = []
+
+    if opus.is_a?(Hash) || sonnet.is_a?(Hash)
+      if opus.is_a?(Hash)
+        rows << UsageRow.new(
+          name: 'Opus',
+          session_pct: format_pct(session_pct),
+          session_reset: format_reset_short(session_reset, now: now),
+          week_pct: format_pct(opus['utilization']),
+          week_reset: format_reset_short(opus['resets_at'], now: now),
+          month_pct: month[:pct],
+          month_reset: month[:reset]
+        )
+      end
+      if sonnet.is_a?(Hash)
+        rows << UsageRow.new(
+          name: 'Sonnet',
+          session_pct: '-',
+          session_reset: '-',
+          week_pct: format_pct(sonnet['utilization']),
+          week_reset: format_reset_short(sonnet['resets_at'], now: now),
+          month_pct: '-',
+          month_reset: '-'
+        )
+      end
+      return rows
+    end
+
+    week = data['seven_day']
+    return [] unless five.is_a?(Hash) || week.is_a?(Hash)
+
+    [
+      UsageRow.new(
+        name: 'Claude',
+        session_pct: format_pct(session_pct),
+        session_reset: format_reset_short(session_reset, now: now),
+        week_pct: format_pct(week&.dig('utilization')),
+        week_reset: format_reset_short(week&.dig('resets_at'), now: now),
+        month_pct: month[:pct],
+        month_reset: month[:reset]
+      )
+    ]
+  end
+
+  def parse_codex(data, now: Time.now)
+    return nil unless data.is_a?(Hash)
+
+    limits = data['rateLimits']
+    limits ||= codex_whitelist_to_rate_limits(data) if data['rate_limit']
+    return nil unless limits
+
+    primary = limits['primary'] || limits['primary_window']
+    secondary = limits['secondary'] || limits['secondary_window']
+    session = nil
+    week = nil
+    [primary, secondary].compact.each do |window|
+      mins = window['windowDurationMins'] || (window['limit_window_seconds'].to_i / 60)
+      if mins <= 360
+        session = window
+      elsif mins >= 1440
+        week = window
+      end
+    end
+    week ||= primary if primary && !session
+    session ||= primary if primary && !week
+
+    UsageRow.new(
+      name: 'Codex',
+      session_pct: format_pct(window_pct(session)),
+      session_reset: format_reset_short(window_reset(session), now: now),
+      week_pct: format_pct(window_pct(week)),
+      week_reset: format_reset_short(window_reset(week), now: now)
+    )
+  end
+
+  def parse_grok(data, now: Time.now)
+    return nil unless data.is_a?(Hash)
+
+    config = data['config'] || data
+    week_pct = config['creditUsagePercent']
+    week_reset = config['billingPeriodEnd'] || config.dig('currentPeriod', 'end')
+    build = Array(config['productUsage']).find { |p| p['product'] == 'GrokBuild' }
+
+    UsageRow.new(
+      name: 'Grok',
+      session_pct: '-',
+      session_reset: '-',
+      week_pct: format_pct(build ? build['usagePercent'] : week_pct),
+      week_reset: format_reset_short(week_reset, now: now)
+    )
+  end
+
+  def fetch_claude_usage
+    [nil, 'claude: no local snapshot']
+  end
+
+  def fetch_codex_usage
+    data, note = codex_app_server_rate_limits
+    return [data, note] if data
+
+    data, fallback_note = codex_session_rate_limits
+    return [data, fallback_note] if data
+
+    [nil, note || fallback_note || 'codex: no local rate limits']
+  end
+
+  def fetch_grok_usage
+    grok_log_billing_config
+  end
+
+  def codex_app_server_rate_limits
+    bin = find_executable('codex')
+    return [nil, 'codex: not in PATH'] unless bin
+
+    pipe = Shellwords.shelljoin([bin, 'app-server'])
+    cmd = "( printf '%s\\n' #{Shellwords.escape(CODEX_INIT_RPC)}; sleep 0.2; " \
+          "printf '%s\\n' #{Shellwords.escape(CODEX_LIMITS_RPC)}; sleep 2 ) | #{pipe}"
+    out, status = Open3.capture2('sh', '-c', cmd)
+    return [nil, 'codex: app-server rate limits unavailable'] unless status.success?
+
+    limits = nil
+    out.each_line do |line|
+      msg = JSON.parse(line)
+      next unless msg['id'] == 2 && msg['result']
+
+      limits = msg.dig('result', 'rateLimits')
+    rescue JSON::ParserError
+      next
+    end
+
+    return [nil, 'codex: app-server rate limits unavailable'] unless limits.is_a?(Hash)
+
+    [{ 'rateLimits' => limits }, nil]
+  rescue Errno::ENOENT
+    [nil, 'codex: not in PATH']
+  rescue StandardError => e
+    [nil, "codex: #{e.message}"]
+  end
+
+  def codex_session_rate_limits
+    pattern = File.expand_path('~/.codex/sessions/**/rollout-*.jsonl')
+    files = Dir.glob(pattern)
+    return [nil, nil] if files.empty?
+
+    newest = files.max_by { |f| File.mtime(f) }
+    limits = nil
+    File.foreach(newest) do |line|
+      next if line.strip.empty?
+
+      data = JSON.parse(line)
+      next unless data.dig('payload', 'type') == 'token_count'
+
+      rl = data.dig('payload', 'rate_limits')
+      limits = rl if rl.is_a?(Hash)
+    rescue JSON::ParserError
+      next
+    end
+    return [nil, nil] unless limits
+
+    mapped = {
+      'rateLimits' => {
+        'primary' => map_codex_session_window(limits['primary']),
+        'secondary' => map_codex_session_window(limits['secondary'])
+      }
+    }
+    date = File.mtime(newest).strftime('%b %-d')
+    [mapped, "codex: from session log (#{date}, may be stale)"]
+  end
+
+  def grok_log_billing_config
+    return [nil, 'grok: no billing log (run grok once)'] unless File.file?(GROK_LOG_PATH)
+
+    entry = reverse_find_jsonl(GROK_LOG_PATH) { |obj| obj['msg'] == 'billing: fetched credits config' }
+    return [nil, 'grok: no billing log (run grok once)'] unless entry
+
+    config = entry.dig('ctx', 'config')
+    return [nil, 'grok: billing log missing config'] unless config.is_a?(Hash)
+
+    note = grok_staleness_note(entry['ts'], now: Time.now)
+    [{ 'config' => config }, note]
+  end
+
+  def reverse_find_jsonl(path)
+    File.readlines(path).reverse_each do |line|
+      next if line.strip.empty?
+
+      obj = JSON.parse(line)
+      return obj if yield(obj)
+    rescue JSON::ParserError
+      next
+    end
+    nil
+  end
+
+  def grok_staleness_note(ts, now: Time.now)
+    return nil unless ts
+
+    logged_at = Time.parse(ts)
+    age = now - logged_at
+    return nil if age < 3600
+
+    format_age_note('grok: billing log from', age)
+  rescue ArgumentError
+    nil
+  end
+
+  def format_age_note(prefix, seconds)
+    if seconds >= 86_400
+      days = (seconds / 86_400).to_i
+      "#{prefix} #{days}d ago"
+    elsif seconds >= 3600
+      hours = (seconds / 3600).to_i
+      "#{prefix} #{hours}h ago"
+    else
+      mins = (seconds / 60).to_i
+      "#{prefix} #{mins}m ago"
+    end
+  end
+
+  def find_executable(cmd)
+    path, status = Open3.capture2('sh', '-c', "command -v #{cmd}")
+    path = path.strip
+    return nil unless status.success? && !path.empty? && File.executable?(path)
+
+    path
+  end
+
+  def fetch_cached(provider, use_cache)
+    return yield unless use_cache
+
+    path = cache_path(provider)
+    if File.file?(path)
+      age = Time.now - File.mtime(path)
+      if age < CACHE_TTL
+        payload = read_json(path)
+        return [payload['data'], payload['note']] if payload && payload.key?('data')
+      end
+    end
+
+    data, note = yield
+    if data
+      FileUtils.mkdir_p(CACHE_DIR)
+      File.write(path, JSON.generate('fetched_at' => Time.now.iso8601, 'data' => data, 'note' => note))
+    end
+    [data, note]
+  end
+
+  def cache_path(provider)
+    File.join(CACHE_DIR, "usage-#{provider}.json")
+  end
+
+  def normalize_providers(providers)
+    list = Array(providers).map(&:to_s).map(&:downcase).reject(&:empty?)
+    return %i[claude codex grok] if list.empty?
+
+    valid = %w[claude codex grok]
+    bad = list - valid
+    raise Hammer::Error, "unknown provider(s): #{bad.join(', ')} (valid: #{valid.join(', ')})" unless bad.empty?
+
+    list.map(&:to_sym)
+  end
+
+  def period_label(period)
+    case period.to_s.downcase
+    when '', 'default', 'session', 'week' then 'default'
+    when 'month' then 'month'
+    else
+      raise Hammer::Error, "unknown period: #{period} (valid: week, month)"
+    end
+  end
+
+  def table_headers(period)
+    if period_label(period) == 'month'
+      %w[Name month\ util month\ reset]
+    else
+      %w[Name session\ util session\ reset week\ util week\ reset]
+    end
+  end
+
+  def row_cells(row, period)
+    if period_label(period) == 'month'
+      [row.name, row.month_pct || '-', row.month_reset || '-']
+    else
+      [row.name, row.session_pct, row.session_reset, row.week_pct, row.week_reset]
+    end
+  end
+
+  def row_to_hash(row, period: nil)
+    if period_label(period) == 'month'
+      { name: row.name, month_util: row.month_pct, month_reset: row.month_reset }
+    else
+      {
+        name: row.name,
+        session_util: row.session_pct,
+        session_reset: row.session_reset,
+        week_util: row.week_pct,
+        week_reset: row.week_reset
+      }
+    end
+  end
+
+  def column_widths(rows, headers)
+    cells = [headers] + rows.map { |row| row_cells(row, nil) }
+    headers.each_index.map do |i|
+      cells.map { |line| line[i].to_s.length }.max
+    end
+  end
+
+  def format_row(cells, widths, align: nil)
+    align ||= [:left] + [:right] * (cells.length - 1)
+    cells.each_with_index.map do |cell, i|
+      text = cell.to_s
+      if align[i] == :right
+        text.rjust(widths[i])
+      else
+        text.ljust(widths[i])
+      end
+    end.join('  ')
+  end
+
+  def parse_time(at)
+    case at
+    when nil then nil
+    when Numeric then Time.at(at.to_i)
+    when String
+      return Time.at(at.to_i) if at.match?(/\A\d+\z/)
+      Time.parse(at)
+    else
+      nil
+    end
+  rescue ArgumentError
+    nil
+  end
+
+  def window_pct(window)
+    return nil unless window.is_a?(Hash)
+    window['usedPercent'] || window['used_percent']
+  end
+
+  def window_reset(window)
+    return nil unless window.is_a?(Hash)
+    window['resetsAt'] || window['reset_at']
+  end
+
+  def map_codex_window(window)
+    return nil unless window.is_a?(Hash)
+    {
+      'used_percent' => window['used_percent'],
+      'limit_window_seconds' => window['limit_window_seconds'],
+      'reset_at' => window['reset_at']
+    }
+  end
+
+  def map_codex_session_window(window)
+    return nil unless window.is_a?(Hash)
+    {
+      'used_percent' => window['used_percent'],
+      'windowDurationMins' => window['window_minutes'],
+      'resetsAt' => window['resets_at']
+    }
+  end
+
+  def claude_month_fields(extra)
+    return { pct: '-', reset: '-' } unless extra.is_a?(Hash) && extra['is_enabled']
+
+    {
+      pct: format_pct(extra['utilization']),
+      reset: '-'
+    }
+  end
+
+  def codex_whitelist_to_rate_limits(data)
+    {
+      'primary' => map_codex_window(data.dig('rate_limit', 'primary_window')),
+      'secondary' => map_codex_window(data.dig('rate_limit', 'secondary_window'))
+    }
+  end
+
+  def read_json(path)
+    return nil unless path && File.file?(path)
+    JSON.parse(File.read(path))
+  rescue JSON::ParserError
+    nil
+  end
+end

data/recipes/llm.rb

@@ -8,6 +8,9 @@ desc <<~TXT
   Namespaces:
     memory   persistent memory store (backs the Claude Code memory plugin)
     prompt   token-prefix prompt expander (UserPromptSubmit hook + CLI)
+
+  Commands:
+    usage    Claude, Codex, and Grok subscription usage (session + week table)
 TXT
 
 require 'fileutils'
@@ -15,11 +18,50 @@ require 'json'
 require 'pathname'
 require 'set'
 
+_llm_root = File.dirname(Hammer::Recipe.path('llm') || File.join(Hammer::Recipe::GEM_DIR, 'llm.rb'))
+require File.join(_llm_root, 'lib/llm/usage')
+
 STORE        ||= ENV['CLAUDE_MEMORY_STORE'] || File.expand_path('~/dev/skills/memory')
 VALID_TYPES  ||= %w[user feedback project reference].freeze
 
 FileUtils.mkdir_p(STORE)
 
+task :usage do
+  desc <<~D
+    Show subscription usage for Claude, Codex, and Grok in one table.
+
+    Default view lists session and weekly windows side by side.
+    Reads Codex via `codex app-server`, Grok from `~/.grok/logs/unified.jsonl`.
+    Claude has no local snapshot. Pass `month` for Claude extra-usage when enabled.
+  D
+  example 'llm usage'
+  example 'llm usage month'
+  example 'llm usage --json'
+  example 'llm usage --provider grok'
+
+  opt :json,     type: :boolean, default: false, desc: 'emit JSON'
+  opt :provider, desc: 'single provider (claude, codex, grok)'
+
+  proc do |opts|
+    period = opts[:args].first
+    providers = opts[:provider] ? [opts[:provider]] : nil
+    rows, notes, = LlmUsage.collect_rows(period: period, providers: providers)
+
+    if rows.empty?
+      notes.each { |note| say note, :yellow }
+      error 'no usage data (sign in to Claude, Codex, or Grok first)' if notes.empty?
+      error 'no usage data available'
+    end
+
+    if opts[:json]
+      puts JSON.generate(LlmUsage.rows_to_json(rows, period: period, notes: notes))
+    else
+      say LlmUsage.render_table(rows, period: period)
+      notes.each { |note| say note, :gray }
+    end
+  end
+end
+
 namespace :memory do
   # Helpers are defined inside the namespace block (class_eval'd on the
   # namespace's anonymous Hammer subclass) so the task procs reach them.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.15
+  version: 0.3.17
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-11 00:00:00.000000000 Z
+date: 2026-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -63,6 +63,7 @@ files:
 - "./recipes/lib/deploy/manifest.rb"
 - "./recipes/lib/deploy/ssh.rb"
 - "./recipes/lib/deploy/template.rb"
+- "./recipes/lib/llm/usage.rb"
 - "./recipes/llm.rb"
 - "./recipes/srt.rb"
 - bin/hammer