agent_ferrum 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0f2cc1c04153bbcfec18fe9d0e5c68299bf3bac2eed2cff4b7ab4cdc8cd03a5
-  data.tar.gz: e1150457b6023ebb1176a671dbab3e2058e5ec183adab75aee59f4c067acd422
+  metadata.gz: e12be8b95890fc0d62001605462364ac13691dad862b6a39f51d230985c89262
+  data.tar.gz: 361a0f0728979f221669776126d2e6f098149d246c481345631acc0e2a6577b7
 SHA512:
-  metadata.gz: 72d310191f52a7b7aa0a179058c771611b1387c8e87def6d6d2051b32256f8fc48c0f739e14c657f64fe1bd2fc6c8955768f7765a4a5841667e59aa9a55439de
-  data.tar.gz: 49e604f1dad52a548b1180e77186a54bf6b5a8306ca478cb2c5679157d8928df91595ff6087c1d4e8320e62b786120d4c060388ff9a9dd1f892bd9253066778a
+  metadata.gz: 4a3c6893977cd42e7df9f9a1bc7f3a21cf527d2b53ee69de49fd88ae61f964a3cb78b82d20961a690944a7188dad3b1bc0e150eaae854ad8184620fdba07a431
+  data.tar.gz: 015a330a02adbf51ea08b391fec09104a473e6e96d8e0bbb92e4d8842baa2c13867c4796d915a547abec31578f56737fc36d076161a8752b1ee49361f9ebc153

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-02-09
+
+### Added
+
+- **Standalone CLI** -- `agent_ferrum start/snapshot/click/stop` where each command is a separate invocation, ideal for AI agents chaining shell commands
+  - Background daemon holds the Chrome browser process, communicating over a Unix domain socket (`UNIXSocket` + JSON protocol)
+  - Zero external dependencies -- only Ruby stdlib
+  - Session management via `~/.agent_ferrum/` (PID file + socket)
+  - Full command set: `start`, `stop`, `status`, `navigate`, `snapshot`, `tree`, `markdown`, `click`, `fill`, `select`, `hover`, `type`, `screenshot`, `eval`, `back`, `forward`, `refresh`, `stealth`, `wait`
+  - Start options: `--headed`, `--stealth`, `--user-agent`, `--viewport`, `--timeout`, `--browser-path`
+
+### Improved
+
+- **Click reliability** -- elements are scrolled into view (`scrollIntoView({block: 'center'})`) before clicking, fixing issues with elements covered by sticky headers or overlapping content on complex pages
+- **Hover implementation** -- `Node#hover` now works via CDP mouse events (`scrollIntoView` + `find_position` + `mouse.move`), replacing Ferrum's `NotImplementedError`
+
 ## [0.1.0] - 2026-02-09
 
 ### Added
@@ -26,4 +42,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Timezone override** via CDP `Emulation.setTimezoneOverride`
 - **Locale support** via Chrome browser options
 
+[0.2.0]: https://github.com/Alqemist-labs/agent_ferrum/releases/tag/v0.2.0
 [0.1.0]: https://github.com/Alqemist-labs/agent_ferrum/releases/tag/v0.1.0

data/README.md

@@ -39,11 +39,11 @@ Your agent reads a compact snapshot instead of the full DOM. It clicks `@e5` to
 
 Real-world token reduction measured on live pages (February 2026):
 
-| Site | Raw HTML | Snapshot | Reduction |
-|------|----------|----------|-----------|
-| **Hacker News** | ~8,600 tokens | ~4,500 tokens | **47%** |
-| **Wikipedia** (Ruby article) | ~140,000 tokens | ~31,000 tokens | **78%** |
-| **GitHub** (repo page) | ~265,000 tokens | ~22,000 tokens | **92%** |
+| Site                         | Raw HTML        | Snapshot       | Reduction |
+| ---------------------------- | --------------- | -------------- | --------- |
+| **Hacker News**              | ~8,600 tokens   | ~4,500 tokens  | **47%**   |
+| **Wikipedia** (Ruby article) | ~140,000 tokens | ~31,000 tokens | **78%**   |
+| **GitHub** (repo page)       | ~265,000 tokens | ~22,000 tokens | **92%**   |
 
 The heavier the page (scripts, styles, data attributes, hidden elements), the bigger the savings. Simple content-focused pages like HN see ~50% reduction. Rich web apps like GitHub or StackOverflow see 90%+.
 
@@ -58,6 +58,7 @@ The heavier the page (scripts, styles, data attributes, hidden elements), the bi
 - **Smart waiting** -- Poll for CSS/XPath/text/block conditions with configurable timeout and interval
 - **Auto-retry** -- Node actions retry automatically on transient errors (element moving, coordinates not found)
 - **AI-friendly errors** -- Error messages tell the agent what to do next ("Call browser.snapshot to refresh refs")
+- **Standalone CLI** -- `agent_ferrum start/snapshot/click/stop` — each command is a separate invocation, ideal for AI agents chaining shell commands. Zero external dependencies
 
 ## Installation
 
@@ -104,7 +105,7 @@ browser.fill("@e2", "search query")
 # Or use CSS/XPath selectors
 browser.click("button.submit")
 browser.click("//a[@href='/about']")
-browser.fill(css: "input[name='email']", "user@example.com")
+browser.fill({css: "input[name='email']"}, "user@example.com")
 ```
 
 ### 3. Wait for content
@@ -153,6 +154,7 @@ AgentFerrum.configure do |c|
   c.browser_path = nil       # Custom Chrome/Chromium path
   c.user_agent = nil         # Custom user agent
   c.locale = nil             # Browser locale (e.g., "fr-FR")
+  c.timezone = nil           # Timezone override (e.g., "Europe/Paris")
 end
 ```
 
@@ -308,6 +310,84 @@ browser.click("@e7")  # Product link
 browser.quit
 ```
 
+## CLI
+
+AgentFerrum ships with a standalone CLI where each command is a separate invocation. A background daemon holds the browser process, communicating over a Unix domain socket. Zero external dependencies -- only Ruby stdlib (`UNIXSocket`, `JSON`).
+
+```
+CLI invocation                     Daemon (background)
+┌──────────────┐                  ┌───────────────────┐
+│ agent_ferrum │  Unix socket     │ AgentFerrum::     │
+│ snapshot     │ ──────────────>  │ Browser instance  │
+│              │ <──────────────  │ (Chrome headless) │
+└──────────────┘  JSON response   └───────────────────┘
+```
+
+### Quick start
+
+```bash
+agent_ferrum start https://example.com   # Launch browser daemon + navigate
+agent_ferrum snapshot                    # Get accessibility tree + markdown
+agent_ferrum click @e1                   # Click an element by ref
+agent_ferrum screenshot /tmp/page.png    # Take a screenshot
+agent_ferrum stop                        # Stop daemon and browser
+```
+
+### All commands
+
+```
+Session:
+  start [URL] [options]   Start the browser daemon
+    --headed              Visible browser (default: headless)
+    --stealth PROFILE     off / minimal / moderate / maximum
+    --user-agent UA       Custom user agent
+    --viewport WxH        Viewport size (default: 1920x1080)
+    --timeout N           Timeout in seconds (default: 30)
+    --browser-path PATH   Path to Chrome binary
+  stop                    Stop the browser daemon
+  status                  Show browser status
+
+Navigation:
+  navigate URL            Navigate to URL (alias: go)
+  back / forward / refresh
+
+Content:
+  snapshot                Full snapshot (alias: snap)
+  tree                    Accessibility tree only
+  markdown                Page markdown only (alias: md)
+  url                     Current URL
+  title                   Page title
+
+Actions:
+  click TARGET            Click element (ref @e1 or CSS selector)
+  fill TARGET VALUE       Fill an input field
+  select TARGET VALUE     Select a dropdown option
+  hover TARGET            Hover over element
+  type TEXT               Type text via keyboard
+
+Utilities:
+  screenshot [PATH]       Take a screenshot
+  eval JS                 Evaluate JavaScript
+  stealth PROFILE         Change stealth profile
+  wait SELECTOR [TIMEOUT] Wait for element (CSS or XPath)
+```
+
+### Example: AI agent loop
+
+```bash
+agent_ferrum start https://shop.example.com
+# AI reads the page
+SNAP=$(agent_ferrum snapshot)
+# AI decides to search
+agent_ferrum fill @e3 "wireless headphones"
+agent_ferrum click @e4
+agent_ferrum wait ".results"
+# AI reads results
+agent_ferrum snapshot
+# Done
+agent_ferrum stop
+```
+
 ## Development
 
 ```bash

data/bin/agent_ferrum

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "agent_ferrum"
+require_relative "../lib/agent_ferrum/cli"
+
+AgentFerrum::CLI.run(ARGV)

data/lib/agent_ferrum/cli/client.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+
+module AgentFerrum
+  class CLI
+    class Client
+      class ConnectionError < AgentFerrum::Error; end
+      class RemoteError < AgentFerrum::Error; end
+
+      def initialize(socket_path)
+        @socket_path = socket_path
+      end
+
+      def call(method, *args)
+        socket = UNIXSocket.new(@socket_path)
+        request = { method: method, args: args }
+        socket.puts(JSON.generate(request))
+
+        raw = socket.gets("\n")
+        raise ConnectionError, "No response from daemon" unless raw
+
+        response = JSON.parse(raw)
+        raise RemoteError, response["error"] if response["error"]
+
+        response["result"]
+      rescue Errno::ENOENT, Errno::ECONNREFUSED
+        raise ConnectionError, "No browser running. Start one with: agent_ferrum start"
+      ensure
+        socket&.close
+      end
+    end
+  end
+end

data/lib/agent_ferrum/cli/server.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "socket"
+require "json"
+
+module AgentFerrum
+  class CLI
+    class Server
+      def initialize(socket_path, options, ready_write_fd: nil)
+        @socket_path = socket_path
+        @options = options
+        @ready_write_fd = ready_write_fd
+        @running = false
+      end
+
+      def run
+        browser = AgentFerrum::Browser.new(**@options)
+        @service = Service.new(browser)
+        @running = true
+
+        File.delete(@socket_path) if File.exist?(@socket_path)
+        @server = UNIXServer.new(@socket_path)
+        signal_ready
+
+        while @running
+          client = @server.accept
+          handle_connection(client)
+        end
+      rescue StandardError => e
+        signal_error(e)
+        raise
+      ensure
+        @server&.close
+        File.delete(@socket_path) if @socket_path && File.exist?(@socket_path)
+      end
+
+      private
+
+      def handle_connection(client)
+        raw = client.gets("\n")
+        return unless raw
+
+        request = JSON.parse(raw)
+        method = request["method"]
+        args = request["args"] || []
+
+        if method == "stop"
+          client.puts(JSON.generate(result: "Stopped"))
+          client.close
+          @service.stop
+          @running = false
+          return
+        end
+
+        result = @service.public_send(method, *args)
+        client.puts(JSON.generate(result: result))
+      rescue NoMethodError
+        client.puts(JSON.generate(error: "Unknown method: #{method}"))
+      rescue StandardError => e
+        client.puts(JSON.generate(error: e.message))
+      ensure
+        client&.close unless client&.closed?
+      end
+
+      def signal_ready
+        return unless @ready_write_fd
+
+        io = IO.for_fd(@ready_write_fd)
+        io.write("ready")
+        io.close
+      end
+
+      def signal_error(error)
+        return unless @ready_write_fd
+
+        io = IO.for_fd(@ready_write_fd)
+        io.write("error:#{error.message}")
+        io.close
+      rescue StandardError
+        # fd may already be closed
+      end
+    end
+  end
+end

data/lib/agent_ferrum/cli/service.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module AgentFerrum
+  class CLI
+    class Service
+      def initialize(browser)
+        @browser = browser
+      end
+
+      def navigate(url)
+        url = "https://#{url}" unless url.match?(%r{\Ahttps?://})
+        @browser.navigate(url)
+        "Navigated to #{@browser.current_url}"
+      end
+
+      def snapshot
+        @browser.snapshot.to_s
+      end
+
+      def tree
+        @browser.accessibility_tree.to_s
+      end
+
+      def markdown
+        @browser.page_markdown
+      end
+
+      def click(target)
+        url_before = @browser.current_url
+        @browser.click(target)
+        @browser.wait_for_navigation(timeout: 3) rescue nil
+        url_after = @browser.current_url
+        if url_after != url_before
+          "Clicked #{target} → #{url_after}"
+        else
+          "Clicked #{target}"
+        end
+      end
+
+      def fill(target, value)
+        @browser.fill(target, value)
+        "Filled #{target}"
+      end
+
+      def select_option(target, value)
+        @browser.select(target, value)
+        "Selected #{value} in #{target}"
+      end
+
+      def hover(target)
+        @browser.hover(target)
+        "Hovering #{target}"
+      end
+
+      def type_text(text)
+        @browser.type_text(text)
+        "Typed #{text}"
+      end
+
+      def current_url
+        @browser.current_url
+      end
+
+      def title
+        @browser.title
+      end
+
+      def eval_js(expression)
+        @browser.evaluate(expression).inspect
+      end
+
+      def screenshot(path = nil)
+        path ||= "screenshot_#{Time.now.strftime('%Y%m%d_%H%M%S')}.png"
+        @browser.screenshot(path: path)
+        "Screenshot saved to #{path}"
+      end
+
+      def back
+        @browser.back
+        "Back to #{@browser.current_url}"
+      end
+
+      def forward
+        @browser.forward
+        "Forward to #{@browser.current_url}"
+      end
+
+      def refresh
+        @browser.refresh
+        "Refreshed"
+      end
+
+      def stealth(profile)
+        @browser.stealth(profile.to_sym)
+        "Stealth set to #{profile}"
+      end
+
+      def wait(selector, timeout = nil)
+        opts = selector.start_with?("/") ? { xpath: selector } : { css: selector }
+        opts[:timeout] = timeout.to_i if timeout
+        @browser.wait_for(**opts)
+        "Element #{selector} found"
+      end
+
+      def stop
+        @browser.quit
+        "Stopped"
+      end
+    end
+  end
+end

data/lib/agent_ferrum/cli.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require "socket"
+require "fileutils"
+
+require_relative "cli/service"
+require_relative "cli/server"
+require_relative "cli/client"
+
+module AgentFerrum
+  class CLI
+    SESSION_DIR = File.expand_path("~/.agent_ferrum")
+    SESSION_FILE = File.join(SESSION_DIR, "session.json")
+    SOCKET_PATH = File.join(SESSION_DIR, "agent_ferrum.sock")
+
+    def self.run(argv)
+      new(argv).execute
+    end
+
+    def initialize(argv)
+      @argv = argv.dup
+      @command = @argv.shift
+    end
+
+    def execute
+      case @command
+      when "start"   then cmd_start
+      when "stop"    then cmd_stop
+      when "status"  then cmd_status
+      when "version" then puts "agent_ferrum #{AgentFerrum::VERSION}"
+      when "help", nil, "-h", "--help" then print_help
+      else cmd_remote
+      end
+    end
+
+    private
+
+    # --- Commands ---
+
+    def cmd_start
+      cleanup_stale_session
+
+      if session_alive?
+        $stderr.puts "Browser already running (pid: #{read_session["pid"]}). Stop it first with: agent_ferrum stop"
+        exit 1
+      end
+
+      options = parse_start_options
+
+      ready_read, ready_write = IO.pipe
+
+      pid = fork do
+        ready_read.close
+        $stdin.reopen("/dev/null")
+        $stdout.reopen("/dev/null")
+        $stderr.reopen("/dev/null")
+        Process.setsid
+        Server.new(SOCKET_PATH, options, ready_write_fd: ready_write.fileno).run
+      end
+
+      ready_write.close
+      Process.detach(pid)
+      write_session(pid: pid)
+      wait_for_daemon(ready_read)
+
+      url = @argv.shift
+      if url
+        client = connect
+        puts client.call(:navigate, url)
+      end
+
+      puts "Browser started (pid: #{pid})"
+    end
+
+    def cmd_stop
+      unless session_alive?
+        $stderr.puts "No browser running."
+        cleanup_session
+        exit 1
+      end
+
+      begin
+        client = connect
+        client.call(:stop)
+      rescue Client::ConnectionError
+        # Daemon already gone, kill the process
+        session = read_session
+        Process.kill("TERM", session["pid"]) if session
+      rescue StandardError
+        # ignore
+      end
+
+      cleanup_session
+      puts "Browser stopped."
+    end
+
+    def cmd_status
+      if session_alive?
+        session = read_session
+        client = connect
+        url = client.call(:current_url) rescue "unknown"
+        puts "Browser running (pid: #{session["pid"]})"
+        puts "URL: #{url}"
+      else
+        cleanup_session
+        puts "No browser running."
+      end
+    end
+
+    def cmd_remote
+      client = connect
+
+      result = case @command
+               when "navigate", "go"      then client.call(:navigate, @argv[0])
+               when "snapshot", "snap"    then client.call(:snapshot)
+               when "tree"                then client.call(:tree)
+               when "markdown", "md"      then client.call(:markdown)
+               when "click"               then client.call(:click, @argv[0])
+               when "fill"                then client.call(:fill, @argv[0], @argv[1..].join(" "))
+               when "select"              then client.call(:select_option, @argv[0], @argv[1..].join(" "))
+               when "hover"               then client.call(:hover, @argv[0])
+               when "type"                then client.call(:type_text, @argv.join(" "))
+               when "url"                 then client.call(:current_url)
+               when "title"               then client.call(:title)
+               when "eval"                then client.call(:eval_js, @argv.join(" "))
+               when "screenshot"          then client.call(:screenshot, @argv[0])
+               when "back"                then client.call(:back)
+               when "forward"             then client.call(:forward)
+               when "refresh"             then client.call(:refresh)
+               when "stealth"             then client.call(:stealth, @argv[0])
+               when "wait"                then client.call(:wait, @argv[0], @argv[1])
+               else
+                 $stderr.puts "Unknown command: #{@command}. Run 'agent_ferrum help' for usage."
+                 exit 1
+               end
+
+      puts result
+    rescue Client::ConnectionError => e
+      $stderr.puts e.message
+      exit 1
+    rescue Client::RemoteError => e
+      $stderr.puts "Error: #{e.message}"
+      exit 1
+    end
+
+    # --- Session management ---
+
+    def write_session(pid:)
+      FileUtils.mkdir_p(SESSION_DIR)
+      File.write(SESSION_FILE, JSON.generate(pid: pid, socket: SOCKET_PATH))
+    end
+
+    def read_session
+      return nil unless File.exist?(SESSION_FILE)
+
+      JSON.parse(File.read(SESSION_FILE))
+    end
+
+    def cleanup_session
+      File.delete(SESSION_FILE) if File.exist?(SESSION_FILE)
+      File.delete(SOCKET_PATH) if File.exist?(SOCKET_PATH)
+    end
+
+    def session_alive?
+      session = read_session
+      return false unless session
+
+      Process.kill(0, session["pid"])
+      true
+    rescue Errno::ESRCH, Errno::EPERM
+      false
+    end
+
+    def cleanup_stale_session
+      return unless File.exist?(SESSION_FILE) && !session_alive?
+
+      cleanup_session
+    end
+
+    def connect
+      Client.new(SOCKET_PATH)
+    end
+
+    def wait_for_daemon(ready_read, timeout: 30)
+      result = IO.select([ready_read], nil, nil, timeout)
+
+      unless result
+        $stderr.puts "Timeout waiting for browser daemon to start."
+        exit 1
+      end
+
+      message = ready_read.read
+      ready_read.close
+
+      if message.start_with?("error:")
+        $stderr.puts "Failed to start browser: #{message.sub('error:', '')}"
+        exit 1
+      end
+    end
+
+    # --- Option parsing ---
+
+    def parse_start_options
+      options = {}
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: agent_ferrum start [URL] [options]"
+
+        opts.on("--headed", "Run in headed mode (visible browser)") do
+          options[:headless] = false
+        end
+
+        opts.on("--stealth PROFILE", "Stealth profile: off, minimal, moderate, maximum") do |v|
+          options[:stealth] = v.to_sym
+        end
+
+        opts.on("--user-agent UA", "Custom user agent string") do |v|
+          options[:user_agent] = v
+        end
+
+        opts.on("--viewport WxH", "Viewport size (e.g. 1920x1080)") do |v|
+          w, h = v.split("x").map(&:to_i)
+          options[:viewport] = [w, h]
+        end
+
+        opts.on("--timeout N", Integer, "Timeout in seconds") do |v|
+          options[:timeout] = v
+        end
+
+        opts.on("--browser-path PATH", "Path to Chrome binary") do |v|
+          options[:browser_path] = v
+        end
+      end
+
+      parser.parse!(@argv)
+      options
+    end
+
+    # --- Help ---
+
+    def print_help
+      puts <<~HELP
+        agent_ferrum — Browser automation CLI for AI agents
+
+        Usage: agent_ferrum <command> [args] [options]
+
+        Session:
+          start [URL] [options]   Start the browser daemon
+            --headed              Visible browser (default: headless)
+            --stealth PROFILE     off / minimal / moderate / maximum
+            --user-agent UA       Custom user agent
+            --viewport WxH        Viewport size (default: 1920x1080)
+            --timeout N           Timeout in seconds (default: 30)
+            --browser-path PATH   Path to Chrome binary
+          stop                    Stop the browser daemon
+          status                  Show browser status
+
+        Navigation:
+          navigate URL            Navigate to URL (alias: go)
+          back                    Go back
+          forward                 Go forward
+          refresh                 Reload page
+
+        Content:
+          snapshot                Full snapshot: accessibility tree + markdown (alias: snap)
+          tree                    Accessibility tree only
+          markdown                Page markdown only (alias: md)
+          url                     Current URL
+          title                   Page title
+
+        Actions:
+          click TARGET            Click element (ref @e1 or CSS selector)
+          fill TARGET VALUE       Fill an input field
+          select TARGET VALUE     Select a dropdown option
+          hover TARGET            Hover over element
+          type TEXT               Type text via keyboard
+
+        Utilities:
+          screenshot [PATH]       Take a screenshot
+          eval JS                 Evaluate JavaScript
+          stealth PROFILE         Change stealth profile
+          wait SELECTOR [TIMEOUT] Wait for element (CSS or XPath)
+
+        Other:
+          help                    Show this help
+          version                 Show version
+      HELP
+    end
+  end
+end

data/lib/agent_ferrum/node.rb

@@ -9,7 +9,10 @@ module AgentFerrum
     end
 
     def click
-      with_retry { @node.click }
+      with_retry do
+        @node.evaluate("this.scrollIntoView({block: 'center', inline: 'center'})")
+        @node.click
+      end
     end
 
     def fill(value)
@@ -24,7 +27,11 @@ module AgentFerrum
     end
 
     def hover
-      with_retry { @node.hover }
+      with_retry do
+        @node.evaluate("this.scrollIntoView({block: 'center', inline: 'center'})")
+        x, y = @node.find_position
+        @node.page.mouse.move(x: x, y: y)
+      end
     end
 
     def focus

data/lib/agent_ferrum/version.rb

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

data/lib/agent_ferrum.rb

@@ -4,6 +4,8 @@ require "zeitwerk"
 
 loader = Zeitwerk::Loader.for_gem
 loader.ignore("#{__dir__}/agent_ferrum/errors.rb")
+loader.ignore("#{__dir__}/agent_ferrum/cli.rb")
+loader.ignore("#{__dir__}/agent_ferrum/cli")
 loader.setup
 
 require_relative "agent_ferrum/errors"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent_ferrum
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Florian
@@ -69,16 +69,22 @@ description: 'Wraps Ferrum (Chrome headless via CDP) with AI-optimized content e
   accessibility tree with refs, compact markdown snapshots, and stealth mode.'
 email:
 - florian@alqemist.com
-executables: []
+executables:
+- agent_ferrum
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- bin/agent_ferrum
 - lib/agent_ferrum.rb
 - lib/agent_ferrum/browser.rb
 - lib/agent_ferrum/browser/target_resolution.rb
+- lib/agent_ferrum/cli.rb
+- lib/agent_ferrum/cli/client.rb
+- lib/agent_ferrum/cli/server.rb
+- lib/agent_ferrum/cli/service.rb
 - lib/agent_ferrum/configuration.rb
 - lib/agent_ferrum/content/accessibility_tree.rb
 - lib/agent_ferrum/content/markdown_converter.rb