OSC 1337 iTerm2 Extensions

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 and the pages it links to:

That is every key iTerm2 documents, in its Proprietary Escape Codes page and in the pages it sends a reader to for images, badges and feature reporting. libghostty-vt recognizes all but three, without regard to case, and acts on two, Copy and CurrentDir; it consumes the rest without doing anything. The three it does not know, Capabilities, SetProfileProperty and UpdateBlock, are newer, and it ignores them all the same.

iTerm2 has a few extensions outside 1337 as well:

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.

Support

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

A
\e]6;1;bg;red;brightness;255\a
B

|AB____|
cursor 1,3

ITERM2-6: Newer keys are ignored too

A
\e]1337;Capabilities\a
\e]1337;SetProfileProperty=Cursor Type=Mg==\a
\e]1337;UpdateBlock=id=b;action=fold\a
B

|AB____|
cursor 1,3
reply none