playbooks

home / skills / plurigrid / asi / libghostty-vt

libghostty-vt skill

/skills/libghostty-vt

This skill provides a zero-dependency VT sequence parser library extraction for terminal emulation, enabling fast ANSI/VT parsing and stateful handling.

npx playbooks add skill plurigrid/asi --skill libghostty-vt

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
3.1 KB
---
name: libghostty-vt
description: 'libghostty-vt'
version: 1.0.0
---

# 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

```zig
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

```bash
# 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)

```zig
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 ✓

Overview

This skill provides a zero-dependency VT/ANSI sequence parser extracted from Ghostty as libghostty-vt. It exposes a small, embeddable parser and stream layer that decodes UTF-8, runs a DFA-based VT state machine, and emits action events for printing, control, CSI/OSC/DCS handling. The library emphasizes performance with SIMD text paths, fixed buffers, and O(1) transition tables. It is intended for embedding in terminals, IDEs, cloud consoles, and TUI frameworks.

How this skill works

Input bytes pass through a UTF-8 decoder into a DFA parser with about 14 states (ground, escape, csi_param, osc_string, dcs_passthrough, etc.). The parser emits typed actions (print, execute, csi_dispatch, esc_dispatch, osc_dispatch, dcs_hook/put/unhook) which a host-provided handler implements. A Stream wrapper provides a fast-path SIMD loop for plain text while falling back to the state machine for control sequences, enabling high throughput without external dependencies.

When to use it

  • Embedding a compact VT parser in a terminal emulator or multiplexer.
  • Adding VT/ANSI support to an IDE integrated terminal or plugin.
  • Building cloud-hosted terminals, remote shells, or browser-based consoles.
  • Implementing terminal recording/playback or TUI libraries that must interpret control sequences.
  • Needing a zero-libc, high-performance VT core for constrained or embedded environments.

Best practices

  • Implement a handler that maps parser actions to your renderer or terminal state; keep handlers small and non-blocking.
  • Use the Stream fast-path for bulk text writes and fall back for control sequence processing to maximize throughput.
  • Buffer OSC and DCS payloads as provided by the library; treat untrusted input carefully and enforce size limits.
  • Test with real-world terminal streams (applications like bash, vim, tmux) to exercise edge-case sequences.
  • Upgrade to the C API when available for broader language bindings; the Zig API is suitable for early testing.

Example use cases

  • Replace or supplement an existing VT parser in a terminal emulator to gain SIMD-accelerated text processing.
  • Embed into an IDE terminal to correctly render ANSI colors, cursor moves, and device-control sequences.
  • Provide a compact VT layer for a cloud console service that needs to parse and forward terminal events securely.
  • Use in a terminal recording/playback tool to faithfully capture and replay control sequences and printed output.
  • Integrate into a TUI framework to normalize input streams from various shells and programs.

FAQ

Is the library production-ready and stable?

As of the source, the project is not yet released; the Zig API is available for testing and a C API is planned for a future release.

Does it require external libraries or libc?

No — the core design is zero-dependency and claims to operate without libc, using fixed-size buffers and no dynamic allocations for the parser core.