Kitty Graphics Protocol

KGP implements the Kitty Graphics Protocol, a terminal escape sequence specification for rendering pixel-based graphics.

Escape Sequence Format

Commands use the APC (Application Program Command) sequence:

ESC_G<control-data>;<payload>ESC\
  • Start: \x1b_G (ESC followed by G)
  • Control data: Comma-separated key=value pairs
  • Payload: Base64-encoded binary data (when applicable)
  • End: \x1b\ (ESC followed by backslash)

Actions

ActionCodeDescription
TransmittUpload image data without displaying
Transmit & DisplayTUpload and display image
PutpCreate placement of existing image
DeletedRemove images or placements
FramefAdd animation frame
AnimateaControl animation playback
ComposecCompose animation frames
QueryqQuery terminal capabilities

Control Data Keys

Common Keys

KeyDescriptionUsed By
aAction typeAll
iImage IDTransmit, Put, Delete, Frame, Animate, Compose
IImage number (non-unique)Transmit, Put, Delete
pPlacement IDTransmit, Put, Delete
fFormat (24, 32, 100)Transmit, Frame
s, vWidth, height (dimensions)Transmit, Frame, Query
tTransmit medium (d, f, t, s)Transmit, Query
oCompression (z = zlib)Transmit
qResponse suppression (0, 1, 2)All
dDelete modeDelete

Placement Keys

KeyDescription
c, rDisplay size (columns, rows)
X, YCell offset within starting cell (pixels)
x, y, w, hSource rectangle (crop)
zZ-index (negative = below text)
CCursor movement (0=move, 1=no move)
P, QParent image/placement for relative positioning
H, VHorizontal/vertical offset for relative positioning
UVirtual placement (Unicode placeholder)

Frame Keys (action=f)

KeyDescription
rFrame number to edit (omit to create new frame)
zFrame gap (ms)
cBackground frame number
XComposition mode (0=blend, 1=replace)
YBackground color (32-bit RGBA)

Animate Keys (action=a)

KeyDescription
sAnimation state (1=stop, 2=loading, 3=loop)
vLoop count (0=ignored, 1=infinite, N>1=loop N-1 times)
zGap override (ms)
cFrame number (used with stop state)

Compose Keys (action=c)

KeyDescription
rSource frame number
cDestination frame number
x, y, w, hSource rectangle
X, YDestination offset (pixels)
CComposition mode (0=blend, 1=replace)

Response Format

Terminal responses follow:

ESC_Gi=<id>[,I=<num>][,p=<pid>];[OK|ERROR_CODE:message]ESC\

Parse with kgp.ParseResponse().