Crate libghostty_vt 

Idiomatic, safe Rust bindings for libghostty-vt, a terminal emulation library extracted from the Ghostty terminal emulator.

libghostty-vt contains the logic for handling the core parts of a terminal emulator: parsing terminal escape sequences, maintaining terminal state, encoding input events, etc. It can handle scrollback, line wrapping, reflow on resize, and more.

This library is currently in development and the API is not yet stable. Breaking changes are expected in future versions. Use with caution in production code.

The core type of libghostty-vt is the Terminal — start there to get a better sense of how everything is structured. You can also check out a list of all top-level modules and their functions below.

Examples

ghostling-rs is a minimal yet functional terminal emulator built with libghostty-vt, written as a single file with only around 1000 lines of heavily commented, easily digestible code. It is based on the original Ghostling which is built on the same underlying C API.

Other examples are currently work-in-progress — if you have any ideas for examples, feel free to share them with us as an issue or pull request.

Memory management and lifetimes

When creating the terminal and various other objects, you can control their memory management via a custom allocator, usually specified with methods like Terminal::new_with_alloc. Objects that accept allocators are also bound by the 'alloc lifetime, since they internally contain a reference to the allocator. If you do not use a custom allocator, feel free to always set the lifetime to 'static.

Using the unstable Allocator API

You can adapt the existing, unstable Allocator API into a libghostty-friendly allocator via its From implementation. Note that the 'alloc lifetime must at least live as long as the Allocator instance itself.

Thread safety

The entire libghostty-vt library is not thread-safe unless otherwise noted. This is because the underlying C API is not designed with thread safety in mind, and we as binding authors must rather conservatively avoid making any assumptions beyond what is presently guaranteed by the C API.

In particular, all libghostty-vt types are !Send, meaning they cannot be transferred across threads, since the C API is allowed to use thread-local state; they are also !Sync, meaning they cannot be shared across threads, since data races may occur as the C API is not guarded with mutexes or other synchronization mechanisms. We currently do not expect to lift these limitations unless the C API starts to make stronger guarantees regarding thread safety.

Note that this does not mean that libghostty-vt can only be used on the main thread. On the contrary, in a complex program we encourage you to create the terminal on a separate thread (or task in async programming), and use channels to communicate between the terminal emulation thread/task and the main program. Under sufficient load, it is generally more efficient to offload terminal emulation to its own operating system-level thread, in order to reduce competition with other business logic.

Re-exports

pub use libghostty_vt_sys as ffi;

Modules

alloc

Adapting custom allocators to work with libghostty.

build_info

Query compile-time build configuration of libghostty-vt.

error

Error handling.

fmt

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

focus

Encoding focus gained/lost events into terminal escape sequences (CSI I / CSI O) for focus reporting mode (mode 1004).

key

Encoding key events into terminal escape sequences,

kitty

Handling various protocols pioneered by Kitty, including the Kitty graphics protocol.

log

Logging functionality.

mouse

Encoding mouse events into terminal escape sequences.

osc

Handling OSC (Operating System Command) escape sequences.

paste

Utilities for validating paste data safety.

render

Managing render states of the terminal.

screen

Terminal screen cell and row types.

selection

Selecting terminal content between two endpoints.

sgr

Handling SGR (Select Graphic Rendition) escape sequences.

style

Terminal cell style attributes.

terminal

Types and functions around terminal state management.

Structs

RenderState

Represents the state required to render a visible screen (a viewport) of a terminal instance.

Terminal

Complete terminal emulator state and rendering.

TerminalOptions

Terminal initialization options.

Enums

Error

Possible errors libghostty-vt may return.

Traits

Logger

Callback type for logging.

Functions

set_logger

Set the log callback.