lux-hammer 0.3.27 → 0.3.29

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbcb0355f0ce770acb1ace879a1567ee1193de1da5ac6e6c32e36faa8f2a48fe
-  data.tar.gz: 8299d3bf2a47844e0e5c01ba73225d43be8aef718ceee3cf9603d0ec85e3e582
+  metadata.gz: 6dab0deb8eba80ec1aac72b16620370af2d80d2528641e9117be71df84e8d416
+  data.tar.gz: 6460bbda170ba18cedf234846e4898f1c6efc48732c81ed122fc6eaa11d237b8
 SHA512:
-  metadata.gz: 6f5a7f793308a5f55e1bdb99ab85ae7aa8b271c92a073f33e1e7130f757395a97071da89a0933958cd89279a7a2004372a71746f1d83c945747ea1cb785f9f75
-  data.tar.gz: b5ee6d077d5b14fd5c448a28ea53e15da59198c067a568bee97193b5352cfea78dd073dff9054af58501453a72cbdae5b0d6c6af5e3e578004b102434a98b29d
+  metadata.gz: c24c74422db1ac9a72b5a03ae4f7d4e56e486c7622be40f5e136c16b9a15b2a04feeb7d2f61cdfdaaeafbc5c3913e71c2f8faf567cac8ea236eaeeadcb7fcb4f
+  data.tar.gz: 823288d67fd112a118c09b3b1dd3599a3b080c5c74fd6e5a35492be182a72fa3fbe82359498e1facb0396b61773b1a51e61dba786284d2bde19426a8e3eddc81

data/.version

@@ -1 +1 @@
-0.3.27
+0.3.29

data/AGENTS.md

@@ -245,12 +245,15 @@ explicit ADR-level discussion. Keys:
 
 ## Help formatting
 
-* Program name in usage lines is computed automatically (invocation path
-  relative to cwd if the bin lives inside cwd, otherwise the basename of
-  `$PROGRAM_NAME`). There is no user-facing override; the auto-detection
-  is the whole API. `Hammer.cli` warms the cache before chdir-ing into
-  the Hammerfile's directory so the resolved name stays relative to the
-  cwd the user invoked from.
+* Program name in usage lines is the invocation as typed: a bare name
+  from PATH (`lux`), or a relative path that is runnable as printed
+  (`bin/foo`). An absolute `$PROGRAM_NAME` (PATH symlink, launchd unit,
+  shim) collapses to its basename - help never shows a full path, and
+  symlinks are never resolved (that once turned a typed `hammer` into
+  `gems/lux-hammer/bin/hammer`). There is no user-facing override; the
+  auto-detection is the whole API. `Hammer.cli` warms the cache before
+  chdir-ing into the Hammerfile's directory so a relative name stays
+  relative to the cwd the user invoked from.
 * `hammer` (no args) routes to the `:default` built-in task, which
   falls through to `print_help(extended: false)` - the brief command
   listing with a top gray `lux-hammer VERSION - <homepage>` banner.
@@ -431,7 +434,8 @@ new code in this gem should show.
 
 ## Testing
 
-* Run: `bundle exec rake test`
+* Run: `bin/hammer test` (the `:test` task in this repo's Hammerfile -
+  there is no Rakefile)
 * Single file: `bundle exec ruby -Ilib -Itest test/parser_test.rb`
 * Single test by name: `... test/parser_test.rb -n test_boolean_via_short_alias`
 * Helper `CaptureIO` in `test/test_helper.rb` swaps `$stdout`/`$stderr`

data/README.md

@@ -1410,7 +1410,7 @@ MyCli.hammer :greet, loud: true
 git clone https://github.com/dux/hammer
 cd lux-hammer
 bundle install
-bundle exec rake test
+bin/hammer test
 ```
 
 Tests live in `test/` and use minitest. Run a single file with

data/lib/lux-hammer.rb

@@ -138,19 +138,14 @@ class Hammer
       @app_desc = text.to_s.rstrip
     end
 
-    # Program name shown in help/usage: the invocation path relative to cwd
-    # if the script lives inside it (e.g. `bin/foo` when invoked from the
-    # project root), otherwise the basename (e.g. `lux` for a globally
-    # installed bin in PATH).
+    # Program name shown in help/usage: the invocation as typed - a bare
+    # name from PATH (`lux`), or a relative path that is runnable as
+    # printed (`bin/foo`). Absolute paths (PATH symlinks, launchd units,
+    # shims) collapse to the basename - help never shows a full path.
     def default_program_name
       prog = $PROGRAM_NAME
-      return File.basename(prog) unless prog.include?('/')
-      # Resolve symlinks on both sides so e.g. macOS `/tmp` -> `/private/tmp`
-      # doesn't cause a false miss when comparing prefixes.
-      abs = File.realpath(prog) rescue File.expand_path(prog)
-      cwd = File.realpath(Dir.pwd) rescue Dir.pwd
-      return abs[(cwd.length + 1)..] if abs.start_with?("#{cwd}/")
-      File.basename(prog)
+      return File.basename(prog) if prog.start_with?('/')
+      prog.sub(%r{\A\./}, '')
     end
 
     # Define a command. Block runs in a CommandBuilder context and must

data/recipes/lib/llm/browser.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# Builds the commands `llm browser:*` hands to Bun. Stagehand is installed
+# globally with `bun add -g`, and Bun resolves imports from NODE_PATH, so the
+# TypeScript under browser/ can live here while the package lives in the
+# global store. Nothing in this module runs Bun or the network - that is what
+# keeps it testable.
+module LlmBrowser
+  GLOBAL_MODULES ||= File.join(Dir.home, '.bun/install/global/node_modules')
+  SCRIPT_DIR     ||= File.join(__dir__, 'browser')
+  RUNNER         ||= File.join(SCRIPT_DIR, 'run.ts')
+  PACKAGES       ||= %w[@browserbasehq/stagehand zod].freeze
+  CHROME         ||= '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+
+  # Who answers Stagehand's act / observe / extract questions. claude and codex
+  # go through their CLIs (subscription, no API key); ollama is Stagehand's own
+  # provider talking to the local daemon.
+  LLMS ||= %w[claude codex ollama].freeze
+
+  # First backend whose name starts with the prefix: `c` is claude, `co` codex,
+  # `o` ollama. No prefix means claude.
+  def self.llm(prefix)
+    return LLMS.first if prefix.nil? || prefix.empty?
+    LLMS.find { |name| name.start_with?(prefix) }
+  end
+
+  def self.env
+    { 'NODE_PATH' => GLOBAL_MODULES }
+  end
+
+  def self.setup_argv
+    ['bun', 'add', '-g', *PACKAGES]
+  end
+
+  def self.run_argv(url, instructions = [], llm: 'claude', headed: false, shot: nil)
+    argv = ['bun', RUNNER, url, *instructions, '--llm', llm]
+    argv << '--headed' if headed
+    argv.push('--shot', shot) if shot
+    argv
+  end
+
+  def self.script_argv(path, extra = [])
+    ['bun', RUNNER, '--script', File.expand_path(path), *extra]
+  end
+
+  def self.installed?(modules: GLOBAL_MODULES)
+    PACKAGES.all? { |pkg| File.directory?(File.join(modules, pkg)) }
+  end
+
+  # What `browser:setup` reports: name => true/false, in the order it prints.
+  def self.check(modules: GLOBAL_MODULES, chrome: CHROME)
+    {
+      'bun'       => command?('bun'),
+      'stagehand' => installed?(modules: modules),
+      'chrome'    => File.exist?(chrome),
+      'claude'    => command?('claude'),
+      'codex'     => command?('codex'),
+      'ollama'    => command?('ollama'),
+    }
+  end
+
+  def self.command?(name)
+    ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).any? { |dir| File.executable?(File.join(dir, name)) }
+  end
+end

data/recipes/lib/llm/launch.rb

@@ -4,7 +4,8 @@ require 'json'
 require 'pathname'
 
 # Builds the command `llm wrap:run` hands to LlmWrap: picks the agent CLI by
-# prefix and maps the generic -c / -f / -a switches to what that CLI takes.
+# prefix and maps the generic -c / -f switches to what that CLI takes. The
+# AGENTS.md chain is injected by default; -b (bare) leaves it out.
 module LlmLaunch
   Launch = Struct.new(:argv, :env, :files)
 
@@ -22,7 +23,7 @@ module LlmLaunch
                     agents: ->(_text, files) { { env: { 'OPENCODE_CONFIG_CONTENT' => { instructions: files }.to_json } } } },
   }.freeze
 
-  # Read AGENTS.md from the git root down on their own; -a only adds the
+  # Read AGENTS.md from the git root down on their own; we only add the
   # files above it for these. Claude reads CLAUDE.md, so it gets the chain.
   NATIVE_AGENTS ||= %w[codex grok opencode].freeze
 
@@ -33,13 +34,13 @@ module LlmLaunch
     TOOLS.keys.find { |name| name.start_with?(prefix) }
   end
 
-  def self.build(tool, extra = [], continue: false, full: false, agents: false, cwd: Dir.pwd, home: Dir.home)
+  def self.build(tool, extra = [], continue: false, full: false, bare: false, cwd: Dir.pwd, home: Dir.home)
     spec = TOOLS.fetch(tool)
     argv = [tool]
     argv.concat(spec[:continue]) if continue
     argv.concat(spec[:full]) if full
 
-    files = agents ? agents_files(tool, cwd: cwd, home: home) : []
+    files = bare ? [] : agents_files(tool, cwd: cwd, home: home)
     env = {}
     if files.any?
       added = spec[:agents].call(agents_text(files), files.map(&:to_s))

data/recipes/lib/llm/usage.rb

@@ -34,6 +34,11 @@ module LlmUsage
   GROK_LOG_PATH   ||= File.expand_path('~/.grok/logs/unified.jsonl')
   GROK_SESSION_GLOB ||= File.expand_path('~/.grok/sessions/**/signals.json')
   GROK_SUMMARY_GLOB ||= File.expand_path('~/.grok/sessions/**/summary.json')
+  GROK_AUTH_PATH  ||= File.expand_path('~/.grok/auth.json')
+  # Same endpoint grok's /usage pane hits. 1.0.13+ strips creditUsagePercent
+  # from the unified log, so the log is only a reset-time fallback.
+  GROK_BILLING_URL ||= 'https://cli-chat-proxy.grok.com/v1/billing?format=credits'
+  GROK_TOKEN_AUTH ||= 'xai-grok-cli'
   CLAUDE_SESSION_GLOB ||= File.expand_path('~/.claude/projects/**/*.jsonl')
   # Written by the statusline hook (~/.claude/statusline-command.sh) from its
   # `rate_limits` input; mtime is the observation time.
@@ -59,7 +64,7 @@ module LlmUsage
       # and caching would freeze the staleness note. Only the API call caches.
       data, note = fetch_claude_usage(period: label, cache: cache, now: now)
       notes << note unless note.nil? || note.empty?
-      rows.concat(parse_claude(data, now: now)) if data
+      rows.concat(parse_claude(data, now: now, period: label)) if data
     end
 
     if wanted.include?(:codex)
@@ -289,7 +294,7 @@ module LlmUsage
     "#{mins}m"
   end
 
-  def parse_claude(data, now: Time.now)
+  def parse_claude(data, now: Time.now, period: nil)
     return [] unless data.is_a?(Hash)
 
     five = data['five_hour']
@@ -324,13 +329,13 @@ module LlmUsage
           month_reset: '-'
         )
       end
-      return rows
+      return rows + claude_scoped_rows(data['limits'], rows, now: now, period: period)
     end
 
     week = data['seven_day']
     return [] unless five.is_a?(Hash) || week.is_a?(Hash)
 
-    [
+    rows = [
       UsageRow.new(
         name: 'Claude',
         session_pct: format_pct(session_pct),
@@ -341,6 +346,36 @@ module LlmUsage
         month_reset: month[:reset]
       )
     ]
+    rows + claude_scoped_rows(data['limits'], rows, now: now, period: period)
+  end
+
+  # Per-model weekly buckets live in `limits` as kind weekly_scoped - Fable has
+  # one, and seven_day_opus/_sonnet read null on the accounts that do. Named off
+  # the API's own display_name, so a model added later needs nothing here; a
+  # scope already carrying its own seven_day_* row is skipped rather than
+  # doubled. A weekly bucket has nothing to say in the month view, where these
+  # would be a row of dashes.
+  def claude_scoped_rows(limits, rows, now: Time.now, period: nil)
+    return [] if period_label(period) == 'month'
+
+    taken = rows.map(&:name)
+
+    Array(limits).filter_map do |limit|
+      next unless limit.is_a?(Hash) && limit['kind'] == 'weekly_scoped'
+
+      name = limit.dig('scope', 'model', 'display_name')
+      next if name.nil? || name.empty? || taken.include?(name)
+
+      UsageRow.new(
+        name: name,
+        session_pct: '-',
+        session_reset: '-',
+        week_pct: format_pct(limit['percent']),
+        week_reset: format_reset_short(limit['resets_at'], now: now),
+        month_pct: '-',
+        month_reset: '-'
+      )
+    end
   end
 
   def parse_codex(data, now: Time.now)
@@ -378,15 +413,15 @@ module LlmUsage
     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' }
+    week_pct = (build && build['usagePercent']) || config['creditUsagePercent']
+    week_reset = config['billingPeriodEnd'] || config.dig('currentPeriod', 'end')
 
     UsageRow.new(
       name: 'Grok',
       session_pct: '-',
       session_reset: '-',
-      week_pct: format_pct(build ? build['usagePercent'] : week_pct),
+      week_pct: format_pct(week_pct),
       week_reset: format_reset_short(week_reset, now: now)
     )
   end
@@ -398,7 +433,7 @@ module LlmUsage
     return fetch_cached(:claude, cache) { fetch_claude_oauth_usage } if period == 'month'
 
     data, note = fetch_claude_snapshot(now: now, path: path)
-    return [data, note] if data
+    return [merge_scoped_limits(data, cache: cache), note] if data
 
     api_data, api_note = fetch_cached(:claude, cache) { fetch_claude_oauth_usage }
     return [api_data, api_note] if api_data
@@ -406,6 +441,18 @@ module LlmUsage
     [nil, [note, api_note].compact.join('; ')]
   end
 
+  # The statusline snapshot carries no per-model windows - Claude Code's
+  # `rate_limits` input is five_hour/seven_day and nothing else - so borrow
+  # `limits` from the API payload. Cached, so this is one call per CACHE_TTL,
+  # and silent when it fails: the snapshot's own numbers are still good.
+  def merge_scoped_limits(data, cache: true)
+    api, = fetch_cached(:claude, cache) { fetch_claude_oauth_usage }
+    limits = api['limits'] if api.is_a?(Hash)
+    return data unless limits
+
+    data.merge('limits' => limits)
+  end
+
   def fetch_claude_snapshot(now: Time.now, path: CLAUDE_LIMITS_PATH)
     snapshot = read_json(path)
     return [nil, 'claude: no local snapshot (statusline writer not installed)'] unless snapshot.is_a?(Hash)
@@ -496,8 +543,59 @@ module LlmUsage
     [nil, note || fallback_note || 'codex: no local rate limits']
   end
 
-  def fetch_grok_usage
-    grok_log_billing_config
+  def fetch_grok_usage(now: Time.now, path: GROK_AUTH_PATH)
+    data, note = fetch_grok_oauth_usage(now: now, path: path)
+    return [data, note] if data
+
+    log_data, log_note = grok_log_billing_config
+    return [log_data, log_note] if log_data
+
+    [nil, [note, log_note].compact.join('; ')]
+  end
+
+  def fetch_grok_oauth_usage(now: Time.now, path: GROK_AUTH_PATH)
+    token = grok_oauth_token(now: now, path: path)
+    return [nil, 'grok: no usable auth token (run `grok login`)'] unless token
+
+    uri = URI(GROK_BILLING_URL)
+    response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 3, read_timeout: 5) do |http|
+      http.get(
+        uri.request_uri,
+        'Authorization' => "Bearer #{token}",
+        'Accept' => 'application/json',
+        'X-XAI-Token-Auth' => GROK_TOKEN_AUTH
+      )
+    end
+    return [nil, "grok: billing API returned #{response.code}"] unless response.is_a?(Net::HTTPSuccess)
+
+    data = JSON.parse(response.body)
+    return [nil, 'grok: billing API returned no config'] unless data.is_a?(Hash) && data['config'].is_a?(Hash)
+
+    [data, nil]
+  rescue JSON::ParserError
+    [nil, 'grok: billing API returned malformed JSON']
+  rescue StandardError => e
+    [nil, "grok: billing API unreachable (#{e.message})"]
+  end
+
+  # grok login writes one Hash per issuer (`https://auth.x.ai::<uuid>`).
+  # An expired token is treated as absent rather than refreshed here.
+  def grok_oauth_token(now: Time.now, path: GROK_AUTH_PATH)
+    creds = read_json(path)
+    return nil unless creds.is_a?(Hash)
+
+    creds.each_value do |entry|
+      next unless entry.is_a?(Hash)
+
+      token = entry['key']
+      next if token.nil? || token.empty?
+
+      expires_at = parse_time(entry['expires_at'])
+      next if expires_at && expires_at <= now
+
+      return token
+    end
+    nil
   end
 
   def codex_app_server_rate_limits
@@ -629,11 +727,12 @@ module LlmUsage
       end
     end
 
+    # A failure is cached too, or an unreachable endpoint costs its timeout on
+    # every run - and the snapshot path that now consults the API is the one
+    # that used to be instant and offline.
     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
+    FileUtils.mkdir_p(CACHE_DIR)
+    File.write(path, JSON.generate('fetched_at' => Time.now.iso8601, 'data' => data, 'note' => note))
     [data, note]
   end
 

data/recipes/llm.rb

@@ -6,6 +6,7 @@ desc <<~TXT
   llm - personal LLM utility CLI
 
   Namespaces:
+    browser  drive a local Chrome with Stagehand, thinking through claude / codex / ollama
     memory   persistent memory store (backs the Claude Code memory plugin)
     plan     apply a /plan bundle - sha1 checked, drift aware
     prompt   token-prefix prompt expander (UserPromptSubmit hook + CLI)
@@ -13,7 +14,7 @@ desc <<~TXT
   Commands:
     usage    subscription limits and per-model token usage
     wrap     run a command with your last two prompts pinned to the screen
-    wrap:run start claude / codex / grok / opencode in wrap, same -c -f -a switches for all
+    wrap:run start claude / codex / grok / opencode in wrap, same -c -f -b switches for all
 TXT
 
 require 'fileutils'
@@ -27,6 +28,7 @@ _llm_root = File.dirname(File.realpath(__FILE__))
 require File.join(_llm_root, 'lib/llm/usage')
 require File.join(_llm_root, 'lib/llm/plan')
 
+BROWSER_LIB  ||= File.join(_llm_root, 'lib/llm/browser')
 STORE        ||= ENV['CLAUDE_MEMORY_STORE'] || File.expand_path('~/dev/ai/memory')
 VALID_TYPES  ||= %w[user feedback project reference].freeze
 
@@ -38,10 +40,15 @@ task :usage do
 
     Default view lists session and weekly windows side by side.
     Local Claude, Codex, and Grok sessions provide calendar day, week, and month token totals.
-    Reads Codex via `codex app-server`; Grok billing + tokens from `~/.grok/logs/unified.jsonl`
-    (inference_done events). Claude 5h/week windows come from the statusline snapshot at
-    `~/.cache/llm/claude-limits.json`, falling back to the OAuth usage API. `month` shows
-    Claude extra-usage credits (API only, and only when you've enabled them).
+    Reads Codex via `codex app-server`. Grok week credits come from the
+    `cli-chat-proxy` billing API (`~/.grok/auth.json`), falling back to
+    `~/.grok/logs/unified.jsonl` for the period end; tokens still sum
+    inference_done events in that log. Claude 5h/week windows come from the
+    statusline snapshot at `~/.cache/llm/claude-limits.json`, falling back to
+    the OAuth usage API. Per-model weekly windows (Fable) get their own row and
+    come from that API either way - the snapshot doesn't carry them. `month`
+    shows Claude extra-usage credits (API only, and only when you've enabled
+    them).
   D
   example 'usage'
   example 'usage month'
@@ -198,22 +205,22 @@ namespace :wrap do
         -c  continue the last session here    claude/grok/opencode -c, codex resume --last
         -f  full permissions, no prompts      --dangerously-skip-permissions, --dangerously-bypass-
                                               approvals-and-sandbox, --always-approve, --auto
-        -a  AGENTS.md from ~ down to cwd      claude --append-system-prompt, codex -c
-                                              developer_instructions, grok --rules, opencode
-                                              inline config
+        -b  bare - no AGENTS.md injection     skips the default below
 
-      codex, grok and opencode read AGENTS.md from the git root down by themselves, so
-      -a only adds the files above the repo for them; claude gets the whole chain.
+      By default every AGENTS.md from ~ down to cwd is handed to the tool: claude
+      --append-system-prompt, codex -c developer_instructions, grok --rules, opencode
+      inline config. codex, grok and opencode read AGENTS.md from the git root down by
+      themselves, so they only get the files above the repo; claude gets the whole chain.
       Anything after `--` is handed to the tool untouched. `~/bin/ai` is this command.
     D
     example 'wrap:run'
     example 'wrap:run g -cf'
-    example 'wrap:run cod -ca'
+    example 'wrap:run cod -cb'
     example 'wrap:run c -- --model opus'
 
     opt :continue, type: :boolean, desc: 'continue the last session in this folder'
     opt :full,     type: :boolean, desc: 'full permissions, no approval prompts'
-    opt :agents,   type: :boolean, desc: 'inject AGENTS.md found from ~ down to cwd'
+    opt :bare,     type: :boolean, desc: 'bare agent - do not inject AGENTS.md'
 
     proc do |opts|
       require File.join(_llm_root, 'lib/llm/wrap')
@@ -225,11 +232,11 @@ namespace :wrap do
              error("unknown tool #{prefix.inspect} - one of #{LlmLaunch::TOOLS.keys.join(', ')}")
       extra = prefix ? args.drop(1) : args
 
-      launch = LlmLaunch.build(tool, extra, continue: opts[:continue], full: opts[:full], agents: opts[:agents])
+      launch = LlmLaunch.build(tool, extra, continue: opts[:continue], full: opts[:full], bare: opts[:bare])
       ENV.update(launch.env)
       say.gray "agents: #{launch.files.map { |f| f.to_s.sub(Dir.home, '~') }.join(', ')}" if launch.files.any?
 
-      flags = %i[continue full agents].select { |k| opts[k] }.map { |k| "--#{k}" }
+      flags = %i[continue full bare].select { |k| opts[k] }.map { |k| "--#{k}" }
       origin = ['llm', 'wrap:run', tool, *flags, '--', *extra]
       # Piped stdout is block-buffered and exec drops the buffer with the banner in it.
       $stdout.flush
@@ -385,6 +392,98 @@ namespace :memory do
   end
 end
 
+namespace :browser do
+  # Helpers live inside the namespace block for the same reason as in
+  # :memory - namespace subclasses do not see the recipe's root class. The
+  # recipe-level `_llm_root` local is out of reach in a def, hence the constant.
+  private
+
+  def browser_lib
+    require BROWSER_LIB
+    LlmBrowser
+  end
+
+  task :setup do
+    desc <<~D
+      Install Stagehand globally with bun and report what the browser tools can use.
+
+      Stagehand (@browserbasehq/stagehand) drives the installed Google Chrome over CDP.
+      Its act / observe / extract calls need a model: claude and codex answer through
+      their CLIs on your subscription, ollama through the local daemon. No API key.
+    D
+    example 'browser:setup'
+
+    proc do
+      lib = browser_lib
+      if lib.installed?
+        say.gray 'stagehand already installed'
+      else
+        say.gray lib.setup_argv.join(' ')
+        error 'bun add failed' unless system(*lib.setup_argv)
+      end
+      lib.check.each do |name, ok|
+        say "#{name.ljust(10)} #{ok ? 'ok' : 'missing'}", (ok ? :green : :red)
+      end
+    end
+  end
+
+  task :run do
+    desc <<~D
+      Open URL in a local Chrome and run act / observe / extract instructions in order.
+
+      Instructions are quoted strings prefixed with act:, observe: or extract:; a bare
+      string is an extract. One JSON object per instruction goes to stdout, progress to
+      stderr. Use it for other people's sites - multi-step flows, structured extraction,
+      forms and logins (--headed). For an app you develop use the chrome-devtools MCP:
+      console, network and perf live there. Nothing here sees inside a canvas.
+
+      Each model call spawns the CLI, so expect 10-20 s per instruction. Nothing is
+      cached locally. BROWSE_CLAUDE_MODEL (sonnet - haiku misses clicks), BROWSE_CODEX_MODEL
+      (codex default - set a small one) and BROWSE_OLLAMA_MODEL (qwen2.5-coder) pick the model.
+    D
+    example 'browser:run https://example.com "extract: the heading and the first link href"'
+    example 'browser:run https://x.com "act: click Sign in" "extract: the form field labels" --headed'
+    example 'browser:run https://x.com "observe: what can be clicked" --llm codex'
+
+    opt :llm,    default: 'claude', positional: false, desc: 'claude | codex | ollama (prefix ok)'
+    opt :headed, type: :boolean, desc: 'visible Chrome window - logins, watching it work'
+    opt :shot,   positional: false, desc: 'save a PNG of the final page to this path'
+
+    proc do |opts|
+      lib = browser_lib
+      url, *instructions = Array(opts[:args])
+      error 'usage: llm browser:run <url> ["act: ..."] ["extract: ..."] [--llm claude|codex|ollama] [--headed] [--shot out.png]' unless url
+      error 'run `llm browser:setup` first' unless lib.installed?
+      llm = lib.llm(opts[:llm]) || error("unknown llm #{opts[:llm].inspect} - one of #{lib::LLMS.join(', ')}")
+
+      $stdout.flush
+      exit(system(lib.env, *lib.run_argv(url, instructions, llm: llm, headed: opts[:headed], shot: opts[:shot])) ? 0 : 1)
+    end
+  end
+
+  task :script do
+    desc <<~D
+      Run an ad-hoc Stagehand script with Bun, Stagehand resolvable from the global store.
+
+      The script imports open() from recipes/lib/llm/browser/lib.ts and gets a ready
+      { stagehand, page, close }. Anything after the file is left in process.argv.
+    D
+    example 'browser:script ./scrape.ts'
+    example 'browser:script ./scrape.ts -- --since 2026-01-01'
+
+    proc do |opts|
+      lib = browser_lib
+      path, *extra = Array(opts[:args])
+      error 'usage: llm browser:script <file.ts> [args...]' unless path
+      error "no such file: #{path}" unless File.file?(File.expand_path(path))
+      error 'run `llm browser:setup` first' unless lib.installed?
+
+      $stdout.flush
+      exec(lib.env, *lib.script_argv(path, extra))
+    end
+  end
+end
+
 namespace :prompt do
   TOKEN_PATTERN        ||= /[a-z0-9_-]+/.freeze
   TOKEN_LINE_RE        ||= /\A(?:\s*:[a-z0-9_-]+)+\s*\z/.freeze
@@ -643,9 +742,10 @@ namespace :prompt do
     D
     opt :claude, type: :boolean, default: false, desc: 'Claude Code hook mode'
     opt :codex,  type: :boolean, default: false, desc: 'Codex hook mode'
+    opt :grok,   type: :boolean, default: false, desc: 'Grok CLI hook mode'
 
     proc do |opts|
-      error '--claude or --codex required' unless opts[:claude] || opts[:codex]
+      error '--claude, --codex or --grok required' unless opts[:claude] || opts[:codex] || opts[:grok]
 
       raw = opts[:stdin].to_s
       prompt = begin

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lux-hammer
 version: !ruby/object:Gem::Version
-  version: 0.3.27
+  version: 0.3.29
 platform: ruby
 authors:
 - Dino Reic
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-08 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -55,6 +55,7 @@ files:
 - "./lib/lux-hammer.rb"
 - "./recipes/deploy.rb"
 - "./recipes/git-helper.rb"
+- "./recipes/lib/llm/browser.rb"
 - "./recipes/lib/llm/launch.rb"
 - "./recipes/lib/llm/plan.rb"
 - "./recipes/lib/llm/usage.rb"