Terminal compatibility

Afterglow targets Linux and Wayland with Vulkan. The terminal core in libs/afterglow-vt parses the protocols. The message formats of file transfer, drag and drop, graphics and clipboard are in libs/afterglow-proto. Renderer tests also check GPU pixels. The table below lists the protocols that Afterglow supports, each with the tests that check it. Differences from other terminals lists what Afterglow does in another way on purpose. Safety limits lists the limits that keep a program from taking all the memory or time of the terminal.

Supported protocol features

FeatureSupported behaviorRegression and interoperability fixture
Kitty relative imagesP, Q, signed H/V; parent movement; chained parents; cascade deletion; missing-parent, cycle and depth errors; virtual placeholder parentsGraphics.Relative*, Graphics.TransmitAndPlaceReportsInvalidRelativeParent and transmit/placeholder pixel regressions; moving-image client
Kitty multiple cursorsShapes 1/2/3/29, clear 0, coordinate types 0/2/4, color operations 30/40, capabilities and queries 100/101; clipping, reset, clear, alternate-screen lifecycle; blink and mixed shape renderingExtensions.MultipleCursor*, Extensions.ExtraCursorColors*, Extensions.ResizeClipsExtraCursorsToTheScreen, Terminal.ExtraCursorsAreBounded, Terminal.ResizeClipsExtraCursorsToTheClampedSize, SnapshotCursor.*, Render.MultipleCursors*; multi-edit client
OSC 1337 downloadsFile, MultipartFile, FilePart, FileEnd; a question before the data, as in iTerm2, while the program waits; data of any size streamed to the fileExtensions.ADownload*, Extensions.DownloadsEndCompleteOnlyWithValidDataOfTheirSize, Extensions.MultipartDownloadsStreamTheirParts, PaneDownload.*, MuxAttach.ADownloadAsksTheWindowAndStreamsItsData, NativeWindow.ADownloadAsksBeforeItsDataAndSavesInTheDownloadFolder, desktop_acceptance.py; download client, upstream it2dl
OSC 1337 uploadsRequestUpload=format=tgz: a question, then a file picker. The program gets ok, the archive in base64 lines and an empty line as typed input, as iTerm2 answers. When you refuse, it gets Ctrl+C, as iTerm2 sends it. A request that Afterglow refuses without a question, or a format other than tgz, gets no answer.Terminal.AnUploadRequestThatNoHostTakesGetsNoAnswer, UploadArchive.*, MuxAttach.AnUploadRequestGoesToTheWindowOrGetsNothing, MuxAttach.TheNextWindowAsksForAnUploadThatTheLastOneDidNotAnswer, NativeWindow.AProgramThatAsksForFilesGetsTheArchiveOrCtrlC; upstream it2ul
IME contextLive cursor-row surrounding text, before/after text, UTF-16 position and cursor rectangleDesktopText.*; IME behavior
Native terminal accessibilityViewport text, cursor, selection and character geometry through Qt/AT-SPI; pane actions, the pane menu and docked-area buttonsDesktopText.*, NativeWindow.Accessible*, desktop_acceptance.py; accessibility
Local file dropLocal absolute paths quoted for Bash/Zsh/Fish, targeted pane, bracketed paste, no automatic EnterFileDrop.*; file-drop workflow
Text drop and selection dragDropped text pasted with the size limit and the question of a paste, selected text dragged to another pane or application (Mouse.dragSelection)NativeWindow.Dropped*, NativeWindow.DropsThatAPaneRefusesPasteNothing, NativeWindow.ASelection*, NativeWindow.*InsideTheSelection*; text drops, selection drag
Kitty indexed imagesf=8 and f=16; the special indices 248 to 255; a new color of the pane draws the image again; no framesGraphics.Indexed*, Render.IndexedImages*, SnapshotImages.Indexed*; indexed images
Kitty graphicsTransmission inline, from a file, a temporary file and shared memory; PNG, raw and zlib data; placements, z-order, animation and composition; Unicode placeholders; feature queries (a=q, e)Graphics.*, Render.*; afterglow_kitten_icat with kitten icat
Kitty keyboard protocolFlags 1, 2, 4, 8 and 16; push, pop, set and query, with a stack for each screen that DECSTR clears; event types, alternate keys with the base layout key, and associated text; AltGr and the fifth level key (ISO_Level3_Shift, ISO_Level5_Shift), and the media and volume keys that reach the windowTerminal.KittyKeyboardStack*, Input.*, KeyMapping.BaseLayoutKeysLevelKeysAndHeldModifiers; keyboard protocols
Kitty text sizing (OSC 66)Scale, width, fraction and alignment; the erase, scroll, overwrite and insert and delete rules of the specificationTextSizing.*
Kitty color control (OSC 21), color stack (OSC 30001, 30101), pointer shapes (OSC 22)See color escape codes and pointer shapesExtensions.PointerShapeStacksQueriesAndReset, Extensions.OklchAndLabColorsInTheColorEscapeCodes, Conformance.ColorStack
Kitty notifications (OSC 99), with OSC 9 and OSC 777Chunks, icons with one icon cache (g) for the whole application that keeps the 32 icons used last, buttons, sounds, close and activation reports, the capability query; filter rules as Kitty’s filter_notification (Notifications.filters)Notification.*, Extensions.LegacyNotificationsRejectControlsAndBadUtf8, ConfigTest.NotificationFilterRules, NativeWindow.NotificationReplacementAndApplicationImageCache, NativeWindow.NotificationFiltersDropWhatTheyMatch; hide notifications
Kitty clipboard (OSC 5522), OSC 52 and paste events (mode 5522)Several MIME types, passwords for reads and writes, the primary selectionClipboard.*, Clipboard.PasteEventsModeIsReported, NativeWindow.KittenClipboard*, NativeWindow.AnAllowedClipboardPasswordAllowsLaterWrites
Kitty file transfer (OSC 5113), drag and drop (OSC 72)See Kitty file transfer and Kitty drag and dropTransfer.*, Dnd.*, afterglow_transfer_kitten_relay, NativeWindow.Kitty*
Shell integration (OSC 133 and OSC 633), contexts (OSC 3008), the working directory (OSC 7)Prompt, command and output marks, click_events=1 and click_events=2, special_key=1, the secondary prompt (k=s), redraw, cmdline and cmdline_url; the context stack; file:// directoriesTerminal.ShellIntegrationCommands, Extensions.VSCodeShellIntegration, Extensions.SystemdContexts, Terminal.WorkingDirectoryReportsOnlyChanges
Program status (OSC 7501), ConEmu progress and directory (OSC 9;4, OSC 9;9)Status, progress and the working directoryProgramStatus.*, Extensions.ConEmuCommands
iTerm2 (OSC 1337)File with animated GIF, WebP and APNG images, MultipartFile, FilePart, FileEnd, SetUserVar, CurrentDir, ClearScrollback, ReportCellSize, SetMark, RemoteHost, Copy, RequestAttention, CursorShapeExtensions.ITerm2Commands, Extensions.ITerm2AnimatedImagesPlayAndLoop, PaneAnimation.AnITerm2GifPlaysThroughThePanesDecoder, Extensions.ITerm2SetMarkMarksTheCursorRowOnTheMainScreen, Extensions.Downloads*, Terminal.BellsRingOnlyForBel
Hyperlinks (OSC 8)Links with and without an id, across wrapped lines and reflowReflow.StyleAndLinkRunAcrossWrapsKeepItsReferences, StateSync.TextStylesLinksAndText
Window operations (XTWINOPS)4 and 8 (resize), 11 and 13 (state and position), 14, 15, 16, 18 and 19 (sizes in pixels and cells), 22 and 23 (title stack), 24 or more (DECSLPP)Terminal.Reports, Terminal.TitleStackPushesAndPops, Extensions.PixelReportsAndImagePercentagesUseWideGeometry
Status reportsDA1, DA2, DA3, XTVERSION, DECRQM, DECRQSS, XTGETTCAPTerminal.Reports, Conformance.TertiaryAttributesAndTerminalParameters, Terminal.XtversionReportsTheProjectVersion, Conformance.ModeReports, Terminal.Decrqss, Terminal.Xtgettcap
Mouse modes9, 1000, 1002, 1003 and 1004 (focus); the formats 1005, 1006, 1015 and 1016 (SGR pixels), with Kitty’s event when the pointer leaves a pane; 1007 (alternate scroll)Input.MouseLegacyFormats, Terminal.MouseFormatResetsOnlyItsOwn, Input.*, NativeWindow.APaneLearnsThatThePointerLeftIt
Synchronized outputMode 2026, and DCS = 1 s and DCS = 2 sConformance.EachSynchronizedBlockHasItsOwnSerial, Conformance.LegacySynchronizedUpdatesAndFlash
Grapheme clusters, color scheme, visibility and size reportsModes 2027, 2031 with CSI ? 996 n, 2033 and 2048Conformance.ThemeVisibilityAndSizeReports, character widths
Color and mode stacksXTPUSHCOLORS, XTPOPCOLORS, XTREPORTCOLORS; XTSAVE and XTRESTORE, without modes for the modes that have no side effects, as in KittyConformance.ColorStack, Conformance.SaveAndRestoreModes, Terminal.XtsaveWithoutModesSavesTheQuietModes
SixelTransparent backgrounds (P2 = 1), XTSMGRAPHICSSixel.*, Extensions.SixelThroughTheTerminal, Conformance.SixelGraphicsAttributesHonourTheAction
Text attributesCurly, dotted and dashed underlines and underline colors (SGR 4:x, 58, 59); Kitty’s SGR 221 and 222 (bold or faint off alone); ED 22; DECCARA with every SGR code, as Kitty extends it, and DECRARATerminal.SgrColorsAndAttributes, Conformance.KittyBoldOffAndFaintOffAlone, Terminal.EraseDisplay22MovesTheScreenIntoTheHistory, Conformance.RectangleAttributes, Conformance.RectangleAttributesTakeEverySgrCode
Kitty unscroll (CSI n + T)SD that fills the new lines from the scrollbackTerminal.UnscrollFillsTheTopFromTheScrollback

Relative images

Relative placement chains permit 32 parent links.

An omitted parent placement ID selects the first matching placement at creation. Displayed Unicode placeholders determine a virtual parent’s origin, including implied diacritics. Afterglow hides the children when it displays no parent placeholders. Scrolling or resizing can change the anchor. Parent offsets use cells. X and Y remain the child’s pixel offsets. Relative placements do not move the terminal cursor.

Image lifetime and scrolling

EventResult
Lowercase Kitty delete (d=a, d=i and the others)The placements go. Image data with an ID or a number stays, also the data of child images.
Last placement of an image without an ID or a number goesThe image data goes. Sixel and iTerm2 images do the same.
ED 2 (erase the screen)Images that reach into the screen go, also when their top row is in the scrollback.
ED 22 (move the screen into the scrollback, then erase it, as in Kitty)The lines down to the last line with text go into the scrollback with their images. Then ED 2 erases the screen. On the alternate screen, or with a scrolling region, ED 22 is the same as ED 2.
ED 3 (erase the scrollback)Images whose top row is in the scrollback go. Images on the screen stay, like the text.
EL, ED 0 and ED 1 (erase part of a line or of the screen)Kitty images stay, as the Kitty specification says: a program deletes them with the delete commands. A program that draws over a Kitty image without the alternate screen, such as top, leaves it on the screen, as in Kitty. Sixel and iTerm2 images whose cells overlap the erased cells go, as xterm erases its graphics with their cells. Selective erases (DECSEL, and DECSED 0 and 1) leave all images.
SU, SD, IL, DL, or a line feed or reverse index at a scroll-region marginAn image whose top-left cell is in the region moves with its rows. With a region smaller than the screen, only a Kitty image that lies entirely inside the region moves, as the Kitty specification says. One that reaches past a margin stays. Sixel and iTerm2 images in the region always move. An image that moves shows only its rows that are in the region after the scroll. It goes when none of its rows is in the region. Rows below the last row of the screen stay when the scroll is up: they come into view as the image moves. A relative child image moves with its parent, and the same rule cuts it. It goes when its parent goes.
Unscroll (CSI n + T, as in Kitty)The rows that it pushes out at the bottom of the screen go with all their images.

The same scrolls move shell-integration marks (OSC 133) with their rows. A command or prompt region goes when its start or end leaves the scroll region. A selection moves when a full-width scroll region holds all of it. Afterglow clears the selection when the scroll region holds only part of it. It also clears the selection when a region with left and right margins holds any of it. With left and right margins, only images and marks in those columns move.

Afterglow stores an iTerm2 inline image at its own size, or at the requested size when that is smaller. The renderer enlarges it to the requested size, within the limits in Sixel, iTerm2 and escape strings. An animated GIF, WebP or APNG plays and loops while it shows, as in iTerm2 and WezTerm. A frame of 10 ms or less shows for 100 ms, as browsers play old GIFs. An animation keeps at most 1,024 frames, and its frames together fit in Graphics.quota: it stops at the last frame that fits.

A pane decodes the images that programs send in processes of their own: PNG data of Kitty graphics, and iTerm2 images. aglow-mux --decode-images, next to afterglow, starts these processes. Each process has limits on its memory, its time and the system calls that it can make (see images that a pane decodes). Without aglow-mux, these images do not show, and Afterglow writes a warning in its log once. A long animation can stop at the frame where the limit of its process stops it. A pane converts an image with an ICC color profile or a cICP color space to sRGB, as Kitty applies the profile of a PNG.

To refuse Kitty transmissions from files, temporary files and shared memory (t=f, t=t, t=s), set Terminal.graphicsFileTransfer to "deny". The program then gets an EPERM error, and Afterglow opens no file. Inline transmissions (t=d) always work.

Afterglow deletes a temporary file (t=t) only when it is below /tmp, /dev/shm or $TMPDIR, and its path below that directory holds tty-graphics-protocol. Afterglow keeps every other file that a command names. Afterglow deletes the shared memory object of a command (t=s) when it has read it or refused the command, whatever its name, as the Kitty specification says. kitten icat names its objects /icat- and a random suffix.

A read from a file or shared memory that fails gives the error EBADF:failed to read image file. These cases give that error:

  • The file or object does not exist, or it is not a regular file.
  • The file is in /proc, /sys or /dev, except /dev/shm.
  • The name is longer than 4,096 bytes.
  • The file holds less data than s × v raw or indexed pixels.
  • The data is PNG (f=100) or compressed (o=z), and the part to read is longer than 320 MiB.

With both c and r, an image keeps its aspect ratio in those cells, centered, as the Kitty specification says. X and Y then add no cell to the c × r cells. The cursor moves past them, and delete commands by cell find the image in them. A feature query (a=q with e) gets the keys of that action that Afterglow supports. The transient usage hint (N=1) applies to a transmission (a=t, a=T). It does not apply to a frame (a=f). When Afterglow must delete an image to make room, it first deletes an image with the hint that has no placement. A feature query reports N for the transmit and query actions. The delete commands d=f and d=F delete one frame of an animation for each command. The r key selects the frame (the first frame is 1). Without r, the command deletes the first frame. On an image with one frame, d=F deletes the image, and d=f keeps it.

Indexed images

An indexed image (f=8 or f=16) holds palette indices, so it follows the colors of the pane. When the colors of the pane change, Afterglow draws the image again in the new colors. A theme, OSC 4 and OSC 21 are examples of such a change. With f=8, every pixel is opaque. With f=16, the second byte of each pixel is its alpha.

IndexColor
0 to 247Entries 0 to 247 of the 256-color palette
248The default background. Window.backgroundOpacity does not apply to it.
249The default foreground
250The selection background, or the default foreground when no setting or program sets it
251The selection foreground, or the default background when no setting or program sets it
252The cursor color, or the default foreground when no setting or program sets it
253The cursor text color, or the default background when no setting or program sets it
254The default foreground. Afterglow underlines a link under the pointer in its text color. Afterglow has no link hover color.
255The default foreground (reserved)

In reverse video (DECSCNM), 248 and 249 change places, as the default colors do. An indexed image has one frame. A frame action (a=f) or a composition (a=c) on an indexed image gets the error EINVAL:indexed images have no frames. A frame action with f=8 or f=16 on an image that exists gets the same error. A feature query reports f=8 and f=16 for the transmit and query actions.

Multiple cursors

Color operations 30 (text), 40 (fill) and query 101 are supported.

Color spaceBehavior
0Follow the main cursor.
1Reverse the relevant cell colors.
2Use RGB components.
5Use a palette entry.

All extra cursors share color settings. Each cell resolves those settings, including palette changes. Reverse fill uses the cell foreground for fill and the cell background for text. It overrides the explicit text-color choice. Capability queries return 1;2;3;29;30;40;100;101. Clients must inspect the response. Query 100 gives the cursors as rectangles (type 4). A run of cursors on one row is one rectangle. Equal runs on the rows below join it. A cursor alone is a point (type 2).

Full reset restores default colors. Clear and screen switches remove positions. Positions use screen coordinates and do not scroll with output. Cursors disappear while viewing scrollback. Resize clips positions to the screen.

Separate layers keep block text readable and beams above glyphs. With layer shaders, mixed cursor order requires one additional RGBA8 frame texture. This costs approximately 7.9 MiB at 1080p or 31.6 MiB at 4K. A second cursor shader pass runs only when opposite drawing orders are required. Persistent cursor buffers retain separate history per layer within the shared allocation limit.

OSC 99 notification bodies can contain more than one line. Tabs become spaces. OSC 9 and OSC 777 notification text gets the same check as OSC 99 text. The text must be valid UTF-8 with no C0, DEL or C1 control characters. Afterglow ignores a notification that fails the check. When Notifications.enabled is off, the OSC 99 query (p=?) gets no answer, as from a terminal without the protocol. The Kitty specification tells a program to read that as no support. A base64 payload can be divided at any character between chunks. OSC 0 and OSC 2 titles lose C0, DEL and C1 controls, U+2028, U+2029 and the controls of bidirectional text. A byte that is not UTF-8 becomes U+FFFD. A C1 control sent as UTF-8 (U+0080 to U+009F) prints nothing.

The command line keeps no control characters except line feeds and tabs. A byte that is not UTF-8 becomes U+FFFD. A command that erases the whole screen (ED 2) moves the start of its output to the top of the screen. OSC 3008 contexts form a stack. A start for a context that is open ends the contexts inside it. A terminal reset (RIS or the Reset command) keeps the context stack, as the context specification requires.

Downloads, input methods and bidirectional text

A new MultipartFile, a terminal reset or the end of the pane’s program ends a file that has no FileEnd. A new shell prompt is a prompt mark (OSC 133 A or N, or OSC 633 A) after a command start mark (C). One new prompt does not end the file, because a job in the background can still send it. A second new prompt with no FilePart after the first ends it, because the program that sent it has stopped. A prompt mark with no C before it does not count, because a shell sends it each time it draws the same prompt again. A command end mark (D) does not make a new prompt. The Bash and Zsh integration of Afterglow sends it after each command, also after Enter on an empty line. With a shell that sends no C mark, no prompt ends a file. A new MultipartFile, a terminal reset or the end of the pane’s program still ends it. In a mux session, a download goes to the window that shows the session, with the other requests of the session. Without a window, the mux session refuses the download (see what the daemon answers). OSC 1337 downloads are not resumable. A program asks for files with OSC 1337 RequestUpload (see send files to a terminal application). Afterglow supports the Kitty file-transfer protocol separately. See Kitty file transfer. IME context does not permit arbitrary surrounding-text edits. Optional bidirectional layout of the main screen has application-grid exclusions and bounded paragraph processing. See bidirectional text.

Character widths

The widths come from Unicode 18.0. Afterglow joins characters into grapheme clusters as UAX #29 says, when grapheme clustering (mode 2027) is on, which is the default. A cluster takes the cells that glibc’s wcwidth gives its characters, but no more than two. Shells and editors measure text with wcwidth, so the cursor stays where they expect it.

TextCellsKitty
A wide emoji, then VS15 (U+FE0E)11
A text emoji, then VS16 (U+FE0F)22
A letter and a spacing mark (Hindi का, Tamil கா)21
A conjunct: a consonant, a virama and a consonant (Hindi क्र)21
Thai SARA AM or Lao AM after a letter22
A prepended mark (U+0600 to U+0605, U+06DD, U+070F, U+0890, U+0891, U+08E2, U+110BD, U+110CD)10

tools/conformance/ucs-detect.sh measures the widths with ucs-detect. See TESTING.md.

Color escape codes and pointer shapes

OSC 21 supports the Kitty color-control protocol. Programs can set, query and reset palette colors and dynamic colors. OSC 4, OSC 10 to 12, OSC 17, OSC 19 and OSC 21 take the same color values:

ValueExample
An X11 color name, in any casered, dark slate gray
A hexadecimal color, as xterm reads it#rgb, #rrggbb, #rrrgggbbb, #rrrrggggbbbb
An rgb: or rgbi: valuergb:ff/80/00, rgbi:1/0.5/0
An OKLCH or CIE LAB color, as CSS Color 4 writes itoklch(0.7 0.1 200), lab(50 60 40)

In the escape codes, each digit of #rgb gives the high bits of its channel, as in xterm, so #fff is #f0f0f0. In Colors and in themes, #fff is white. Color values gives the values of oklch and lab. A query reports such a color as the sRGB color that Afterglow set. Afterglow converts these colors with the sample code and the gamut mapping of CSS Color 4. Kitty reads some colors in a different way:

ColorKittyAfterglow
#rgb in an escape code#fff is white.#fff is #f0f0f0, as in xterm.
OKLCH or LAB outside sRGBClips each channel.Decreases the chroma until the clipped color is less than one just noticeable difference (deltaE OK 0.02) away.
LABOther values, for example a middle gray for lab(10 0 0).The values of CSS Color 4.
A percentage of CA percentage of 1.A percentage of 0.4, as in CSS Color 4.
A percentage of a or bIgnores the %.A percentage of 125, as in CSS Color 4.

Kitty and Afterglow both ignore an alpha, such as oklch(0.7 0.1 200 / 0.5). Cursor text, visual-bell color and eight transparent-background slots affect rendering. Transparent slots support an explicit opacity or the configured window opacity. The color stack saves and restores these settings. Unknown color keys produce the protocol’s encoded unknown response.

OSC 22 supports the Kitty mouse-pointer protocol. Programs can replace, push, pop and query shapes. All protocol shape names are supported, including zoom, cell and vertical-text pointers. A terminal reset clears the stacks of both screens and restores the default text pointer.

aglow interoperability

aglow is a client of four Kitty protocols: file transfer, drag and drop, graphics and the clipboard. It does not need Kitty. aglow run, which runs the commands of scripts, uses no Kitty protocol and has no counterpart in kitten. When AFTERGLOW_SOCKET names no socket on its own computer, aglow run asks the terminal for the socket of an ssh session. It asks with OSC 24569, which is Afterglow’s own. The aglow client tells how to use it. Its message formats come from libs/afterglow-proto, the same code that the terminal uses.

CommandProtocolInteroperability checks
aglow transferFile transfer (OSC 5113): directories, links, permissions, times, zlib, deltas and the SHA-256 password formAgainst the Afterglow service in process (Client.*). Through a pseudo-terminal, also with --confirm-paths. Against Kitty 0.49.2 (kitty_transfer_interop.py). Against a hostile terminal (Proto.Hostile.*)
aglow dndDrag and drop (OSC 72): MIME data, copy and move, remote directory trees in both directionsAgainst Afterglow in a nested KWin (NativeWindow.Aglow*). As the target or source of a remote drag (AglowDrop.*, AglowDrag.*). With the question that lists the files before a drop replaces them (AglowOverwrite.*)
aglow icatGraphics (APC G): PNG as it is, other formats as pixels, GIF, WebP and APNG animation frames, Unicode placeholders, tmux passthrough; an ICC profile or a cICP color space converted to sRGBaglow_icat_render draws its output with the Afterglow renderer. aglow_icat_decode checks the pixels of crafted images, and the first frame of a GIF over the 320 MiB budget. aglow_icat_external checks the formats that go to ImageMagick and the downloads of URLs, with a fake magick and curl. aglow_tmux_pty runs it in a private tmux server, with allow-passthrough on and off.
aglow runThe socket query of a remote host (OSC 24569), with the DA1 guard and tmux passthroughAgainst a terminal and a socket that a test plays (aglow_run_pty). Also in a private tmux server (aglow_tmux_pty). Through sshd run as the user (RemoteCommandsTest.*)
aglow clipboardClipboard (OSC 5522), and OSC 52 for plain text in a terminal without OSC 5522Against a terminal that a test plays (aglow_clipboard_pty, aglow_clipboard_cases), and the message formats in libs/afterglow-proto/tests

aglow transfer, aglow dnd, aglow icat and aglow clipboard take the options of the kitten command of the same name, with the differences below.

  • aglow transfer sends the permission password only in the SHA-256 form, which Afterglow and Kitty accept. It does not use Kitty’s own form, which encrypts the password with KITTY_PUBLIC_KEY.
  • aglow icat decodes PNG, APNG, JPEG, GIF, WebP, BMP, TIFF and netPBM images itself, with any --engine. It uses libpng, libjpeg-turbo, libwebp and readers of its own. It sends only the other formats to ImageMagick, on standard input and with a policy of its own. These are AVIF, HEIC, JPEG XL, QOI, SVG, TGA, ICO and CUR. They also include a BMP with JPEG or PNG data, and a BMP with run-length encoding that does not fit its depth. aglow reads RLE8 only at 8 bits and RLE4 only at 4 bits. --engine magick is the same as --engine auto. aglow icat shows the first frame of an animation in such a format.
  • aglow icat downloads URLs with curl, which must be installed, where kitten icat has its own HTTP client.
  • aglow icat converts an image with an embedded color profile (ICC) or a cICP color space to sRGB. It uses Little CMS, as the builtin engine of kitten icat does. It converts only an RGB profile of a color image, of at most 4 MiB. A PNG that it sends as it is keeps its profile, for the terminal. The two can differ by 1 in a sample. An Adobe RGB JPEG of 100,150,200 gives 66,151,202 in kitten icat, and 66,151,203 in aglow icat and in Pillow.
  • cICP: the primaries BT.709, BT.2020 and Display P3, with the sRGB, linear, PQ and HLG transfers, in full range. PQ and HLG map 203 cd/m², their reference white (BT.2408), to the white of sRGB, and clip what is brighter. Other cICP values leave the pixels as they are.
  • aglow icat accepts --silent and ignores it, as kitten icat does.
  • aglow icat compresses pixels with zlib only when it sends them through the terminal connection. A file or shared memory holds raw pixels.
  • aglow clipboard makes a PNG from a JPEG, GIF, APNG, WebP, BMP, TIFF or netPBM image on the clipboard, as kitten clipboard does. It does not make other image formats.
  • aglow dnd has the option --confirm-drop-timeout, which kitten dnd does not have.
  • aglow clipboard has the option --detection-timeout, which kitten clipboard does not have.
  • aglow icat --image-id refuses a number outside 0 to 4294967295. kitten icat wraps it.

Afterglow adds the o key to the end message of a drag (t=e:x=4). It names the action that the drop took. Kitty does not send it. A move to another application is reported as a copy, so that the source keeps its files. See Kitty drag and drop.

Run the tests of aglow:

ctest --test-dir build --output-on-failure -R 'aglow|Aglow|^Image\.|^(Client|RunBinaryTest|RemoteCommandsTest)\.|^Proto\.(Client|Hostile|RunClient|RunInput|RunRemote|Remote)\.'

kitten interoperability

The kitten commands of Kitty are clients of the same protocols as aglow. The tests below run kitten 0.50 against Afterglow. Each test skips when kitten is not installed.

CommandInteroperability checks
kitten icatafterglow_kitten_icat runs it in afterglow_headless, which answers its queries, and reads the images and placements that reach the terminal. It checks the transfer modes detect, stream, file and memory, with a PNG that kitten sends as it is and with an image that it converts. Each temporary file and shared memory object must be deleted. It also checks --place, Unicode placeholders, the frames of an animated GIF, and kitten in a private tmux server. Then it draws the output with the Afterglow renderer.
kitten clipboardNativeWindow.KittenClipboard* run it in a pane of a window in a nested KWin: a write of text and of several MIME types, a read that the prompt allows or denies, and a read over the 8 MiB limit (EFBIG).
kitten dndNativeWindow.Kitty* drag and drop tests, in a nested KWin with real compositor input: a drag between panes, remote directory trees, and a move or copy to a Wayland application.
kitten transferafterglow_transfer_kitten_relay, against the Afterglow file transfer service in process.

Remote commands (OSC 24569)

OSC 24569 is Afterglow’s own sequence. It tells aglow run on a remote host where the socket of its ssh session is. The number spells AGLOW on a phone keypad. No other terminal is known to use it. libs/afterglow-proto writes and reads the query and the replies, for the pane and for aglow.

SequenceForm
Query, from aglow runOSC 24569 ; q=remote ST
Reply with a socketOSC 24569 ; path=PATH ST
Reply without a socketOSC 24569 ; error=REASON ST
ReasonMeaning
offThe pane has no forward. It runs no ssh session, or a requirement of remote commands is missing
forwardThe ssh server refused the forward, or Afterglow did not confirm the forward in time
versionThe aglow on the remote host has another protocol
lengthThe socket path on the remote host would be over 103 bytes

PATH is an absolute path of at most 103 bytes, with no control characters. A reply ends with BEL when the query ended with BEL, else with ST. The pane answers at once, before the replies to what follows the query. Afterglow ignores every other OSC 24569, such as a reply that a program echoes.

aglow run sends DA1 (CSI c) after the query, and every terminal answers DA1. When the DA1 answer comes with no OSC 24569 reply, the terminal is not Afterglow. aglow run waits at most 2 seconds, as a last guard. Inside tmux, aglow run sends the query in tmux passthrough (DCS tmux; ... ST). tmux answers DA1 itself at once, and keeps the DA1 answer of the terminal. Thus inside tmux the guard is a status report (CSI 5 n) in the same passthrough. tmux passes its answer (CSI 0 n) to the pane. When allow-passthrough is off, tmux passes nothing, and aglow run asks tmux for that option first. tmux gets half of the wait for its answer, and the query gets the rest. When tmux answers later, aglow run sends no query. The query goes through the same tmux server, which is slow to answer, and a late reply would go to the shell. aglow run asks the terminal only when standard output is its terminal and its process group is in the foreground there. When its output goes into a pipeline, the program at the end of the pipeline can read the terminal and take the reply. Then aglow run asks nothing. A background job asks nothing, because a change of the terminal modes would stop it (SIGTTOU). A program that writes into aglow run through a pipe and reads the terminal can still take the reply. aglow run reads all the input of the terminal up to the guard’s answer. Without that answer, it discards the input and output of the terminal that wait, so that a late reply does not go to the shell.

The reply is not a secret. Any remote program can send the query. When no program reads the reply, it goes to the shell as input. The permissions of the socket are the only boundary.

Differences from other terminals

AreaAfterglowOther terminals
Character widthsA grapheme cluster takes the cells that glibc’s wcwidth gives it, at most two. See character widths.Kitty gives a letter with a spacing mark one cell, and a prepended mark none.
#rgb in a color escape codeEach digit gives the high bits of its channel, as in xterm: #fff is #f0f0f0.Kitty reads #fff as white.
OKLCH and LAB colorsThe code and the gamut mapping of CSS Color 4. See color escape codes.Kitty clips colors outside sRGB, and gives other values for LAB.
Caps Lock and Num Lock in the Kitty keyboard protocolReported only in the “report all keys” mode, so that a program reads Num Lock+Up as Up.The Kitty specification also reports them in the disambiguate mode, for keys without text.
F13 to F35 without the Kitty keyboard protocolThe sequences of xterm’s terminfo entry, as the Kitty specification lets a terminal do.Kitty sends its own CSI u codes.
Ctrl with a key of a non-Latin layoutThe key of the first Latin layout, as Qt’s shortcuts do. Ctrl+С on a Russian layout is Ctrl+C, also in the Kitty keyboard protocol without alternate keys (CSI 99;5u). With alternate keys (flag 4) Afterglow sends the key of the layout and the base layout key, as Kitty does: CSI 1089::99;5u.Without flag 4, Kitty sends the key of the layout, CSI 1089;5u, which a program that knows only Latin shortcuts does not read as Ctrl+C.
Ctrl+Shift, Super or Ctrl+Alt+Shift with a letter, digit or punctuation key, without the Kitty keyboard protocolxterm’s bytes: Ctrl+Shift+I sends a tab (0x09), Super+A sends a. A program without the Kitty protocol reads these.Kitty sends a CSI u code, such as CSI 105;6u for Ctrl+Shift+I.
A temporary image file (t=t)Deleted only when tty-graphics-protocol is in its path below the temporary directory.Kitty looks for the tag anywhere in the path.
Sized text (OSC 66) at a resize that reflowsThe text stays, at the normal size, because a block of several rows cannot wrap.The Kitty specification does not say what a reflow does with sized text.
Unscroll (CSI n + T) with a scrolling region smaller than the screenBlank lines, as SD gives. Afterglow fills from the scrollback only when the region is the whole screen.Kitty also fills a region that starts at the top line.
OSC 1337 downloadsOne question with the name, and with the size when the program declares one. The choices are Save to the download folder, Save As… and Refuse. Terminal.downloads sets a policy. The data goes to the file as it comes.iTerm2 asks two questions: allow the download, then where to save it. It asks again past 1 GiB, and keeps the data in memory until the end. Kitty does not support OSC 1337 downloads.
The end message of a drag (t=e:x=4)Has the key o, the action that the drop took. A move to another application is reported as a copy.Kitty sends no o.

The differences of aglow from kitten are in aglow interoperability.

Safety limits

These limits keep a program from taking all the memory or time of the terminal. Real programs stay far below them.

Images

The main screen and the alternate screen have separate image stores. Each store has these limits:

ItemLimitAt the limit
Images4,096Afterglow deletes an image without a placement: first an image with the transient hint (N=1), then the oldest. When every image has a placement, a Kitty command gets an ENOSPC error.
Placements4,096A Kitty command gets an ENOSPC error. A new Sixel or iTerm2 image removes the oldest Sixel or iTerm2 placement. When there is none, Afterglow does not keep the new image.
Frames per image1,024A Kitty command gets an ENOSPC error.
Frames of all images16,384Afterglow deletes images as for image data. A frame of one pixel costs far more to keep than its 4 bytes.
Image dataGraphics.quota, 320 MiB by default, at 4 bytes for each pixelAfterglow deletes images without a placement: first those with the transient hint (N=1), then the oldest. When none is left, it deletes the oldest image with a placement.
Pending transmissions320 MiBThe transmission fails with an EFBIG error.

The main screen and the alternate screen of a pane each have their own image work budget. The budget is 1 GiB, and it fills again at 1 GiB each second.

Work over the budgetError
A read from a file (t=f), a temporary file (t=t) or shared memory (t=s)EBUSY:too much image data read
A frame edit (a=f, a=c)EBUSY:too much frame editing

The error ends with , try again later when the program can send the same command again. When Afterglow deletes the temporary file or the shared memory object by the rules above, the error has no , try again later. A command that tries again with the same name then gets EBADF:failed to read image file.

Afterglow reads the file in the thread that reads the program’s output. While a read waits, for example on a network mount that does not answer, the pane does not change. To prevent this, set Terminal.graphicsFileTransfer to "deny".

Afterglow checks the size that a Kitty transmission declares before it reads or decompresses the data. Raw pixels (f=24 or f=32) use 3 or 4 bytes for each pixel, and Afterglow keeps 4. Indexed pixels (f=8 or f=16) use 1 or 2 bytes for each pixel, and Afterglow keeps the same number. The limits count 4 bytes for each pixel of all these formats, because Afterglow draws every image as RGBA.

CaseResult
o has a value that is not zThe program gets an EINVAL error.
f=0Afterglow reads it as the default, f=32, as Kitty does.
f is not 0, 8, 16, 24, 32 or 100The program gets an EINVAL error.
Raw or indexed pixels without s or v, or with a value above 10,000The program gets an EINVAL error.
Raw or indexed pixels where s × v × 4 bytes is more than 320 MiBThe program gets an EFBIG error.
Raw or indexed pixels where s × v × 4 bytes is more than Graphics.quotaThe program gets an ENOSPC error.
Uncompressed raw or indexed pixels from a file or shared memoryAfterglow reads s × v pixels and no more of the file.
Raw or indexed pixels with o=z that decompress to more than s × v pixelsThe program gets an EINVAL error.
PNG data (f=100) or o=z data that is longer than 320 MiB, inlineThe program gets an EFBIG error.
PNG data with o=z that decompresses to more than Graphics.quota or 320 MiBThe program gets an EINVAL error.
A PNG image whose decoded pixels (width × height × 4 bytes) are more than 320 MiBThe program gets an EBADPNG error.
A PNG image whose decoded pixels (width × height × 4 bytes) are more than Graphics.quotaThe program gets an ENOSPC error.

Images that a pane decodes

The processes that decode the images of a pane have these limits. A session pane has the same limits in the daemon (see MUX.md).

ItemLimitAt the limit
Side of an image10,000 pixelsA Kitty command gets an EBADPNG error. An iTerm2 image does not show.
Decoded pixels of an image (width × height × 4 bytes)320 MiBA Kitty command gets an EBADPNG error. An iTerm2 image does not show.
Time to decode an image30 seconds, and a CPU time of 5 seconds and 1 second more for each 16 MiB of pixelsThe process ends, and the decode fails as above.
Memory of a decoding processIts memory at its start, and 8 times the decoded pixels and 64 MiB moreThe decode fails as above.
Scans of a progressive JPEG1,000The decode fails as above.

The processes need a kernel with seccomp filters, and Linux 5.3 or later (pidfd_open). They also need an x86-64, little-endian AArch64, RISC-V 64 or little-endian POWER64 processor. On FreeBSD, the processes run in Capsicum capability mode instead, on any processor. Elsewhere, the images that programs send do not show, and Afterglow writes why in its log.

Sixel, iTerm2 and escape strings

ItemLimitAt the limit
An OSC, DCS or APC string64 MiBAfterglow ignores the whole string. The data of an OSC 1337 file goes on as it comes, and this limit does not apply to it.
A Sixel image10,000 pixels on a side, and 4,096 × 4,096 pixelsAfterglow does not show the image.
Pixel writes of one Sixel image4 × 4,096 × 4,096Afterglow does not show the image. A $ repaints a band, so a short image can write the same pixels many times.
The size that an iTerm2 image shows at10,000 pixels on a side, and 4,096 × 4,096 pixelsThe image shows smaller. When it keeps its aspect ratio, both sides shrink by the same factor.

Multiple cursors

CSI parsing permits 4,096 numeric parameters per sequence. An overflow rejects the complete command. Divide larger point sets across sequences. The terminal keeps at most 4,096 extra cursors. It ignores new positions after this limit. At this limit, the terminal keeps the positions of the rectangles that start nearest the top, then nearest the left. The order of the rectangles in the sequence does not matter.

OSC 8 links of each screen have a 16 MiB limit. Above it, new text prints without a link. Each link counts its URI, its id and 160 bytes for its entry. A link with an id counts its URI and id two times. An OSC 8 sequence longer than 8,192 bytes ends the open link. The text after it has no link. OSC 133 marks have no length limit. A cmdline or cmdline_url value over 65,536 bytes is ignored, and the mark still counts. The command line is then the text typed after the B mark.

Downloads

A download (OSC 1337 File or MultipartFile without inline=1) has no size limit: its data streams to the file. The arguments of a File download must come in its first 4,096 bytes, before the :. Longer arguments refuse the file. An inline image in parts can have 96 MiB of base64 data. MultipartFile arguments have a 4,096-byte limit. Longer arguments refuse the file.

Pointer shapes

Each screen has its own stack of pointer shapes. Each stack has 32 entries. A full stack discards its oldest entry when a new entry is pushed.

Protocol definitions

Existing coverage

The suite also checks these features:

  • Terminal parsing, grid behavior, scrollback and reflow.
  • Tab stops: HTS, TBC, CHT, CBT and DECST8C (CSI ? 5 W), which sets a stop at every 8th column again.
  • Sixel.
  • Kitty image transmission, placement, animation, Unicode placeholders and indexed images.
  • iTerm2 inline images.
  • OSC 66 text sizing.
  • Keyboard and mouse encodings.
  • Shell markers.
  • Clipboard and notification extensions.

See libs/afterglow-vt/tests for exact accepted sequences. See libs/afterglow-proto/tests for the message formats.

Run focused tests:

ctest --test-dir build --output-on-failure -R 'Graphics.Relative|Graphics.TransmitAndPlaceReportsInvalidRelativeParent|Extensions.Multiple|Terminal.ExtraCursorsAreBounded|Terminal.ResizeClipsExtraCursors|Extensions.ResizeClipsExtraCursors|Extensions.ExtraCursor|Extensions.*Download|PaneDownload|UploadArchive|Terminal.AnUploadRequest|MuxAttach.*(Download|Upload)|DesktopText|FileDrop|Render.Multiple|SnapshotCursor|Bidi|Graphics.Indexed|Render.Indexed|SnapshotImages.Indexed'

See accessibility and downloads for the native acceptance suite.

Mirrored from docs/COMPATIBILITY.md in the Afterglow repository.