libghostty

Dart bindings to libghostty-vt, the terminal emulator library from Ghostty.

Android	iOS	macOS	Linux	Windows	Web
✅	✅	✅	✅	✅	✅

Getting started

# pubspec.yaml
dependencies:
  libghostty: ^0.0.7

On web, initialize the WASM module once before using any bindings:

await initializeForWeb(Uri.parse('assets/libghostty.wasm'));

Usage

Terminal

Terminal emulator with screen state, scrollback, cursor, styles, modes, and VT stream processing. Register effect callbacks for PTY writes, bell, title changes, and more.

import 'dart:typed_data';
import 'package:libghostty/libghostty.dart';

void main() {
  final terminal = Terminal(cols: 80, rows: 24);

  // Register effects (callbacks invoked synchronously during write).
  terminal.onWritePty = (data) => pty.write(data);
  terminal.onBell = () => playSound();
  terminal.onTitleChanged = () => print('Title: ${terminal.title}');

  // Write VT data and resize.
  terminal.write(Uint8List.fromList(vtData));
  terminal.resize(cols: 120, rows: 40, cellWidthPx: 8, cellHeightPx: 16);

  // Read a single cell via grid reference (for ad-hoc lookups).
  final ref = terminal.gridRefAt(col: 0, row: 0);
  print(ref.content); // the character at (0, 0)
  ref.dispose();

  // Read screen via render state (for render loops).
  terminal.renderState.update();
  while (terminal.renderState.nextRow()) {
    while (terminal.renderState.nextCell()) {
      final cell = terminal.renderState.cell;
      if (cell.hasText) print(cell.content);
    }
  }
  terminal.renderState.markClean();

  terminal.dispose();
}

Key encoding

Encode key events into terminal escape sequences, supporting legacy and Kitty keyboard protocol.

final event = KeyEvent()
  ..mods = const .ctrl()
  ..action = .press
  ..key = .c;

final encoded = terminal.keyEncoder.encode(event);
if (encoded.isNotEmpty) pty.write(utf8.encode(encoded));
event.dispose();

Mouse encoding

Encode mouse events into escape sequences, supporting X10, UTF-8, SGR, URxvt, and SGR-Pixels protocols.

// Sync tracking mode from terminal after each write.
terminal.mouseEncoder.syncFrom(terminal);
terminal.mouseEncoder.setSize(const MouseEncoderSize(
  screenWidth: 640,
  screenHeight: 384,
  cellWidth: 8,
  cellHeight: 16,
));

final event = MouseEvent()
  ..action = .press
  ..button = .left;
event.setPosition(x: 10.0, y: 5.0);

final encoded = terminal.mouseEncoder.encode(event);
if (encoded.isNotEmpty) pty.write(utf8.encode(encoded));
event.dispose();

Formatting

Format terminal content as plain text, VT sequences, or HTML.

final formatter = terminal.createFormatter(format: .plain);
print(formatter.format());
formatter.dispose();

SGR and OSC parsing

Parse SGR (Select Graphic Rendition) parameters into typed attributes and OSC (Operating System Command) sequences from a byte stream.

// SGR: parse Select Graphic Rendition parameters.
final sgr = SgrParser();
for (final attr in sgr.parse([1, 38, 2, 255, 0, 0])) {
  switch (attr.tag) {
    case .bold:
      print('bold');
    case .directColorFg:
      print('fg: ${attr.color}');
    default:
      break;
  }
}
sgr.dispose();

// OSC: parse Operating System Command sequences.
final osc = OscParser();
osc.feedBytes(utf8.encode('0;My Title'));
final command = osc.end(0x07);
print(command.type);        // OscCommandType.changeWindowTitle
print(command.windowTitle); // My Title
osc.dispose();

Paste validation

Check paste data for unsafe sequences (newlines, bracketed paste escapes) before writing to the terminal.

pasteIsSafe('hello');           // true
pasteIsSafe('rm -rf /\n');      // false
pasteIsSafe('\x1b[201~inject'); // false