Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Examples

Every example is a complete program you can build and run. Each one lives in its own directory under example/, with a README that says how to run it. Most of them are one zig build run. CI compiles all Rust examples, so they can’t fall behind the API.

If you want to see everything working together, start with ghostling-rs. It’s a minimal but complete terminal built on libghostty-vt, written in Rust.

If you only want to read a terminal’s screen, start with rust-vt-stream.

Start Here

ExampleWhat it does
rust-vt-helloThe smallest complete program: create a terminal, write text with a color sequence in it, and print the screen. This is the program on the main page.
rust-vt-streamFeed VT sequences into a terminal, read the final screen back as plain text, and draw it with a render state. Start here for read-only tools like replay viewers and CI log viewers.
rust-vt-formatterWrite text and cursor movement into a terminal, then stream the screen to stdout as plain text through a GhosttyWriter.

Terminal

ExampleWhat it doesGuide
rust-vt-colorsSet the default colors and palette, then read effective and default values as an OSC 10 override layers on top.Colors
rust-vt-effectsRegister callbacks for what a program asks of the terminal: pty replies, the bell, title changes, OSC 52 clipboard reads and writes, and unknown sequences. You need these as soon as a real program runs in the terminal.Effects
rust-vt-compressionCompress scrollback while the terminal is idle.Scrollback
rust-vt-snapshotEncode a terminal’s full state and restore it three ways: in one shot, with scrollback kept compressed, and page by page. The page by page path gives you a terminal you can draw before the old history arrives.Snapshots
rust-vt-grid-traverseWalk the whole grid cell by cell with grid refs, reading codepoints, row wrap state and styles.The Grid
rust-vt-grid-ref-trackedKeep a reference to one cell while the terminal scrolls under it.The Grid
rust-vt-renderDraw a frame from a render state: check what’s dirty, walk the rows and cells, and read styles, colors, the cursor and the selection. Use this when you render the terminal yourself.Rendering
rust-vt-searchSearch the terminal for a string, step through the matches like a find bar, and read the viewport matches to draw highlights.Search
rust-vt-selectionSelect a word, a line, a command’s output or the whole screen, then format each selection as text. The line and output selections use OSC 133 prompt markers.Selection
rust-vt-selection-gestureFeed press, drag, release and deep press events to ghostty_selection_gesture_event() and get back selections you can show or copy.Selection
rust-vt-kitty-graphicsAccept images sent with the Kitty Graphics Protocol and find out what to draw. It installs a stand-in PNG decoder, reads placements from the render state, and plays an animation.Images

Input

ExampleWhat it doesGuide
rust-vt-encode-keyEncode Ctrl+C as an escape sequence with the Kitty keyboard protocol.Input
rust-vt-encode-mouseEncode a left button press at a pixel position as an SGR mouse sequence.Input
rust-vt-encode-focusEncode a focus gained event as CSI I, for programs that turn on focus reporting (mode 1004).Input
rust-vt-pastePaste into a terminal with ghostty_terminal_paste(): plain text, bracketed paste (mode 2004), the unsafe-paste confirmation, and Kitty paste events (mode 5522). It also checks paste safety and encodes paste data without a terminal.Input

Building Blocks

ExampleWhat it doesGuide
rust-vt-oscParse an OSC sequence and read the window title out of it.
rust-vt-sgrParse SGR sequences into text attributes, including a real one from Kakoune with a curly underline and RGB colors.
rust-vt-modesPack DEC and ANSI mode numbers into a GhosttyMode and encode a DECRPM report.
rust-vt-color-schemeEncode a color scheme report, the reply to a CSI ? 996 n query.Colors
rust-vt-size-reportEncode an in-band size report (mode 2048) from the grid and cell size.
rust-vt-allocatorRun a terminal on your own allocator, built on malloc and free. It counts live bytes to check that the terminal frees everything.
rust-vt-build-infoQuery build options like SIMD and Kitty graphics, then check that the loaded library matches the headers you compiled against.

Other Languages

C language examples can be found in the original documentation. Examples written in other languages can be found there as well, under the “Other Languages” section.