OSC 1337 iTerm2 Extensions
iTerm2's own commands: inline images, marks, user variables, the clipboard and the working directory, and its other OSC extensions.
OSC 1337 ; Pt ST
- ECMA-48
- §8.3.89 OSC – Operating System Command, p. 51
- Specification
- Proprietary Escape Codes, iTerm2 documentation
iTerm2, the macOS terminal, puts most of its own commands under one OSC number, 1337, as OSC 1337 ; Key=value ST; it used OSC 50 once, and moved because xterm uses 50 for fonts. Their definition is iTerm2’s Proprietary Escape Codes page. Some of the ones programs use most:
Pt | Does | libghostty-vt |
|---|---|---|
CurrentDir=dir | report the shell’s working directory | kept, as OSC 7 |
Copy=:base64 | put text on the clipboard | passed to the host, as OSC 52 |
File=args:base64 | show a file, usually an image, inline in the text | ignored |
SetMark | set a mark to jump back to | ignored |
SetUserVar=name=base64 | set a variable iTerm2 can show, such as in a tab title | ignored |
RemoteHost=user@host | report the user and host the shell is on | ignored |
ShellIntegrationVersion=n | report the version of iTerm2’s shell integration | ignored |
CursorShape=n | 0 block, 1 bar, 2 underline, from Konsole | ignored |
ReportCellSize | ask for a cell’s size in points; answered OSC 1337 ; ReportCellSize=h;w;scale ST | not answered |
ReportVariable=base64 | ask for one of iTerm2’s variables | not answered |
ClearScrollback | erase the scrollback | ignored |
StealFocus, RequestAttention=yes | bring the window forward, bounce the dock icon | ignored |
SetProfile=name, SetColors=key=value | change the session’s profile or colors | ignored |
CopyToClipboard=name … EndCopy | copy all the text in between to the clipboard | ignored |
SetBadgeFormat=base64, SetKeyLabel=key=value | the badge, the Touch Bar’s labels | ignored |
UnicodeVersion=n | choose Unicode 8’s or 9’s character widths | ignored |
The page lists more, such as annotations, blocks and buttons, and Custom=id=secret:pattern for sequences a script defines itself. libghostty-vt recognizes every key it lists, without regard to case, and acts on the two above; it consumes the rest without doing anything.
iTerm2 has a few extensions outside 1337 as well:
| Sequence | Does | libghostty-vt |
|---|---|---|
OSC 4 ; -1 ; ? ST, OSC 4 ; -2 ; ? ST | ask for the default foreground and background, through the palette query | not answered |
OSC 6 ; 1 ; bg ; red ; brightness ; n ST | color the tab; the same for green and blue | ignored |
OSC 21337 ; status=text ST | set the tab’s status line and indicator | ignored |
OSC P n rrggbb ST | change a color, the Linux console’s way | ignored |
and it documents others that this site gives pages of their own: notifications with OSC 9, progress with OSC 9 ; 4, FinalTerm’s shell integration marks with OSC 133, hyperlinks, and its answer to XTVERSION, iTerm2 and its version.
A default xterm has none of these and ignores them (the OSC numbers it knows). OSC 6 is xterm’s own, for turning its special colors on and off, but iTerm2’s string does not parse as that and changes nothing (do_osc); OSC 4 ; -1 is a negative color number, where xterm stops (ChangeAnsiColorRequest). The cases follow xterm, so the one where libghostty-vt keeps the working directory is a known difference.
Validation
ITERM2-1: The working directory
\e]1337;CurrentDir=/home/user\a
|______|
pwd ""
ITERM2-2: The clipboard changes nothing on screen
A
\e]1337;Copy=:SGVsbG8=\a # "Hello"
B
|AB____|
cursor 1,3
reply none
ITERM2-3: The rest are consumed
A
\e]1337;SetMark\a
\e]1337;SetUserVar=name=dmFsdWU=\a
\e]1337;RemoteHost=user@example.com\a
\e]1337;CursorShape=1\a
\e]1337;File=inline=1:SGVsbG8=\a
B
|AB____|
cursor 1,3
reply none
ITERM2-4: Questions are not answered
\e]1337;ReportCellSize\a
\e]1337;ReportVariable=c2Vzc2lvbi5uYW1l\a
\e]4;-1;?\a
|______|
reply none
ITERM2-5: Tab colors and status
A
\e]6;1;bg;red;brightness;255\a
\e]21337;indicator=#ff0000;status=busy\a
B
|AB____|
cursor 1,3
ITERM2-6: OSC P does not change a color
\e]Pg4040ff\e\\ # the foreground, the Linux console's way
\e]10;?\a
|______|
reply \e]10;rgb:0000/0000/0000\a