docs/vt: document a bunch of OSCs #399

pluiedev · 2025-11-21T16:17:09Z

What it says on the tin. The precise list is OSCs 0-2, 4, 5, 7, 9, 9;4, 10-19, 22, 52, 104, 105 and 110-119.

Also expanded the concept page about control sequences and added a concept page detailing the color syntax we support.

vercel · 2025-11-21T16:17:14Z

@pluiedev is attempting to deploy a commit to the Ghostty Team on Vercel.

A member of the Team first needs to authorize it.

00-kat

N.B.: I did sometimes try to maintain hard-wrap in suggestions but not always, so they may need re-wrapping.

00-kat · 2025-11-22T06:58:42Z

docs/vt/concepts/sequences.mdx

+An OSC sequence begins with OSC (`ESC ]` or `0x9d`). Then, by convention, an
+integer is added to identify the operation 

-OSC Sequences are typically used to encode strings or other non-integer data to
-transmit between the terminal and the application. The format of an OSC sequence
-is below. An example OSC sequence is `OSC 2 ; 👻  Ghostty 👻  ST` (where `ST` is
-the String Terminator). By convention, OSC sequences *usually* have some integer
-identifier to identify the sequence.
+The format of an OSC sequence is below. By convention, OSC sequences are
+identified by an integer identifier followed by a semicolon (`;`), although
+this is never required by the standard. Certain obsolete OSC sequences use
+non-numeric identifiers before the semicolon, but Ghostty does not support


The convention of adding an integer is mentioned twice on adjacent sentences.

Suggested change

An OSC sequence begins with OSC (`ESC ]` or `0x9d`). Then, by convention, an

integer is added to identify the operation

OSC Sequences are typically used to encode strings or other non-integer data to

transmit between the terminal and the application. The format of an OSC sequence

is below. An example OSC sequence is `OSC 2 ; 👻 Ghostty 👻 ST` (where `ST` is

the String Terminator). By convention, OSC sequences *usually* have some integer

identifier to identify the sequence.

The format of an OSC sequence is below. By convention, OSC sequences are

identified by an integer identifier followed by a semicolon (`;`), although

this is never required by the standard. Certain obsolete OSC sequences use

non-numeric identifiers before the semicolon, but Ghostty does not support

The format of an OSC sequence is below. An OSC sequence begins with OSC (`ESC ]`

or `0x9d`). Then, by convention, an integer is added to identify the operation,

followed by a semicolon (`;`), although this is never required by the standard.

Certain obsolete OSC sequences use non-numeric identifiers before the semicolon,

but Ghostty does not support

00-kat · 2025-11-22T07:00:51Z

docs/vt/concepts/sequences.mdx

+this is never required by the standard. Certain obsolete OSC sequences use
+non-numeric identifiers before the semicolon, but Ghostty does not support
+
+> [!NOTE]


Having a note that interrupts a line reads really weirdly to me; I don't know how it renders on the website but the file's contents and GitHub's rendered view both look odd.

I think the note should be moved under the format description (i.e. right above the DCS heading), since otherwise the format is quite far away from “The format of an OSC sequence is below” in the first line of the paragraph before the note.

00-kat · 2025-11-22T07:06:47Z

docs/vt/concepts/sequences.mdx

-identifier to identify the sequence.
+The format of an OSC sequence is below. By convention, OSC sequences are
+identified by an integer identifier followed by a semicolon (`;`), although
+this is never required by the standard. Certain obsolete OSC sequences use


There has not been a mention of the standard before this, and no other mention clarifies which standard is being referred to: many OSCs have their own standard that require the integer identifier, so this might cause confusion.

Also I feel like “specified” is a better term than “required” here since OSCs can't be parsed without some way to know what's being parsed (as it's just arbitrary data), so there's always some means of identifying it and including the identifier is required even if the standard doesn't say what the identifier looks like or where it goes.

00-kat · 2025-11-22T07:10:06Z

docs/vt/concepts/sequences.mdx

+osc_sequence = "0x1B" "]" data terminator
 data = [0x20-0xFF]
-ST = "0x1B" "0x5C"
+terminator = "0x1B" "0x5C"


Shouldn't BEL be included here?

Suggested change

terminator = "0x1B" "0x5C"

terminator = "0x1B" "0x5C" | "0x07"

00-kat · 2025-11-22T07:33:05Z

docs/vt/external.mdx

+Below is a list of protocols that Ghostty supports, which originate from other
+terminal emulators:


Is this list actually exhaustive? I could assume it's close for just OSCs but the page is in /docs/vt and not /docs/vt/osc, and it's missing at the very least KIP (I haven't tried to determine what else is missing, this is just the first one I thought of since the page on sequences mentions it). It might be worth noting this “isn't exhaustive” or is “still work in progress”?

00-kat · 2025-11-22T10:11:15Z

docs/vt/osc/52.mdx

+
+When `d` is the single character `?`, the terminal will reply with
+another OSC 52 sequence with the data found from the first clipboard
+listed in `t` that contains the requested data.


I think this could use an example: while it's obvious what the response looks like, it's not particularly obvious what the t value is in the presence of multiple clipboards in t.

Edit: Ghostty seems to just do nothing…?

00-kat · 2025-11-22T10:22:18Z

docs/vt/concepts/colors.mdx

@@ -0,0 +1,72 @@
+---
+title: Colors
+description: All sorts of information regarding colors in terminal emulation.


Suggested change

description: All sorts of information regarding colors in terminal emulation.

description: Assorted information about colors in terminals.

“All sorts of” → “Assorted” was just one of… assorted changes, but “terminal emulation” to me feels like an obscure way to put it, and “terminals” over “terminal emulators” since that seems to be more common in these docs.

00-kat · 2025-11-22T10:31:25Z

docs/vt/concepts/colors.mdx

+<VTSequence sequence={["#", "Pr", "Pg", "Pb"]} />
+
+Where each of `r`, `g` and `b` can be one to four hexadecimal digits,
+corresponding to 4, 8, 12 or 16 bit color channels respectively.


Other docs use a serial comma.

Suggested change

corresponding to 4, 8, 12 or 16 bit color channels respectively.

corresponding to 4, 8, 12, or 16 bit color channels respectively.

00-kat · 2025-11-22T10:31:32Z

docs/vt/concepts/colors.mdx

+<VTSequence sequence={["#", "Pr", "Pg", "Pb"]} />
+
+Where each of `r`, `g` and `b` can be one to four hexadecimal digits,
+corresponding to 4, 8, 12 or 16 bit color channels respectively.


Suggested change

corresponding to 4, 8, 12 or 16 bit color channels respectively.

corresponding to 4, 8, 12 and 16 bit color channels respectively.

I think.

00-kat · 2025-11-22T10:41:42Z

docs/vt/concepts/colors.mdx

+description: All sorts of information regarding colors in terminal emulation.
+---
+
+Ghostty emulates a full 256-color palette, as well as 5 **special colors**


Might it also be useful to note what the 256-color palette is?

mitchellh · 2025-12-02T19:50:55Z

I think there are a bunch of improvements that can be made but I'm going to accept this as a general net positive. Thank you.

docs/vt: fill in more details about control sequences

c5e3227

pluiedev force-pushed the pluie/jj-poqplzsntrln branch from 749f151 to 8fb52d4 Compare November 21, 2025 16:18

pluiedev added 3 commits November 22, 2025 00:20

docs: add OSCs 0-2,4,5,7,9,9;4,10-19,22,104,105,110-119

a7ca1be

components: italicize parameters in VTSequence

78404bf

docs/vt: add OSC 52

4a6a129

pluiedev force-pushed the pluie/jj-poqplzsntrln branch from 8fb52d4 to 4a6a129 Compare November 21, 2025 16:20

00-kat suggested changes Nov 22, 2025

View reviewed changes

mitchellh merged commit d3b82df into ghostty-org:main Dec 2, 2025
2 of 3 checks passed

	terminator = "0x1B" "0x5C"
	terminator = "0x1B" "0x5C" \| "0x07"

		Below is a list of protocols that Ghostty supports, which originate from other
		terminal emulators:

	description: All sorts of information regarding colors in terminal emulation.
	description: Assorted information about colors in terminals.

	corresponding to 4, 8, 12 or 16 bit color channels respectively.
	corresponding to 4, 8, 12, or 16 bit color channels respectively.

	corresponding to 4, 8, 12 or 16 bit color channels respectively.
	corresponding to 4, 8, 12 and 16 bit color channels respectively.

docs/vt: document a bunch of OSCs #399

docs/vt: document a bunch of OSCs #399

Uh oh!

Conversation

pluiedev commented Nov 21, 2025

Uh oh!

vercel bot commented Nov 21, 2025

Uh oh!

00-kat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mitchellh commented Dec 2, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants