iterm2_ruby
Ruby gem + CLI for controlling iTerm2 via its native WebSocket + Protobuf API.
Too many iTerms. Too many tabs. Too many agents "helping" you at once.
GenAI made you think you can do 20 things at once. It was wrong, but you did it anyway and you're still doing it, and now you've got 20 terminal windows and no idea which one's stuck waiting on you. osascript is too slow to keep up, steals your focus every time it tries, and nags you for an Automation permission it already has. iterm2_ruby skips all of that: it talks to iTerm2 directly, so you can actually navigate the mess you made -- ~20x faster, no focus theft, plus real-time event notifications so you don't have to go looking in the first place.
Real-World Usage
Four things it's doing today, in real projects:
Jump to any running session instantly, by project name. No window-hunting:
ITerm2.connect { |c| c.raise_by_title(project_name) }
No stolen focus, no AppleScript delay -- just the right window, front and center.
A live dashboard across every open terminal. One call returns every window, tab, and session, enriched with project name, status, cwd, and PID:
data = ITerm2.connect { |c| c.topology_for_aggregator }
This feeds a real-time "mission control" view over a whole fleet of sessions.
Split a pane and pop a live browser preview next to your code:
ITerm2.connect do |c|
c.split_pane(guid, vertical: true, profile_name: "Web Browser",
profile_customizations: { "Initial URL" => url })
end
Spawn a background task in its own window, no permission dialogs:
iterm2ctl create window # => session E8F2...
iterm2ctl send "run-task.sh" --session E8F2...
AppleScript automation triggers a macOS Automation prompt every time. This doesn't.
Installation
gem install iterm2_ruby
Or add to your Gemfile:
gem "iterm2_ruby"
Prerequisites
- macOS with iTerm2 installed
- Ruby >= 3.1
- iTerm2 API enabled: Preferences > General > Magic > Enable Python API
Quick Start (CLI)
# List all windows/tabs/sessions
iterm2ctl list
# Send text to the active session
iterm2ctl send "echo hello"
# Read visible screen contents
iterm2ctl read
# Raise tab matching a title pattern
iterm2ctl raise "my-project"
# Show current focus state
iterm2ctl focus
# Watch for events in real-time
iterm2ctl watch
Quick Start (Ruby API)
One-shot (auto-connects, runs command, disconnects)
require "iterm2"
# List all sessions
sessions = ITerm2.topology
sessions.each { |s| puts "#{s[:session_id]} - #{s[:title]}" }
# Send text to a session
ITerm2.send_text(session_id, "ls -la\n")
# Read screen contents
screen = ITerm2.read_screen(session_id)
puts screen[:lines].join("\n")
# Raise a tab by title
ITerm2.raise_by_title("my-project")
# Get current focus
focus = ITerm2.focus
puts focus[:active_session]
Persistent client (reuses connection)
require "iterm2"
ITerm2.connect do |client|
# List sessions
sessions = client.topology
session_id = sessions.first[:session_id]
# Get detailed session info
info = client.session_info(session_id)
puts "CWD: #{info[:cwd]}, PID: #{info[:pid]}"
# Watch for focus changes
client.on_focus_change do |event|
puts "Focus changed: #{event}"
end
sleep # keep connection open for notifications
end
CLI Command Reference
| Command | Description | |
|---|---|---|
list |
List all windows/tabs/sessions | |
list --with-cwd |
Include working directories | |
list --with-pid |
Include PIDs | |
list --triage |
Compact triage view (window/tab/session/cwd/job) | |
tabs |
List tabs grouped by window | |
send TEXT |
Send text to a session | |
send-text ID TEXT |
Send text to a specific session by ID | |
read |
Read visible screen contents | |
read-screen ID |
Read screen for a specific session by ID | |
raise PATTERN |
Raise tab matching title pattern | |
raise --cwd PATH |
Raise tab by working directory | |
activate-session ID |
Activate a session directly by ID | |
| `create [window\ | tab]` | Create a new window or tab |
split |
Split the current pane | |
close |
Close a session | |
move --tab ID --to-window ID |
Move a tab to another window | |
var get NAME |
Get a variable | |
var set NAME VALUE |
Set a variable (user.* only) | |
var all |
Dump all variables | |
info |
Show session tty, pid, cwd, job | |
focus |
Show current focus state | |
prompt |
Show prompt state | |
watch [TYPE] |
Watch for events (focus/sessions/prompt/screen/layout) | |
profile [KEYS] |
Get profile properties | |
profiles |
List all profiles | |
inject TEXT |
Inject data as if from process | |
version |
Show version | |
help |
Show help |
Most commands accept --session ID, --tab ID, or --window ID to target a specific object. Use --json for machine-readable output.
Ruby API Reference
Connection
| Method | Description | ||
|---|---|---|---|
| `ITerm2.connect { \ | client\ | ... }` | Open connection, yield client, auto-close |
ITerm2::Client.new |
Create persistent client | ||
client.close |
Close connection |
Topology
| Method | Description |
|---|---|
list_sessions |
Raw ListSessionsResponse from iTerm2 |
topology |
Flat array of {window_id:, tab_id:, session_id:, title:} |
topology_enriched |
Topology with cwd, pid, tty, job added |
session_info(session_id) |
Get tty, pid, cwd, name, job for a session |
Session Interaction
| Method | Description |
|---|---|
send_text(session_id, text) |
Send text to a session |
read_screen(session_id) |
Read visible screen (returns {lines:, cursor:}) |
inject(session_id, data) |
Inject data as if from process |
Window Management
| Method | Description |
|---|---|
activate_session(session_id) |
Raise and focus a session |
activate_tab(tab_id) |
Raise a tab |
activate_window(window_id) |
Raise a window |
raise_by_title(pattern) |
Raise first session matching title |
raise_by_cwd(pattern) |
Raise first session matching cwd |
create_tab(window_id:, profile_name:) |
Create a new tab |
split_pane(session_id, vertical:) |
Split a pane |
close_session(session_id) |
Close a session |
close_tab(tab_id) |
Close a tab |
reorder_tabs(window_id => [tab_ids]) |
Move/reorder tabs across windows |
Profile & Properties
| Method | Description |
|---|---|
set_profile_property(session_id, key, value) |
Set a profile property |
get_profile_property(session_id, *keys) |
Get profile properties |
list_profiles(properties:, guids:) |
List all profiles |
get_property(name, session_id:) |
Get a session/window property |
get_variables(*names, session_id:) |
Get variables |
set_variables(vars, session_id:) |
Set user variables |
focus |
Get current focus state |
get_prompt(session_id) |
Get prompt state |
Notifications (Real-time Events)
| Method | Description | ||
|---|---|---|---|
| `on_focus_change { \ | event\ | }` | Focus changed |
| `on_new_session { \ | event\ | }` | New session created |
| `on_session_terminated { \ | event\ | }` | Session terminated |
| `on_prompt_change(session_id) { \ | event\ | }` | Prompt state changed |
| `on_screen_update(session_id) { \ | event\ | }` | Screen content changed |
| `on_layout_change { \ | event\ | }` | Layout changed |
How It Works
- Authentication: One-time osascript call gets a cookie+key from iTerm2
- Connection: WebSocket to iTerm2's local API (Unix socket or TCP port 1912)
- Protocol: Google Protocol Buffers for message encoding (binary, fast)
- Notifications: Background dispatch thread routes events to registered callbacks
No external WebSocket gems required -- framing is hand-rolled per RFC 6455.
Documentation
docs/cli.md-- fulliterm2ctlcommand referencedocs/api.md-- complete Ruby API referencedocs/architecture.md-- connection, auth, and dispatch designllms.txt-- condensed reference for LLM/agent use
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/fkchang/iterm2_ruby.
License
MIT License. See LICENSE for details.