ghostty-org/ghostling: A minimum viable terminal emulator built on top of the libghostty C API. Ex minimo, infinita nascuntur. 👻🐣 · GitHub

Ghostling is a demo project meant to highlight a minimum
functional terminal built on the libghostty C API in a
single C file.

The example uses Raylib for windowing and rendering. It is single-threaded
(although libghostty-vt supports threading) and uses a 2D graphics renderer
instead of a direct GPU renderer like the primary Ghostty GUI. This is to
showcase the flexibility of libghostty and how it can be used in a variety of
contexts.

Libghostty is an embeddable library extracted from Ghostty’s core,
exposing a C and Zig API so any application can embed correct, fast terminal
emulation.

Ghostling uses libghostty-vt, a zero-dependency library (not even libc) that
handles VT sequence parsing, terminal state management (cursor position,
styles, text reflow, scrollback, etc.), and renderer state management. It
contains no renderer drawing or windowing code; the consumer (Ghostling, in
this case) provides its own. The core logic is extracted directly from Ghostty
and inherits all of its real-world benefits: excellent, accurate, and complete
terminal emulation support, SIMD-optimized parsing, leading Unicode support,
highly optimized memory usage, and a robust fuzzed and tested codebase, all
proven by millions of daily active users of Ghostty GUI.

Despite being a minimal, thin layer above libghostty, look at all the
features you do get:

• Resize with text reflow
• Full 24-bit color and 256-color palette support
• Bold, italic, and inverse text styles
• Unicode and multi-codepoint grapheme handling (no shaping or layout)
• Keyboard input with modifier support (Shift, Ctrl, Alt, Super)
• Kitty keyboard protocol support
• Mouse tracking (X10, normal, button, and any-event modes)
• Mouse reporting formats (SGR, URxvt, UTF8, X10)
• Scroll wheel support (viewport scrollback or forwarded to applications)
• Scrollbar with mouse drag-to-scroll
• Focus reporting (CSI I / CSI O)
• And more. Effectively all the terminal emulation features supported
  by Ghostty!

These features aren’t properly exposed by libghostty-vt yet but will be:

• Kitty Graphics Protocol
• OSC clipboard support
• OSC title setting

These are things that could work but haven’t been tested or aren’t
implemented in Ghostling itself:

• Windows support (libghostty-vt supports Windows)

This list is incomplete and we’ll add things as we find them.

libghostty is focused on core terminal emulation features. As such,
you don’t get features that are provided by the GUI above the terminal
emulation layer, such as:

• Tabs
• Multiple windows
• Splits
• Session management
• Configuration file or GUI
• Search UI (although search internals are provided by libghostty-vt)

These are the things that libghostty consumers are expected to implement
on their own, if they want them. This example doesn’t implement these
to try to stay as minimal as possible.

Requires CMake 3.19+, a C compiler, and Zig 0.15.x on PATH.
Raylib is fetched automatically via CMake’s FetchContent if not already installed.

cmake -B build -G Ninja
cmake --build build
./build/ghostling

For a release (optimized) build:

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

After the initial configure, you only need to run the build step:

libghostty-vt has a fully capable and proven Zig API. Ghostty GUI itself
uses this and is a good — although complex — example of how to use it.
However, this demo is meant to showcase the minimal C API since C is so
much more broadly used and accessible to a wide variety of developers and
language ecosystems.

libghostty-vt has a C API and can have zero dependencies, so it can be used
with minimally thin bindings in basically any language. I’m not sure yet if
the Ghostty project will maintain official bindings for languages other than C
and Zig, but I hope the community will create and maintain bindings for many
languages!

No no no! libghostty has no opinion about the renderer or GUI framework
used; it’s even standalone WASM-compatible for browsers and other environments.

libghostty provides a high-performance render state API
which only keeps track of the state required to build a renderer. This is the
same API used by Ghostty GUI for Metal and OpenGL rendering and in this repository
for the Raylib 2D graphics API. You can layer any renderer on top of this!

I needed to pick something. Really, any build system and any library
could be used. CMake is widely used and supported, and Raylib is a simple
and elegant library for windowing and 2D rendering that is easy to set up.
Don’t get bogged down in these details!