iterm2_ruby 0.2.0

data/lib/iterm2/session.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ITerm2
+  class Session
+    attr_reader :client, :id, :window_id, :tab_id, :title
+
+    def initialize(client:, id:, window_id: nil, tab_id: nil, title: nil)
+      @client = client
+      @id = id
+      @window_id = window_id
+      @tab_id = tab_id
+      @title = title
+    end
+
+    def activate(select_tab: true, order_window_front: true)
+      client.activate_session(id, select_tab: select_tab, order_window_front: order_window_front)
+    end
+
+    def send_text(text, suppress_broadcast: false)
+      client.send_text(id, text, suppress_broadcast: suppress_broadcast)
+    end
+
+    def read_screen(trailing_lines: nil)
+      client.read_screen(id, trailing_lines: trailing_lines)
+    end
+
+    def info
+      client.session_info(id)
+    end
+
+    def get_variable(name)
+      client.get_variable(name, session_id: id)
+    end
+
+    def to_h
+      {
+        window_id: window_id,
+        tab_id: tab_id,
+        session_id: id,
+        title: title
+      }
+    end
+  end
+end

data/lib/iterm2/tab.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module ITerm2
+  class Tab
+    attr_reader :client, :id, :window_id
+
+    def initialize(client:, id:, window_id:)
+      @client = client
+      @id = id
+      @window_id = window_id
+    end
+
+    def activate(order_window_front: true)
+      client.activate_tab(id, order_window_front: order_window_front)
+    end
+
+    def sessions
+      client.topology
+            .select { |s| s[:tab_id] == id && s[:window_id] == window_id }
+            .map { |s| Session.new(client: client, id: s[:session_id], window_id: s[:window_id], tab_id: s[:tab_id], title: s[:title]) }
+    end
+
+    def primary_session
+      sessions.first
+    end
+
+    def close(force: false)
+      client.close_tab(id, force: force)
+    end
+
+    def to_h
+      {
+        window_id: window_id,
+        tab_id: id,
+        sessions: sessions.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/iterm2/version.rb

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

data/lib/iterm2/window.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ITerm2
+  class Window
+    attr_reader :client, :id
+
+    def initialize(client:, id:)
+      @client = client
+      @id = id
+    end
+
+    def activate
+      client.activate_window(id)
+    end
+
+    def tabs
+      tab_ids = client.topology.select { |s| s[:window_id] == id }.map { |s| s[:tab_id] }.uniq
+      tab_ids.map { |tab_id| Tab.new(client: client, id: tab_id, window_id: id) }
+    end
+
+    def create_tab(profile_name: nil)
+      result = client.create_tab(window_id: id, profile_name: profile_name)
+      Session.new(client: client, id: result[:session_id], window_id: result[:window_id], tab_id: result[:tab_id])
+    end
+
+    def to_h
+      {
+        window_id: id,
+        tabs: tabs.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/iterm2.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "iterm2/version"
+require_relative "iterm2/proto/api_pb"
+require_relative "iterm2/connection"
+require_relative "iterm2/client"
+require_relative "iterm2/window"
+require_relative "iterm2/tab"
+require_relative "iterm2/session"
+
+module ITerm2
+  # Alias the protoc-generated Iterm2 module for internal use
+  Proto = ::Iterm2
+
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class AuthError < Error; end
+  class RPCError < Error; end
+  class NotFoundError < RPCError; end
+  class SubscriptionError < Error; end
+
+  # Convenience: open connection, yield client, close
+  def self.connect(app_name: "iterm2_ruby")
+    client = Client.new(app_name: app_name)
+    return client unless block_given?
+
+    yield client
+  ensure
+    client&.close if block_given?
+  end
+
+  # One-shot: list all sessions
+  def self.list_sessions
+    connect { |c| c.list_sessions }
+  end
+
+  # One-shot: flat topology
+  def self.topology
+    connect { |c| c.topology }
+  end
+
+  # One-shot: send text to a session
+  def self.send_text(session_id, text)
+    connect { |c| c.send_text(session_id, text) }
+  end
+
+  # One-shot: read screen contents
+  def self.read_screen(session_id, trailing_lines: nil)
+    connect { |c| c.read_screen(session_id, trailing_lines: trailing_lines) }
+  end
+
+  # One-shot: raise by title pattern
+  def self.raise_by_title(pattern)
+    connect { |c| c.raise_by_title(pattern) }
+  end
+
+  # One-shot: activate a session
+  def self.activate_session(session_id)
+    connect { |c| c.activate_session(session_id) }
+  end
+
+  # One-shot: enriched topology (with cwd, pid, tty)
+  def self.topology_enriched
+    connect { |c| c.topology_enriched }
+  end
+
+  # One-shot: raise by cwd pattern
+  def self.raise_by_cwd(pattern)
+    connect { |c| c.raise_by_cwd(pattern) }
+  end
+
+  # One-shot: session info (tty, pid, cwd, name, job)
+  def self.session_info(session_id)
+    connect { |c| c.session_info(session_id) }
+  end
+
+  # One-shot: get variable
+  def self.get_variable(name, **scope)
+    connect { |c| c.get_variable(name, **scope) }
+  end
+
+  # One-shot: current focus state
+  def self.focus
+    connect { |c| c.focus }
+  end
+
+  # One-shot: prompt state for a session
+  def self.get_prompt(session_id)
+    connect { |c| c.get_prompt(session_id) }
+  end
+
+  # One-shot: get profile properties for a session
+  def self.get_profile_property(session_id, *keys)
+    connect { |c| c.get_profile_property(session_id, *keys) }
+  end
+
+  # One-shot: list all profiles
+  def self.list_profiles(properties: nil, guids: nil)
+    connect { |c| c.list_profiles(properties: properties, guids: guids) }
+  end
+
+  # One-shot: inject data into a session
+  def self.inject(session_id, data)
+    connect { |c| c.inject(session_id, data) }
+  end
+end

data/llms.txt

@@ -0,0 +1,114 @@
+# iterm2_ruby
+
+> Ruby gem + CLI for controlling iTerm2 via its native WebSocket + Protobuf API. ~20x faster than osascript/JXA, no focus stealing, real-time event notifications.
+
+## Install
+
+```bash
+gem install iterm2_ruby
+```
+
+Requires macOS, iTerm2 with API enabled (Preferences > General > Magic > Enable Python API), Ruby >= 3.1.
+
+## Usage: One-Shot (connect, run, disconnect)
+
+```ruby
+require "iterm2"
+
+sessions = ITerm2.topology
+ITerm2.send_text(session_id, "ls -la\n")
+screen = ITerm2.read_screen(session_id)
+ITerm2.raise_by_title("my-project")
+```
+
+## Usage: Persistent Client (reuse connection)
+
+```ruby
+ITerm2.connect do |client|
+  sessions = client.topology
+  client.send_text(sessions.first[:session_id], "make test\n")
+  client.on_focus_change { |e| puts e.inspect }
+  sleep  # keep alive for notifications
+end
+```
+
+## Core Methods
+
+### `client.topology` -> Array<Hash>
+Flat list of all sessions: `[{window_id:, tab_id:, session_id:, title:}, ...]`
+
+### `client.send_text(session_id, text, suppress_broadcast: false)` -> true/false
+Send text to a session. Does NOT auto-append `\n` -- include it to execute a command.
+
+### `client.read_screen(session_id, trailing_lines: nil)` -> Hash
+Read visible screen. Returns `{lines: ["line1", ...], cursor: {x:, y:}}`.
+Pass `trailing_lines: N` for scrollback.
+
+### `client.activate_session(session_id)` -> true/false
+Raise and focus a session (selects tab, brings window to front).
+
+### `client.raise_by_title(pattern)` -> true/false
+Find first session matching title (case-insensitive regex) and activate it.
+Raises `NotFoundError` if no match.
+
+### `client.focus` -> Hash
+Current focus: `{active_session:, active_tab:, active_window:, app_active:}`.
+
+### `client.session_info(session_id)` -> Hash
+Session details: `{tty:, pid:, cwd:, name:, job:}`.
+
+### `client.get_prompt(session_id)` -> Hash
+Prompt state: `{state:, command:, working_directory:, exit_status:}`.
+States: `:editing`, `:running`, `:at_prompt`, `:unavailable`.
+
+## Other Methods
+
+`topology_enriched`, `list_sessions`, `activate_tab`, `activate_window`,
+`raise_by_cwd`, `create_tab`, `split_pane`, `close_session`, `close_tab`,
+`set_profile_property`, `get_profile_property`, `list_profiles`, `get_property`,
+`get_variables`, `set_variables`, `inject`, `reorder_tabs`, `topology_for_aggregator`.
+
+## Notifications
+
+```ruby
+client.on_focus_change { |e| }       # {type: :focus, session:, ...}
+client.on_new_session { |e| }        # {type: :new_session, session_id:}
+client.on_session_terminated { |e| }  # {type: :session_terminated, session_id:}
+client.on_prompt_change(sid) { |e| }  # {type: :prompt, state:, ...}
+client.on_screen_update(sid) { |e| }  # {type: :screen_update, session:}
+client.on_layout_change { |e| }       # {type: :layout_change}
+```
+
+## CLI
+
+```bash
+iterm2ctl list              # list sessions
+iterm2ctl send "cmd"        # send text (auto-appends \n)
+iterm2ctl read              # read screen
+iterm2ctl raise "pattern"   # raise tab by title
+iterm2ctl focus             # show focus state
+iterm2ctl info              # show session details
+iterm2ctl move --tab ID --to-window ID  # move tab between windows
+iterm2ctl watch             # stream events as JSON
+```
+
+Most commands accept `--session ID`, `--tab ID`, `--window ID`, `--json`.
+
+## Errors
+
+`ITerm2::ConnectionError` (can't connect), `ITerm2::AuthError` (auth failed),
+`ITerm2::RPCError` (iTerm2 error), `ITerm2::NotFoundError` (no match),
+`ITerm2::SubscriptionError` (subscribe failed). All inherit `ITerm2::Error`.
+
+## Gotchas
+
+1. `send_text` does not append `\n` -- the CLI does, the API does not.
+2. iTerm2 sends each notification twice (server-side behavior).
+3. One-shot methods open a new connection per call -- use `ITerm2.connect { }` for batches.
+
+## Documentation
+
+- [Full API Reference](docs/api.md) -- every method with signatures, return shapes, examples
+- [CLI Reference](docs/cli.md) -- every command with flags and exit codes
+- [Architecture](docs/architecture.md) -- connection lifecycle, threading, protobuf protocol
+- [README](README.md) -- quick start guide