Example Scripts¶
Here are a collection of working scripts for you to crib from. While they are categorized according to their main function, some of them demonstrate more than one scripting feature. Search through this page or look for See Also sections in the documentation that link to examples demonstrating particular APIs.
Session Title Providers
George’s Title Algorithm — Demonstrates a complex session title provider.
Badge or Window Name in Tab Title — Demonstrates a simple session title provider.
Status Bar Components
Status Bar Component — Demonstrates a status bar component with variable-length text and a configurable knob.
Escape Key Indicator — Demonstrates monitoring for keystrokes, custom status bar components, and using variables as a back-channel for communication between parts of a script.
JSON Pretty Printer Status Bar Component — Demonstrates a status bar component that handles clicks and opens a popover with a web view.
Status Bar Component: Mouse Mode — Demonstrates a status bar component that responds to changes in a variable.
GMT Clock - Demonstrates a status bar component that shows the current time in the GMT time zone.
Free Disk Space Status Bar Component - Demonstrates a status bar component that updates itself periodically, showing the amount of free disk space.
Unread Count and Status Bar Icon - Demonstrates a status bar component with an icon and an “unread count”.
Web-Based Status Bar - Demonstrates fetching a web page periodically and showing its data in a custom status bar component. Also demonstrates providing an icon for a custom status bar component.
Show Python Virtual Environment - A status bar component that shows the current Python virtual environment.
Tmux
Tmux Integration — Demonstrates basic functions of the tmux integration API.
Tile tmux Window Panes — Demonstrates sending a command to the tmux server in tmux integration mode.
Monitoring for Events
Random Color Preset — Demonstrates performing an action when a new session is created and using a color preset.
Per-Host Colors — Demonstrates monitoring for different kinds of events concurrently.
Show Status Bar Only in Full Screen Windows - Demonstrates monitoring for the creation of windows and the change of window style.
Change Color Presets On Theme Change — Demonstrates monitoring a variable and using color presets.
Preserve Tab Color — Demonstrates monitoring for session creation and using color presets.
Tab Title - Demonstrates monitoring for the creation of a new tab. Also demonstrates prompting the user for a string and changing a tab title.
Alert on Long-Running Jobs - Demonstrates monitoring all sessions for long-running jobs. Also demonstrates posting notifications.
Send stty Command When Session Resizes - Demonstrates watching for a variable to change in all sessions and sending text in response.
Set Tab Color from Current App - Demonstrates watching for changes in the current foreground job. Updates the tab color as a function of the current command.
Sync Pane Title to Tab — Monitors for changes to a pane’s title and copies it to the tab title. Demonstrates monitoring for changes to a variable and setting variables.
Profiles and Color Presets
Get Selected Color Preset — Demonstrates getting a session’s profile and querying the list of color presets.
Modify Background Image Blending — Demonstrates registering a function and adjusting profiles’ values.
Set Tab Color — Demonstrates changing a session’s local profile without updating the underlying profile.
Increase Font Size By 6 — Demonstrates changing a session’s font without updating the underlying profile.
Resize Font in All Sessions in Window - Demonstrates registering a function that changes the font of all sessions in a window.
Change Default Profile - Demonstrates changing the default profile.
Change Session’s Profile - Demonstrates changing a session’s profile.
Standalone Scripts
Launch iTerm2 and Set Session Title — Demonstrates setting a session’s name. Also demonstrates a script that’s meant to be run from the command line that will launch iTerm2 and wait until it’s able to connect before proceeding.
Launch iTerm2 and Run Command — Demonstrates launching iTerm2 from the command line (if needed) and creating a new window that runs a command.
Keyboard
Function Key Tabs — Demonstrates changing the behavior of a keystroke.
Broadcasting Input
Enable Broadcasting Input — Demonstrates broadcast domains.
Asymmetric Broadcast Input — Demonstrates splitting panes, broadcast domains, filtering keystrokes, and sending input.
Windows and Tabs
Move Tab To Next/Previous Window — Demonstrates moving tabs among windows.
Sort Tabs — Demonstrates reordering tabs in a window.
Persistent MRU Tabs — Demonstrates monitoring for changes in keyboard focus and reordering tabs in a window. This script keeps tabs always in most-recently-used order, so the first tab is always selected.
Select MRU On Close - This script selects the next-most-recently-used tab when the current tab closes. Same for split panes.
Find Pane with Process - This script shows an alert prompting the user to enter a process ID and then reveals the pane that contains it.
Asyncio
Close Tabs to the Right — Demonstrates asyncio.gather to perform actions in parallel.
Change Color Preset by Time of Day — Demonstrates performing an action at a particular time of day.
Custom Toolbelt Tools
Targeted Input — Demonstrates custom toolbelt tool, broadcast domains, and sending input.
Custom Context Menu Items
Sum Selection - Demonstrates a custom context menu item that calculates the sum of selected numbers.
Selection
Zoom on Screen — Demonstrates selecting a menu item and modifying the selection.
Other
Clear All Sessions (all tabs or current tab) — Demonstrates registering a function, injecting a control sequence, and iterating over sessions.
Create Window — Custom Escape Sequence — Demonstrates custom control sequences.
One-Shot Alert — Demonstrates registering a function and showing a modal alert.