The kitty remote control protocol

The kitty remote control protocol is a simple protocol that involves sending data to kitty in the form of JSON. Any individual command of kitty has the form:

<ESC>P@kitty-cmd<JSON object><ESC>\

Where <ESC> is the byte 0x1b. The JSON object has the form:

{
    "cmd": "command name",
    "version": <kitty version>,
    "no_response": <Optional Boolean>,
    "payload": <Optional JSON object>,
}

The version above is an array of the form [0, 14, 2]. If you are developing a standalone client, use the kitty version that you are developing against. Using a version greater than the version of the kitty instance you are talking to, will cause a failure.

Set no_response to true if you don’t want a response from kitty.

The optional payload is a JSON object that is specific to the actual command being sent. The fields in the object for every command are documented below.

As a quick example showing how easy to use this protocol is, we will implement the @ ls command from the shell using only shell tools. First, run kitty as:

kitty -o allow_remote_control=socket-only --listen-on unix:/tmp/test

Now, in a different terminal, you can get the pretty printed @ ls output with the following command line:

echo -en '\eP@kitty-cmd{"cmd":"ls","version":[0,14,2]}\e\' | socat - unix:/tmp/test | awk '{ print substr($0, 13, length($0) - 14) }' | jq -c '.data | fromjson' | jq .

close-tab

Fields are:

match (default: None)

Which tab to close

self (default: False)

Boolean indicating whether to close the window the command is run in

close-window

Fields are:

match (default: None)

Which window to close

self (default: False)

Boolean indicating whether to close the window the command is run in

create-marker

Fields are:

match (default: None)

Which window to create the marker in

self (default: False)

Boolean indicating whether to create marker in the window the command is run in

marker_spec (optional)

A list or arguments that define the marker specification, for example: [‘text’, ‘1’, ‘ERROR’]

detach-tab

Fields are:

match (default: None)

Which tab to detach

target (optional)

Which OS Window to move the detached tab to

self (default: False)

Boolean indicating whether to detach the tab the command is run in

detach-window

Fields are:

match (default: None)

Which window to detach

target (optional)

Which tab to move the detached window to

self (default: False)

Boolean indicating whether to detach the window the command is run in

disable-ligatures

Fields are:

strategy (required)

One of never, always or cursor

match_window (optional)

Window to change opacity in

match_tab (default: None)

Tab to change opacity in

all (default: False)

Boolean indicating operate on all windows

env

Fields are:

env (required)

dictionary of environment variables to values. Empty values cause the variable to be deleted.

focus-tab

Fields are:

match (default: None)

The tab to focus

focus-window

Fields are:

match (default: None)

The window to focus

get-colors

Fields are:

match (default: None)

The window to get the colors for

configured (default: False)

Boolean indicating whether to get configured or current colors

get-text

Fields are:

match (default: None)

The tab to focus

extent (default: screen)

One of screen, all, or selection

ansi (default: False)

Boolean, if True send ANSI formatting codes

cursor (optional)

Boolean, if True send cursor position/style as ANSI codes

wrap_markers (optional)

Boolean, if True add wrap markers to output

self (default: False)

Boolean, if True use window command was run in

goto-layout

Fields are:

layout (required)

The new layout name

match (default: None)

Which tab to change the layout of

kitten

Fields are:

kitten (required)

The name of the kitten to run

args (optional)

Arguments to pass to the kitten as a list

match (default: None)

The window to run the kitten over

last-used-layout

Fields are:

match (default: None)

Which tab to change the layout of

all (default: False)

Boolean to match all tabs

launch

Fields are:

args (required)

The command line to run in the new window, as a list, use an empty list to run the default shell

match (default: None)

The tab to open the new window in

window_title (default: None)

Title for the new window

cwd (default: None)

Working directory for the new window

env (default: [])

List of environment variables of the form NAME=VALUE

tab_title (default: None)

Title for the new tab

type (default: window)

The type of window to open

keep_focus (default: False)

Boolean indicating whether the current window should retain focus or not

copy_colors (default: False)

Boolean indicating whether to copy the colors from the current window

copy_cmdline (default: False)

Boolean indicating whether to copy the cmdline from the current window

copy_env (default: False)

Boolean indicating whether to copy the environ from the current window

location (default: default)

Where in the tab to open the new window

allow_remote_control (default: False)

Boolean indicating whether to allow remote control from the new window

stdin_source (default: none)

Where to get stdin for thew process from

stdin_add_formatting (default: False)

Boolean indicating whether to add formatting codes to stdin

stdin_add_line_wrap_markers (default: False)

Boolean indicating whether to add line wrap markers to stdin

no_response (default: False)

Boolean indicating whether to send back the window id

marker (default: None)

Specification for marker for new window, for example: “text 1 ERROR”

ls

Fields are:

all_env_vars (default: False)

Whether to send all environment variables for ever window rather than just differing ones

new-window

Fields are:

args (required)

The command line to run in the new window, as a list, use an empty list to run the default shell

match (default: None)

The tab to open the new window in

title (default: None)

Title for the new window

cwd (default: None)

Working directory for the new window

tab_title (default: None)

Title for the new tab

window_type (default: kitty)

One of kitty or os

keep_focus (default: False)

Boolean indicating whether the current window should retain focus or not

remove-marker

Fields are:

match (default: None)

Which window to remove the marker from

self (default: False)

Boolean indicating whether to detach the window the command is run in

resize-os-window

Fields are:

match (default: None)

Which window to resize

self (default: False)

Boolean indicating whether to close the window the command is run in

incremental (default: False)

Boolean indicating whether to adjust the size incrementally

action (default: resize)

One of resize, toggle-fullscreen or toggle-maximized

unit (default: cells)

One of cells or pixels

width (default: 0)

Integer indicating desired window width

height (default: 0)

Integer indicating desired window height

resize-window

Fields are:

match (default: None)

Which window to resize

self (default: False)

Boolean indicating whether to close the window the command is run in

increment (default: 2)

Integer specifying the resize increment

axis (default: horizontal)

One of horizontal, vertical or reset

scroll-window

for unscrolling by lines.

Fields are:

amount (required)

The amount to scroll, a two item list with the first item being either a number or the keywords, start and end. And the second item being either ‘p’ for pages or ‘l’ for lines or ‘u’

match (default: None)

The window to scroll

send-text

Fields are:

data (required)

The data being sent. Can be either: text: followed by text or base64: followed by standard base64 encoded bytes

match (default: None)

A string indicating the window to send text to

match_tab (default: None)

A string indicating the tab to send text to

all (default: False)

A boolean indicating all windows should be matched.

exclude_active (default: False)

A boolean that prevents sending text to the active window

set-background-image

Fields are:

data (required)

Chunk of at most 512 bytes of PNG data, base64 encoded. Must send an empty chunk to indicate end of image. Or the special value - to indicate image must be removed.

img_id (required)

Unique uuid (as string) used for chunking

match (default: None)

Window to change opacity in

layout (default: None)

The image layout

all (default: False)

Boolean indicating operate on all windows

configured (default: False)

Boolean indicating if the configured value should be changed

set-background-opacity

Fields are:

opacity (required)

A number between 0.1 and 1

match_window (optional)

Window to change opacity in

match_tab (default: None)

Tab to change opacity in

all (default: False)

Boolean indicating operate on all windows

set-colors

Fields are:

colors (required)

An object mapping names to colors as 24-bit RGB integers

cursor_text_color (optional)

A 24-bit color for text under the cursor, or null to use background.

match_window (optional)

Window to change colors in

match_tab (default: None)

Tab to change colors in

all (default: False)

Boolean indicating change colors everywhere or not

configured (default: False)

Boolean indicating whether to change the configured colors. Must be True if reset is True

reset (default: False)

Boolean indicating colors should be reset to startup values

set-font-size

Fields are:

size (required)

The new font size in pts (a positive number)

all (default: False)

Boolean whether to change font size in the current window or all windows

increment_op (optional)

The string + or - to interpret size as an increment

set-spacing

Fields are:

settings (required)

An object mapping margins/paddings using canonical form {‘margin-top’: 50, ‘padding-left’: null} etc

match_window (optional)

Window to change colors in

match_tab (default: None)

Tab to change colors in

all (default: False)

Boolean indicating change colors everywhere or not

configured (default: False)

Boolean indicating whether to change the configured colors. Must be True if reset is True

set-tab-title

Fields are:

title (required)

The new title

match (default: None)

Which tab to change the title of

set-window-title

Fields are:

title (optional)

The new title

match (default: None)

Which windows to change the title in

temporary (default: False)

Boolean indicating if the change is temporary or permanent

signal-child

Fields are:

signals (optional)

The signals, a list of names, such as SIGTERM, SIGKILL, SIGUSR1, etc.

match (default: None)

Which windows to change the title in