This is described at https://rockorager.dev/misc/bracketed-paste-mime/ however the protocol described differs from kitty's actual behavor. This document is based on the linked page and has been modified to match Kitty's implementation of the protocol.
The main OSC 5522 spec can be found here: https://sw.kovidgoyal.net/kitty/clipboard/
Detection is performed with a standard DECRQM query:
CSI ? 5522 $ p
To which the terminal will respond with a DECRPM response:
CSI ? 5522 ; Ps $ y
A Ps value of 0 or 4 means the mode is not supported. Reference
The mode can be enabled using DECSET or DECRST control sequences:
CSI ? 5522 h to enable the mode. CSI ? 5522 l to disable the mode.
When this mode is enabled and the user performs a paste operation, the terminal sends an unsolicited list of available MIME types from the clipboard location that caused the paste using the standard Kitty clipboard protocol response format (as if it had received a read request with a base64-encoded period . as the MIME type). The terminal SHOULD also generate a single-use password (token) for this paste event.
Terminal -> Application:
OSC 5522 ; type=read:status=OK[:loc=primary][:pw=<base64 password>] ST
OSC 5522 ; type=read:status=DATA:mime=<base64 `.`> ; <base64 MIME list> ST
[... Additional DATA packets if needed for chunking ...]
OSC 5522 ; type=read:status=DONE ST
Where:
- OSC is ESC ] (0x1b 0x5d)
- ST is ESC \ (0x1b 0x5c)
- is the base64-encoded space seperated list of available MIME types (e.g., dGV4dC9wbGFpbg== for text/plain)
- loc=primary, when present, identifies the primary selection as the clipboard location that caused the paste. When loc is omitted, the paste came from the default system clipboard.
- is a base64-encoded single-use password/token generated by the terminal
- <base64
.> isLg==
The application then makes an explicit read request for the desired MIME type using the standard Kitty clipboard protocol, including the password token when one was provided, and reading from the same clipboard location. Per the Kitty spec a human friendly name is required when a password is used and it SHOULD be set to Paste event when using a password token provided by a paste event. The application is free to request mulitple MIME types in its read request and the terminal SHOULD provide all requested MIME types available on the clipboard as defined by the standard Kitty clipboard protocol. The terminal MUST ignore any unavailable MIME types without invalidating the request provided at least one requested MIME type is available.
Application -> Terminal:
OSC 5522 ; type=read:pw=<base64 password>:name=<base64 name>[:loc=primary] ; <base64 MIME list> ST
Terminal -> Application:
OSC 5522 ; type=read:status=OK ST
OSC 5522 ; type=read:status=DATA:mime=<base64 MIME type> ; <base64 data> ST
[... additional DATA packets if needed for chunking ...]
OSC 5522 ; type=read:status=DONE ST
Where is the base64-encoded clipboard content, chunked to a maximum of 4096 bytes before encoding
When this mode is enabled and a paste event occurs, the terminal MUST send an unsolicited response as if it received a Kitty clipboard read request with a base64-encoded period (.) as the MIME type. This sends a list of available MIME. The terminal SHOULD also include a pw field in the OK response containing a unique, single-use token for this paste event. The terminal MAY also include the pw field in the DATA and DONE packets of this paste event. If the paste event came from the primary selection, the terminal MUST also include loc=primary in the OK response. If the paste event came from the default system clipboard, the terminal MUST omit loc.
When enabled, this mode takes precedence over standard bracketed paste mode (2004). Terminals MUST NOT send both sequence types for the same paste event.
If both mode 5522 and mode 2004 are enabled, the terminal MUST use mode 5522.
Terminals implmenting paste events that conform to this specification MUST also support the entirety of the Kitty Clipboard Extension (OSC 5522).
This mode enables unsolicited MIME type listings on paste events. However, it does not introduce new security concerns beyond the existing Kitty clipboard protocol (OSC 5522):
- Single-Use Password: To prevent clipboard sniffing while avoiding repetitive confirmation prompts, the terminal
can generate a cryptographic single-use password for each paste event.
- The password is sent in the pw field with the initial unsolicited MIME list.
- The application should include this password when requesting the clipboard content.
- If a password was provided and it matches the one generated for the current paste event, the terminal MUST return the clipboard data without prompting the user for confirmation.
- The password MUST be scoped to the clipboard location that caused the paste event and MUST NOT authorize reads from any other clipboard location.
- The password MUST be invalidated after use or after a short timeout.
- If the application requests data without the password or with an invalid password, the terminal SHOULD fall back to its standard security behavior (e.g., prompting the user).
- Note that Kitty will ignore requests that have a pw but do not include the name field
- MIME type listings reveal only the format types available, not the actual clipboard content
- The existing OSC 5522 specification does not require permission prompts for listing MIME types
- Actual clipboard data is only transmitted when the application explicitly requests it via OSC 5522 read requests
Terminals SHOULD apply the same security policies for this mode as they do for the standard Kitty clipboard protocol. Applications MUST validate MIME types and sanitize clipboard data appropriately before processing.
Using pw: secret123 (base64: c2VjcmV0MTIzCg==)
When a paste event occurs the terminal sends:
\x1b]5522;type=read:status=OK:pw=c2VjcmV0MTIzCg==\x1b\\
\x1b]5522;type=read:status=DATA:mime=Lg==:pw=c2VjcmV0MTIzCg==;dGV4dC9wbGFpbiBpbWFnZS9wbmcK\x1b\\
\x1b]5522;type=read:status=DONE:pw=c2VjcmV0MTIzCg==\x1b\\
dGV4dC9wbGFpbiBpbWFnZS9wbmcK decodes to text/plain image/png\n
Note that the list of MIME types provided by Kitty ends with a newline. This is not required when replying to the terminal, nor is it defined by the spec. Decoders should not be dependent on the newline being present.
The application requests the text/plain content using the password token:
\x1b]5522;type=read:pw=c2VjcmV0MTIz:name=UGFzdGUgZXZlbnQ=;dGV4dC9wbGFpbg==\x1b\\
Inital vertion written based on Kitty 0.47.1 on 2026-06-10