Proto commits in gnachman/iTerm2

These commits are when the Protocol Buffers files have changed: (only the last 100 relevant commits are shown)

2026-10-07

Add floating panes A floating pane floats over a tab's split panes. It can be moved, resized, raised, hidden, maximized, docked into the split panes, and dragged to other tabs and windows. Floats are saved with window arrangements and session restoration, can be created and controlled from the Python API, it2, AppleScript, key bindings and pointer actions, and work in tmux integration, which shows tmux's own floating panes. This squashes the floating-panes branch. See that branch for the individual commits.

2026-10-06

Report floating panes through the API, Python client and it2 Server (protocol 1.21): - ListSessions gives each tab its floating panes, back to front, with frame and grid, and whether they are hidden. - Adding, moving, resizing, restacking, hiding or showing a float sends a layout change. - Minimized sessions are the tiled panes that maximizing hid, also when a float is active. - Activating a float leaves a maximized pane alone. - Splitting “all” skips floats, whose splits go to a tiled pane. - move_session refuses a float as its destination. - apply_layout rejects a float as a leaf. Python client 2.26: - Tab.floating_sessions and Tab.floating_panes_hidden. - Session.floating. - all_sessions and lookups include floats. - current_session finds an active float. it2: - With no session given, a command uses the tab's active session, which may be a float. - Session lists and broadcast validation include floats.

2026-09-26

Add Python API support for Session Notes (#764) Add a strict, atomic session_note generic property for reading and patching Session Notes, plus typed Python SDK get/set methods and a read-only SessionNote value. A patch may be partial: omitted keys retain their current values, and an empty text removes the note. Preserve terminal focus for API-driven show, update, collapse and background-session operations. Restore Session Notes through a saved-state relaunch by hydrating the model in +sessionFromArrangement: instead of the async finish block, which ran after -didFinishRestoration and so left the model nil when restoration looked at it. The protobuf schema is unchanged. Only its documentation comments gained the new property.

2026-09-16

Add Python API for tab groups Expose tab groups to the Python API: discover them via Tab.tab_group and Window.tab_groups, create them with Window.async_create_tab_group, change membership with Tab.async_add_to_tab_group / async_remove_from_tab_group, and rename, recolor, or collapse them via the TabGroup class. The consecutive-tabs invariant is enforced in iTerm2, which reorders tabs as membership changes. The rename/recolor/collapse mutators are registered as app-scope built-in functions (iTermTabGroupBuiltInFunctions) that resolve the group's current host window at call time, so a TabGroup handle keeps working after its tabs are dragged to another window. Membership and creation stay window-scoped because they act on tabs whose window is known when called. New protocol version 1.19 carries the per-tab group id, name, color, and collapsed state in ListSessionsResponse. Bumps the iterm2 module to 2.24 and adds an interactive example plus its test wrapper.

2026-09-10

Fix Python API current_tab/current_session None after async_create A script that created a window and then immediately read Window.current_tab or Tab.current_session got None, so scripts that split panes or changed fonts on a freshly created window stopped working in 3.7.0. The iterm2 Python library learns a new window's selected tab and active session only from FocusChanged notifications, and 2.21 added an async_refresh re-entrancy guard that swallows the recovery refresh when those notifications arrive before the client knows the window exists. iTerm2 selects the new tab synchronously during creation, i.e. before the CreateTab response, so the client is always in exactly that state. Durable fix: carry the selected tab and per-tab active session in ListSessionsResponse (protocol 1.18) and read them in the library, so current_tab/current_session are correct straight out of the refresh that async_create already performs, with no dependence on notification timing. Library bumped to 2.23. Transitional server-only workaround for already-shipped clients in the affected range [2.21, 2.23): hold a connection's selected_tab and active-session FocusChanged notifications while it has a CreateTab in flight, then replay that create's own ids to that one connection after the response is sent. Encapsulated in iTermAPICreateTabFocusDeferral, gated on the x-iterm2-library-version header, scoped per connection so other connections keep receiving focus notifications live. Deletable once every supported client is 2.23+. Adds unit tests for the version gate and the deferral's hold/replay behavior, and a manual-test runner for the patched library.

Fix Python API current_tab/current_session None after async_create A script that created a window and then immediately read Window.current_tab or Tab.current_session got None, so scripts that split panes or changed fonts on a freshly created window stopped working in 3.7.0. The iterm2 Python library learns a new window's selected tab and active session only from FocusChanged notifications, and 2.21 added an async_refresh re-entrancy guard that swallows the recovery refresh when those notifications arrive before the client knows the window exists. iTerm2 selects the new tab synchronously during creation, i.e. before the CreateTab response, so the client is always in exactly that state. Durable fix: carry the selected tab and per-tab active session in ListSessionsResponse (protocol 1.18) and read them in the library, so current_tab/current_session are correct straight out of the refresh that async_create already performs, with no dependence on notification timing. Library bumped to 2.23. Transitional server-only workaround for already-shipped clients in the affected range [2.21, 2.23): hold a connection's selected_tab and active-session FocusChanged notifications while it has a CreateTab in flight, then replay that create's own ids to that one connection after the response is sent. Encapsulated in iTermAPICreateTabFocusDeferral, gated on the x-iterm2-library-version header, scoped per connection so other connections keep receiving focus notifications live. Deletable once every supported client is 2.23+. Adds unit tests for the version gate and the deferral's hold/replay behavior, and a manual-test runner for the patched library.

2026-07-01

Add screenshot save destination and Python API capture Adds a configurable save location to the Make Screenshot window: the "Save" button honors the new screenshotSaveLocation advanced setting (empty falls back to the Desktop), and a new "Save As…" button opens a save panel and supports multi-part output. Save logic is unified behind a small SaveDestination. Also exposes screenshot capture to the Python API via Session.async_screenshot() -> bytes, backed by new ScreenshotRequest / ScreenshotResponse proto messages (field 134), regenerated ObjC and Python gencode, server dispatch, and an apiServerScreenshot: delegate that reuses PTYSession's existing render path. The API is version-gated (protocol 1.17, check_supports_screenshot). George Nachman reviewed and revised this work: removed the dead applyBackground(to:color:) helper left over from the reverted background-color feature, fixed tilde expansion for the screenshotSaveLocation setting so a ~ path no longer silently falls back to the Desktop, and kept Copy from closing the panel (which would be destructive). Co-authored-by: George Nachman <gnachman@gmail.com>

2026-06-18

feat(api): add select_tab to CreateTabRequest for background tabs (#675) The Python API's create_tab always selected the new tab and ordered its window to the front, stealing keyboard focus on every create. This is asymmetric with SplitPaneRequest, which never raises or steals focus, and there was no per-creation equivalent of ActivateRequest's select_tab / order_window_front controls (GitLab #8223). Add an opt-in optional bool select_tab = 6 on CreateTabRequest. Unset or true reproduces the historical behavior exactly; false creates the tab in the background without selecting it or raising its window. A brand-new window (its first tab) is still ordered front regardless. The window/focus motion came from three spots: insertTab:atIndex:'s makeKeyAndOrderFront: and its setCurrentTerminal:, plus the launcher's makeKeyAndActivateIfNeeded: (canActivate = NO only suppressed cross-app activation, not the in-app raise). All three are now gated: a new automaticallyOrderFrontNewTabs property (default YES) mirrors automaticallySelectNewTabs and guards the two insertTab: spots, and apiServerCreateTab: sets launcher.makeKey plus both term flags from select_tab, restoring them after the create. Python: Window.async_create_tab / iterm2.rpc.async_create_tab gain select: bool = True. Generated stubs regenerated with tools/build_proto.sh; wire format unchanged. Co-authored-by: G Six <localparty@gmail.com>

2026-06-02

OSC 133 k= and aid= support Implement OSC 133 k= (Semantic Prompt prompt kind: i/s/c/r) and aid= (nested shell-integration session id) attribute support end-to-end. Parser (VT100Terminal) handles key=value arguments on A/B/C/D/P. Marks gain kind, excludedSubranges, firstLineOfCommand/fullCommand, and aid/parentAid/ancestorAids. Non-initial prompts (k=s/c/r) add excluded subranges to the active mark without breaking the prompt state machine or paste-each-line gate. aid= populates a registry so D;aid=X targets the matching mark and an outer-D cascade-closes inner marks (e.g. ssh tunnel drops where the inner D never arrives). Mark coord storage (promptRange / commandRange / outputStart and the excludedSubranges endpoints) moves to ResilientCoordinate so it survives folds, resizes, and scrollback overflow. Saved-tree (alt- screen) marks observe a separate RC pool whose resize broadcast is built against altScreenLineBuffer rather than the primary linebuffer. Consumers (Select Current Command, share URL, AI explain, the Python GetPromptResponse.excluded_subranges field, etc.) subtract excluded subranges from the typed-command range. Shell integration scripts (bash, zsh, fish, tcsh, xonsh) emit k=s around PS2 and aid= on A/B/C/D. New /v2/ scripts ship alongside legacy /v1/. Fixes issue 5749 (Advanced Paste hangs on PS2).

2024-09-11

Expose style info to Python API. Issue 11848

The documentation is generated from this commit.

2021-09-26

Add support for HTML formatted status bar components.

2021-07-24

Expose minimized sessions (i.e., siblings of a maximized session) to Python API. Add Tab.all_sessions which includes them. Fix EachSessionOnceMonitor to also affect minimized sessions (this may break things). Issue 9813

2021-07-06

Provide a GetPromptResponse object along with a PROMPT notification. Issue 8245

2021-03-22

[python, api] Add advanced keystroke notifications that include key-up and flags-changed. Issue 9585

2020-08-31

Context menu improvements. - Fix parsing user-provided URLs with // in query parameter. - Fix some failing tests - Don't show pause/unpause tmux in context menu in versions of tmux that don't support it. - Move context menu code into its own file. - Add support for context menu providers in Python API.

2020-08-12

Document built-in API methods

2020-07-10

[python,api] Add Arrangements.async_list. Issue 9004

2020-02-18

[Python,API] Add support for listing prompts by ID. Add capabilities check for prompt ID and bump protocol version number

[API,python] Add ability to get prompt by ID

[python,API] Expose prompt unique ID

[python, API] Expose prompt state in GetPromptResponse

2019-11-09

Add support for getting the default profile

2019-11-01

start implementing custom line graphs

2019-08-07

Add support for custom status bar components to have icons

2019-08-06

Improve PromptMonitor to inform you when a command starts and ends.

2019-06-01

Add Session.async_set_profile(). Issue 7782 - Add Profile.local_write_only_copy - Add Session.async_set_profile - Make iTerm2 report its version to the websocket client - Add a capabilities check so the python library can be backward-compatible with older versions of iTerm2 by using deprecated APIs for them. - Add the ability to set multiple profile properties at once from Python. Deprecate the one-at-a-time API. - If you try to set session-specific profile values that are effectively equal to a shared profile, just switch to the shared profile. If they include a GUID matching a shared profile, switch to it and then divorce and modify. - Bump the min library version to 0.69 - Improve validation of API requests to set profile properties. - Expose the set of non-deprecated keys from iTermProfilePreferences. - Remove default profile values for deprecated keys

2019-05-20

Add support for modal alerts attached to windows. For method calls, pass receiver in protobuf rather than taking the "id" argument. Built-in functions can now declare optional-valued arguments. Add tabtitle example. This commit breaks backward compatibility with older python library alert.py's.

2019-05-19

Add support for method invocations from scripts. The purpose is to make it easier to add new scripting functionality without adding new protobuf interfaces. A method call is just like a function call except: 1) It is marked as a method call in the RPC request 2) It must contain an "id" argument 3) The value of the "id" argument is a globally unique identifier for the receiver This commit adds support for a class creating a variables frame to mark one of its variables as a "primary key". Primary keys are added to the global index, and can be targeted by method calls. Varible references have been generalized not to depend on scopes, so that a variable may hold a reference to its own primary key. A class may support methods by: 1) Conforming to iTermObject, which is necessary to be the "owner" of an iTermVariables object. 2) Returning built-in functions from -objectMethodRegistry. Those built-in functions should be named as fooWithCompletion: followed by zero or more other arguments. Reflection is used to type check inputs, although it's unfortunately ineffective as it only recognizes NSObject. Better type checking is still needed.

2019-05-10

Add a user scope per window and add an API to set values in it to Python

2019-02-10

Add the ability for scripts to invoke registered functions. Register a move-tab-to-window builtin function. Add APIs to call it and to invoke functions in the various contexts. Still needs more testing.

2019-01-18

Add a completion block to toggle full screen. Delay responding the API RPC to toggle full screen until it's actually done/failed. Issue 7438

2018-12-28

[python, api] Give session title providers a unique ID. Now you can change their function signatures without having to go through setup again. Also fix up the status bar onclick registration to be less weird. fixup

2018-12-22

[python, api] Improvements to NewSessionMonitor 1. Move it to the lifecycle module 2. Rename uniqueIdentifier to session_id in the proto

[python, api] Improvements to session termination notifications 1. Move the python code into the lifecycle module. Add docs for it. 2. Change the proto to use the more standard session_id field name. 3. Change the semantics to communicate when a session's command exits rather than when its window closes. Now a session can only terminate once, which is much nicer. 4. Use a context manager instead of a callback.

2018-12-21

[python] Remove location change notifications because they're equally well handled by variable notifications. Move prompt notifications to a context manager.

2018-12-14

[api. python] Add async_close to tab, window, and session. Issue 7414.

2018-12-12

[python, api] Update keyboard interfaces. Filtering is now a distinct subscription from keyboard monitoring. It does not send notifications. This allows you to filter separately from monitoring. All the keyboard code is now in the same python file. The examples are updated.

2018-11-09

Fix a lot of spelling mistakes. PR 367 by jsoref. Minor tweaks by gln.

2018-10-19

Make it possible to subscribe to profile changes. Expose the evaluated badge text in a variable. Add the badgetitle example.

2018-10-18

[python, api] Add APIs for setting broadcast domains

2018-10-09

[api, python] Add support for getting the selection. Change how screen contents are fetched to be very general. Deprecate some of the old ways of getting screen contents. Add support for opening popovers from status bar components. Add support for an on-click handler for status bar components. Add lots of handy methods to the util functions.

2018-10-07

[python, api] Add interface to get number of lines on screen, history, and overflow

[python, api] Add support for getting and setting the selection.

2018-09-23

[python, api] Add color presets to API. Refactor Color into its own submodule. Add gather to connection. Change how waiting on the websocket works to support the case where two receivers exist and the first one finishes before the second one. Before, the second one would never await the websocket leading to deadlock.

2018-09-22

Attempt to add color presets. My gather function deadlocks for some reason.

2018-09-16

Incomplete implementation of variable references

2018-09-14

Incomplete implementation of variable references

2018-09-12

[python, api] Enable monitoring variables in python. Expose mouse mode as a variable.

2018-08-02

[api, python] Enable creating tmux integration windows and tabs

2018-07-26

[api, python] Add support for setting the default profile. Fix repl detector for aioconsole 0.1.10

2018-07-17

[status bar] Add support for custom status bar components.

2018-07-14

[status bar] Add support for custom status bar components.

2018-07-10

[api] Add API to reorder tabs. Issue 5671

2018-06-25

[api, python] Add support for app and tab variables in API. Update it2api, python lib, and docs.

2018-06-23

[api, python] Add support for tmux to the API

2018-06-20

[python, api] Allow sending text without broadcast. Fix a typo. Make custom tools reload when their script is registered. Link the targeted_input example.

[api, python] Add support for broadcast domains

2018-06-17

[api, python] When registering for keystroke notifications API clients can specify keystroke patterns for the app to ignore. Issue 6780 Note these are only ignored as input to a session, not (e.g.) main menu shortcuts.

2018-06-11

Add support for custom session title functions

2018-06-10

Add support for custom session title functions

2018-05-30

[python, api] add the ability to customize the profile of new tabs and windows

[api, python] Add the ability to override profile properties when creating a split pane

[api, python] Add API to bury/disinter sessions

[api, python] Add support for changing split pane layout.

[api, python] Add support for get/set session property of grid_size

2018-05-27

Initial attempt at set tab layout. Untested

[api, python] Add support for get/set session property of grid_size

2018-05-26

[api, python] Add support for buried sessions

2018-05-25

[api, python] Add support for invoking and querying state of menu items

2018-05-23

[api] Add support for restarting the session. Fix up some naming issues in session.py

2018-05-22

[api, python] Use JSON to get/set variables

2018-05-21

[api] Make RPC timeouts settable at registrationtime

2018-05-19

[api] Giant friggin commit to add support for iTerm2-originated RPCs. - Add support for registering for iTerm2-invoked RPCs in scripts. - Add key binding to invoke a script function. - Add CoreParse third party library - Make session variables not always strings - Add session.id to variables. Gives the GUID. - Recognize Python as the name of a python binary. It can be distributed as an app bundle. - Refactor request handling in APIServer - Expose textview in disclosable view so it can be made selectable. - Add support for disclosable view accessories to iTermWarning. Still left to do: - Autocomplete for function arguments in the keybinding text field would be nice - Update docs, adding app.async_register_rpc_handler, notifications.async_subscribe_to_server_originated_rpc_notification - Add a tutorial on how to write one an RPC handler - Allow SetVariable RPC to send non-string values. Use json to encode its value. - Allow GetVariable RPC to return non-string values over JSON.

2018-05-18

Add support for missing keys to api and python.

Add apis for listing profiles

2018-05-11

[python] Improve focus notifications

2018-04-26

Add focus change notifications and API to query focused objects

Add interfaces for saving/restoring window arrangements

Add support for activating the app

If the library is newer than iTerm2 then respond with an error instead of just not ACKing

Move top level message fields into oneof

Add ability to get and set variables

Update iterm2env. For some reason it was a broken python install. Add Activate API.

2018-04-24

API: Add inject RPC

API: Add property getters and setters. For now, just frame and fullscreen exist.

2018-04-22

Add special 'active' and 'all' session IDs to API proto

2018-04-21

Rename request and response to be more general

Update API to use python 3.6 asyncio. Improve the proto to include splitter hierarchy.

2018-04-12

Add API endpoint for getting profile properties

2017-05-29

Add a few new notifications to the API server for session terminated (i.e., removed from UI) and layout changed. Update the python library to keep its window hierarchy in synch with the truth.

2017-05-21

Add API to split panes to API server.

Add create tab/window API to api server.

2017-05-05

Add a session-created websocket API notification.

Add a notification to the websocket server that receives custom escape sequences. Add a python example to receive them and a shell script to send them.

2017-03-21

Add a send text request to the API server

2017-02-12

Indicate which session caused a notification

Add a list-sessions API

2017-01-29

Add websocket API to subscribe to location (host, user, directory) changes.

Add websocket API for changing profile properties

2017-01-27

Add a prototype API server using websockets.