Ghostling: a terminal emulator in one C file, built to show what libghostty can do

One C file, one purpose, no pretence

Ghostling is described as a minimum viable terminal emulator built on top of the libghostty C API, and the README calls it a demo project meant to highlight a minimum functional terminal in a single C file.

That framing is the most useful thing about it. There is no application logic spread over a tree of modules, no build of a full product, and no feature list to negotiate. The application is main.c, and the repository listing shows exactly that alongside a CMakeLists.txt, a bin2header.cmake helper, a fonts directory, a demo.gif, an .envrc and a flake.nix.

The warning in the README deserves to be quoted in substance rather than paraphrased. The Ghostling terminal isn't meant to be a full featured, daily use terminal, it is a minimal viable terminal based on libghostty, and since this is basically a demo, the author didn't carefully audit every single place for correctness, and this is C, so you've been warned.

So the audience is specific: a developer who wants to read a complete, small example of how libghostty is used, and who will go build their own thing on top of it. The second half of that sentence is in the repository's own tagline, that the goal is to show the flexibility of libghostty and how it can be used in a variety of contexts.

The licence is MIT, and the project lives in the ghostty-org organisation next to Ghostty itself, so the code is a first-party demonstration rather than a third-party experiment.

libghostty owns the emulation, the demo owns the pixels

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 specifically, described as a zero-dependency library, not even libc, that handles VT sequence parsing, terminal state management for cursor position, styles, text reflow and scrollback, and renderer state management. It contains no renderer drawing or windowing code; the consumer, Ghostling in this case, provides its own.

That division is the architecture. The hard part of writing a terminal, the part where correctness is won or lost, lives in the library, which the README credits with excellent, accurate and complete terminal emulation support, SIMD-optimised parsing, leading Unicode support, highly optimised memory usage, and a fuzzed and tested codebase, all proven by millions of daily active users of the Ghostty GUI.

What the demo adds is a renderer, and it is deliberately the simplest one. The example uses Raylib for windowing and rendering, 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.

The FAQ makes the last point explicitly. libghostty has no opinion about the renderer or GUI framework used, is even standalone WASM-compatible for browsers and other environments, and provides a high-performance render state API which only keeps track of the state required to build a renderer. The README says the same API is used by Ghostty GUI for Metal and OpenGL rendering, and in this repository for the Raylib 2D graphics API, and concludes that you can layer any renderer on top of it.

The feature list is longer than a demo should have

The README has a section that invites you to look at all the features you do get, and the list is the strongest argument the project makes.

There is resize with text reflow, full 24-bit color and 256-color palette support, and bold, italic and inverse text styles. Input covers keyboard input with modifier support for Shift, Ctrl, Alt and Super, the Kitty keyboard protocol, the Kitty graphics protocol, and mouse tracking in X10, normal, button and any-event modes with the SGR, URxvt, UTF8 and X10 reporting formats. The scroll wheel either scrolls the viewport scrollback or is forwarded to the application, there is a scrollbar with mouse drag-to-scroll, and there is focus reporting with CSI I and CSI O.

What makes this list meaningful is that none of it is implemented in the demo. It is inherited, and the README says so plainly: effectively all the terminal emulation features supported by Ghostty.

That is the whole argument of the library, and the demo is the proof of it. A terminal emulator is mostly a large, fiddly pile of protocol handling, and the protocols here are the ones that break naive implementations: grapheme clusters, mouse reporting formats, focus events, the Kitty extensions. Getting them right is a project, and the project does not start from zero.

There is a limit to the inheritance, and it is stated. OSC clipboard support is listed under what is coming, because these features aren't properly exposed by libghostty-vt yet but will be. Windows support is in the second list, of things that could work but haven't been tested or aren't implemented in Ghostling itself, even though libghostty-vt supports Windows.

What libghostty will never give you

The section headed what you won't ever get is the most useful part of the README for anyone evaluating this, and it is a design statement rather than a bug list.

libghostty is focused on core terminal emulation features, so you don't get the features provided by the GUI above the terminal emulation layer. The list is tabs, multiple windows, splits, session management, configuration file or GUI, and a search UI, although the search internals are provided by libghostty-vt. The README states that these are the things libghostty consumers are expected to implement on their own if they want them, and that this example doesn't implement them to try to stay as minimal as possible.

That is a coherent division of labour. The library is the part where a hundred terminals would otherwise each reimplement the same protocol handling, and the layer above it is where products legitimately differ. Search is the interesting case, because the hard part of search, the reverse index over the scrollback, is in the library, and the user interface for it is not.

So the honest assessment of Ghostling is that it is a terminal with no shell around it, in the sense that a modern terminal is a window manager for shells. There is one session, no way to name it, no way to configure it, and no way to search what has scrolled past except by scrolling.

For the intended reader, that is the point rather than a shortfall. The demo shows the emulation layer, and the layers above it are exactly the parts an application author is expected to write.

Building it needs CMake, Ninja and Zig on the path

The build requirements are listed exactly, and one of them is unusual enough to notice.

You need CMake 3.19 or later, Ninja, a C compiler, and Zig 0.16.x on PATH. On macOS that means the Command Line Tools or Xcode. On Linux, Ubuntu or Debian, the README gives the install line:

sudo apt install -y ninja-build build-essential git libxinerama-dev libxcursor-dev libxrandr-dev libxi-dev libxext-dev libx11-dev libgl-dev

The Zig requirement is the one that will stop people. The application itself is C, and the FAQ explains why it is not written in 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, but this demo is meant to show the minimal C API since C is so much more broadly used and accessible to a wide variety of developers and language ecosystems.

The build itself is three commands, and the last one runs the program:

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

For a release build, the build type is passed at configuration time:

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

After the initial configuration, only the build step is needed, and to clean up the build directory the target is clean, with cmake --build build --target clean.

The performance warning that follows is important and easy to miss. Debug builds are VERY SLOW since Ghostty included a lot of extra safety and correctness checks, and the README says plainly: do not benchmark debug builds.

Raylib's input events are the weakest link

The limitations section attributes the demo's known issues to the layers underneath it rather than to the library, and the Kitty keyboard protocol is the clearest case.

Kitty keyboard protocol support is broken with some inputs. The reason given is the limitations of the underlying Raylib input system, which doesn't support rich enough input events to fully and correctly implement the Kitty keyboard protocol, and the README links the known issue in the GLFW tracker. The libghostty-vt API supports the Kitty keyboard protocol correctly, but requires correct input events to do so.

That is a precise diagnosis with a clear owner. The library is fine; the demo's windowing layer cannot deliver the events the library needs. Any application built on libghostty-vt with a richer input stack would not have this problem, and any application built on it with Raylib will.

There is a second constraint that is easy to skip because it is in the list of things that could work. Windows support is not implemented in Ghostling itself and hasn't been tested there, even though libghostty-vt supports Windows. Since the build instructions in the README cover macOS and Linux only, with the Debian package list given in full, the practical reading is that this is a Unix-only demo as it stands.

And the correctness caveat from the top of the README still applies to all of it. The author says outright that not every place was carefully audited, in a language where a mistake is a memory bug rather than an exception. For a demo that is a reasonable trade, and for anything you build on it, the audit is yours.

MIT, no releases, and a repository organised around one file

The licence is MIT, with the LICENSE file at the root of the repository, so the code can be read, copied and built on without obligations beyond keeping the notice.

The release history is empty, the repository has no GitHub releases, and the last push to the repository was on 2026-08-09. For a demo, that is the right shape, and the versioning lives in the upstream library rather than here.

The repository listing shows the small surface: a .envrc for a development environment, a .github directory, an AGENTS.md, a CMakeLists.txt, the bin2header.cmake helper for embedding the fonts directory into the binary, the flake.nix and flake.lock for a Nix development environment, the demo.gif, and main.c.

The FAQ on other languages is worth reading if you are not writing C. libghostty-vt has a C API and can have zero dependencies, so it can be used with minimally thin bindings in basically any language. The author says he is not sure yet if the Ghostty project will maintain official bindings for languages other than C and Zig, and hopes the community will create and maintain bindings for many languages.

And the last FAQ entry is the one to remember when reading any of this. Why CMake, Raylib, and so on? The answer is that something had to be picked, any build system and any library could have been 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. The instruction is not to get bogged down in these details, which is the right instruction for a demonstration of the layer underneath.

Editorial conclusion

Ghostling fits a developer who wants to read one file and understand how a correct terminal emulator is wired, and who intends to put a real renderer and a real input stack underneath libghostty-vt in their own application. It does not fit someone who wants a terminal to use all day, since the README says outright that it is not meant to be a full featured daily use terminal and never will carry tabs, splits, session management or a configuration file. Before you build it, install Zig 0.16.x and the listed system packages, build in Release mode because debug builds are very slow, and read the Kitty keyboard protocol caveat before you rely on it.

Frequently asked questions

Official sources

1. ghostty-org/ghostling on GitHub
2. Issues
3. License: MIT
4. README