Copying all data types to the clipboard#

There already exists an escape code to allow terminal programs to read/write plain text data from the system clipboard, OSC 52. kitty introduces a more advanced protocol that supports:

  • Copy arbitrary data including images, rich text documents, etc.

  • Allow terminals to ask the user for permission to access the clipboard and report permission denied

The escape code is OSC 5522, an extension of OSC 52. The basic format of the escape code is:

<OSC>5522;metadata;payload<ST>

Here, metadata is a colon separated list of key-value pairs and payload is base64 encoded data. OSC is <ESC>[. ST is the string terminator, <ESC>\.

Reading data from the system clipboard#

To read data from the system clipboard, the escape code is:

<OSC>5522;type=read;<base 64 encoded space separated list of mime types to read><ST>

For example, to read plain text and PNG data, the payload would be:

text/plain image/png

encoded as base64. To read from the primary selection instead of the clipboard, add the key loc=primary to the metadata section.

To get the list of MIME types available on the clipboard the payload must be just a period (.), encoded as base64.

The terminal emulator will reply with a sequence of escape codes of the form:

<OSC>5522;type=read:status=OK<ST>
<OSC>5522;type=read:status=DATA:mime=<base 64 encoded mime type>;<base64 encoded data><ST>
<OSC>5522;type=read:status=DATA:mime=<base 64 encoded mime type>;<base64 encoded data><ST>
.
.
.
<OSC>5522;type=read:status=DONE<ST>

Here, the status=DATA packets deliver the data (as base64 encoded bytes) associated with each MIME type. The terminal emulator should chunk up the data for an individual type. A recommended size for each chunk is 4096 bytes. All the chunks for a given type must be transmitted sequentially and only once they are done the chunks for the next type, if any, should be sent. The end of data is indicated by a status=DONE packet.

If an error occurs, instead of the opening status=OK packet the terminal must send a status=ERRORCODE packet. The error code must be one of:

status=ENOSYS

Sent if the requested clipboard type is not available. For example, primary selection is not available on all systems and loc=primary was used.

status=EPERM

Sent if permission to read from the clipboard was denied by the system or the user.

status=EBUSY

Sent if there is some temporary problem, such as multiple clients in a multiplexer trying to access the clipboard simultaneously.

Terminals should ask the user for permission before allowing a read request. However, if a read request only wishes to list the available data types on the clipboard, it should be allowed without a permission prompt. This is so that the user is not presented with a double permission prompt for reading the available MIME types and then reading the actual data.

Writing data to the system clipboard#

To write data to the system clipboard, the terminal programs sends the following sequence of packets:

<OSC>5522;type=write<ST>
<OSC>5522;type=wdata:mime=<base64 encoded mime type>;<base 64 encoded chunk of data for this type><ST>
<OSC>5522;type=wdata:mime=<base64 encoded mime type>;<base 64 encoded chunk of data for this type><ST>
.
.
.
<OSC>5522;type=wdata<ST>

The final packet with no mime and no data indicates end of transmission. The data for every MIME type should be split into chunks of no more than 4096 bytes. All the chunks for a given MIME type must be sent sequentially, before sending chunks for the next MIME type. After the transmission is complete, the terminal replies with a single packet indicating success:

<OSC>5522;type=write:status=DONE<ST>

If an error occurs the terminal can, at any time, send an error packet of the form:

<OSC>5522;type=write:status=ERRORCODE<ST>

Here ERRORCODE must be one of:

status=EIO

An I/O error occurred while processing the data

status=EINVAL

One of the packets was invalid, usually because of invalid base64 encoding.

status=ENOSYS

The client asked to write to the primary selection with (loc=primary) and that is not available on the system

status=EPERM

Sent if permission to write to the clipboard was denied by the system or the user.

status=EBUSY

Sent if there is some temporary problem, such as multiple clients in a multiplexer trying to access the clipboard simultaneously.

Once an error occurs, the terminal must ignore all further OSC 5522 write related packets until it sees the start of a new write with a type=write packet.

The client can send to the primary selection instead of the clipboard by adding loc=primary to the initial type=write packet.

Finally, clients have the ability to alias MIME types when sending data to the clipboard. To do that, the client must send a type=walias packet of the form:

<OSC>5522;type=walias;mime=<base64 encoded target MIME type>;<base64 encoded, space separated list of aliases><ST>

The effect of an alias is that the system clipboard will make available all the aliased MIME types, with the same data as was transmitted for the target MIME type. This saves bandwidth, allowing the client to only transmit one copy of the data, but create multiple references to it in the system clipboard. Alias packets can be sent anytime after the initial write packet and before the end of data packet.

Support for terminal multiplexers#

Since this protocol involves two way communication between the terminal emulator and the client program, multiplexers need a way to know which window to send responses from the terminal to. In order to make this possible, the metadata portion of this escape code includes an optional id field. If present the terminal emulator must send it back unchanged with every response. Valid ids must include only characters from the set: [a-zA-Z0-9-_+.]. Any other characters must be stripped out from the id by the terminal emulator before retransmitting it.

Note that when using a terminal multiplexer it is possible for two different programs to overwrite each others clipboard requests. This is fundamentally unavoidable since the system clipboard is a single global shared resource. However, there is an additional complication where responses form this protocol could get lost if, for instance, multiple write requests are received simultaneously. It is up to well designed multiplexers to ensure that only a single request is in flight at a time. The multiplexer can abort requests by sending back the EBUSY error code indicating some other window is trying to access the clipboard.