libghostty-vt Skill | Agent Skills

libghostty-vt

Zero-dependency VT sequence parser from Ghostty. Mitchell Hashimoto's embeddable terminal core.

Status

NOT YET RELEASED (as of 2025-09) - Zig API available for testing, C API coming.

What It Is

libghostty-vt extracts Ghostty's proven VT parsing into a standalone library:

Parse ANSI/VT sequences
Maintain terminal state
Zero dependencies (no libc required!)
SIMD-optimized (>100 MB/s plain text)

Architecture

Raw Bytes → UTF8Decoder → Parser (DFA) → Stream → Actions
                           │
                     State Machine
                     (14 states)

Parser States

| State | Purpose | |-------|---------| | ground | Normal text printing | | escape | ESC detected (0x1B) | | csi_entry | CSI sequence start | | csi_param | Parsing CSI parameters | | osc_string | OSC data collection | | dcs_passthrough | DCS data collection |

Action Types

const Action = union(enum) {
    print: u21,              // Unicode codepoint
    execute: u8,             // C0/C1 control
    csi_dispatch: CSI,       // Control Sequence Introducer
    esc_dispatch: ESC,       // Escape sequence
    osc_dispatch: *osc.Parser,
    dcs_hook: DCS,
    dcs_put: u8,
    dcs_unhook: void,
};

Key Files (ghostty-org/ghostty)

src/terminal/Parser.zig      # State machine
src/terminal/stream.zig      # Stream wrapper + SIMD
src/terminal/osc.zig         # OSC parser
src/terminal/parse_table.zig # Compile-time transition table
src/simd/vt.zig              # SIMD acceleration

Performance

| Optimization | Impact | |--------------|--------| | Pre-computed state table | O(1) transitions | | SIMD text processing | 10-100x for plain text | | Fast-path CSI parsing | Skips state machine | | Fixed-size buffers | No allocation |

Use Cases

Terminal emulators (tmux, zellij, Ghostty)
IDE terminals (VS Code, JetBrains)
Cloud terminals (Vercel, Render)
TUI frameworks
Terminal recording/playback

When Available

# Future installation (not yet available)
# Zig
zig fetch --save git+https://github.com/ghostty-org/libghostty-vt

# C (when released)
# pkg-config --cflags --libs libghostty-vt

Example (Future API)

const vt = @import("libghostty-vt");

var parser = vt.Parser.init();
var stream = vt.Stream(MyHandler).init(&parser, &handler);

// Process bytes
for (input) |byte| {
    if (stream.next(byte)) |action| {
        switch (action) {
            .print => |cp| handler.print(cp),
            .csi_dispatch => |csi| handler.handleCSI(csi),
            // ...
        }
    }
}

Sources

https://mitchellh.com/writing/libghostty-is-coming
https://ghostty.org/docs/about
https://github.com/ghostty-org/ghostty
https://vt100.net/emu/dec_ansi_parser

GF(3) Assignment

Trit: +1 (PLUS) - Generator/Parser
Hue: 180° (cyan - terminal green vibes)

Triads:

libghostty-vt (+1) × vterm (0) × terminfo (-1) = 0 ✓
libghostty-vt (+1) × tmux (0) × escape-sequence-validator (-1) = 0 ✓

Agent Skills: libghostty-vt

Install this agent skill to your local

Skill Files