Ghostling - Minimal libghostty Terminal

Warning

This fork is currently a slop fork focused on getting Ghostling to limp along on Windows. The Windows build works only via local workarounds and is still pretty meh. Expect rough edges, hardcoded assumptions, and debug scaffolding while things are being figured out.

Ghostling is a demo project meant to highlight a minimum functional terminal built on the libghostty C API. The core demo remains centered around main.c, with small platform backend files for process hosting.

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.

Important

The Ghostling terminal isn't meant to be a full featured, daily use terminal. It is a minimal viable terminal based on libghostty. Still, it supports a lot more features than even the average terminal emulator!

What is Libghostty?

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.

Features

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!

What Is Coming

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:

• Additional Windows polish and testing

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

What You Won't Ever Get

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.

Building

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.

On Windows, Ghostling now uses ConPTY for process hosting, but the build and runtime story are still experimental in this fork. The current Windows profile flags are:

• --pwsh (default on Windows)
• --cmd
• --wsl
• --git-bash

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

Examples on Windows:

.\build\ghostling.exe --pwsh
.\build\ghostling.exe --cmd
.\build\ghostling.exe --wsl
.\build\ghostling.exe --git-bash

Warning

Debug builds are VERY SLOW since Ghostty included a lot of extra safety and correctness checks. Do not benchmark debug builds.

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:

cmake --build build

FAQ

Why Not Zig?

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.

What about Rust or any other language?

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!

Why CMake, Raylib, etc.?

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!