In-depth articles on technology shaping what comes next.

Libghostty 1.0: Lessons in Stable C ABI Design

Libghostty 1.0 shows how to design a stable C ABI: opaque handles, enum-keyed setters, CI-enforced symbol versioning, and library-first architecture.

Illustration of one shared glowing core powering many different terminal-like screens connected by threads of light.
One emulation core, many faces: libghostty now sits inside IDEs, editors, TUIs, and new terminals alike.

Imagine you're on the team that owns the terminal inside JetBrains IDEs. Your emulator, JediTerm, has a bug — the kind of bug terminal emulators specialize in, where some obscure escape sequence renders wrong in a way that's maddening to reproduce. You could patch it. Or you could delete a decade of accumulated emulation code and link against a C library with a stable ABI that someone else maintains, fuzzes, and ports to nine operating systems for you. JetBrains chose the second option. Every IntelliJ, PyCharm, and GoLand user — over 12.5 million active users, by JetBrains' own reporting — now runs a terminal powered by libghostty, which hit 1.0 this week.

That's the headline number, but the more interesting story is underneath it. Libghostty is the terminal-emulation core carved out of Ghostty, Mitchell Hashimoto's GPU-accelerated terminal, and released as a standalone C library with an enforced ABI stability policy. A year ago it had no C API and exactly one consumer. Today it has a tagged 1.0, distribution-ready packaging, and an adoption list that reads like a who's who of developer tooling. How you get from "app with internals" to "library the industry trusts" is a lesson in engineering discipline that applies far beyond terminals.

From App to Library: How libghostty Was Carved Out

Terminal emulation is one of those problem domains that looks easy from a distance and is quietly brutal up close. Decades of escape sequences, competing graphics protocols, Unicode grapheme clustering, scrollback reflow on resize — every terminal author rediscovers the same minefield. I've written before about how modern GPU-accelerated terminals work, from TTY parsing to glyph atlases, and the consistent theme is that the emulation layer is where correctness goes to die. It's exactly the kind of code you want to write once, test to death, and share.

Ghostty's author seems to have understood this from the start. The application was built in Zig with its emulation core structured so it could be separated — first as a Zig module, then behind a C API, now as libghostty-vt 1.0 with its own release cycle, its own tarballs, and its own consumers. The extraction wasn't an afterthought or a marketing gesture; the project announced the intent over a year before the C API existed, then spent that year making the boundary real. The order of operations matters: the library wasn't promoted to 1.0 when the code worked, but when the contract around the code was stable enough to promise things about.

The consumer list suggests the bet paid off. Neovim has an approved pull request replacing libvterm with libghostty-vt — a change that closes a ten-year-old issue about scrollback reflow on resize, which tells you something about how long these wounds stay open when every project maintains its own emulator. KDE developers are prototyping a Konsole successor on it. Vercel's Turborepo uses it to render task output. Antithesis used it to fuzz TUI programs and surfaced real bugs in btop. Someone built an Emacs terminal on it, and there's a WebAssembly build with an xterm.js-compatible API. Community bindings exist for Rust, Go, JavaScript, Swift, Python, .NET, Elixir, Dart, and Java.

Designing a Stable C ABI: Opaque Handles and Enum Keys

Here's the part worth stealing for your own projects. Most C libraries fail at longevity not because the code rots, but because the ABI calcifies: a struct gains a field and every consumer needs recompiling, a function signature changes and symbols vanish, an enum grows and shifts values. Libghostty's design is a short masterclass in avoiding all three, and the techniques are old, proven, and chronically underused.

/* The clunky way: the struct IS the ABI.
* Add a field and every consumer recompiles or corrupts memory. */
typedef struct {
int rows;
int cols;
int scrollback_limit;
/* ... forty more fields your ABI now depends on forever */
} term_config_t;
/* The libghostty way: an opaque handle plus enum-keyed access.
* The library can add a hundred new settings without one new symbol. */
typedef struct ghostty_terminal_s ghostty_terminal_t;
typedef enum {
GHOSTTY_TERMINAL_ROWS,
GHOSTTY_TERMINAL_COLS,
GHOSTTY_TERMINAL_SCROLLBACK_LIMIT,
/* new keys append here, forever */
} ghostty_terminal_key_t;
ghostty_result_t ghostty_terminal_get(
const ghostty_terminal_t *terminal,
ghostty_terminal_key_t key,
void *out);
ghostty_result_t ghostty_terminal_set(
ghostty_terminal_t *terminal,
ghostty_terminal_key_t key,
const void *value);

Three decisions do the heavy lifting. First, every object is an opaque handle: callers hold pointers, never structs, so the library can reshape its internals freely between releases. Second, the hundreds of readable and writable values live behind a small set of enum-keyed getters and setters. New functionality means a new enum constant, not a new exported symbol — and a program built against newer headers but running against an older library gets a clean GHOSTTY_UNSUPPORTED result instead of a crash or silent garbage. That one detail is the difference between graceful degradation and a 3 a.m. segfault in someone else's product.

Third, the few structs that are public carry their own size, or reserve padding, so fields can be appended without breaking layout — the same trick sockaddr and the Win32 API have used for decades. Enums are pinned to int on every compiler, as far as the C standard permits, because an enum whose underlying type shifts between compilers is an ABI time bomb. None of this is exotic. All of it is the kind of thing you only do if you decide, on day one, that the ABI is a product feature rather than an accident of the current source layout. This is the specification-implementation gap in its purest form: the ABI is the specification, and everything else is negotiable.

  • Opaque handles for everything. Callers never see layout, so layout is free to change.
  • Enum-keyed getters and setters. New settings are new constants, not new symbols — and old libraries answer GHOSTTY_UNSUPPORTED instead of crashing.
  • Self-sizing public structs. A struct_size field lets you append fields later; reserved padding buys future room.
  • Pinned enum types. Enums fixed to int so the ABI doesn't shift between compilers.
  • Versioned symbols on ELF. The dynamic loader refuses a mismatched library by name, loudly, at load time — not mysteriously, at runtime.

Enforcing ABI Stability in CI, Not in Good Intentions

Every project claims backward compatibility. Almost none can prove it on a random Tuesday. Libghostty's CI runs libabigail against a committed baseline on Linux, checking every change for ABI drift, and compares golden type manifests on macOS and WebAssembly. Exported symbols on ELF platforms are versioned, so the loader itself becomes an enforcement mechanism. The promise isn't maintained by code review and vigilance; it's maintained by machines that fail the build when a human slips.

An ABI isn't a contract you sign once. It's a promise your CI has to keep on every single commit.

This is the piece I'd urge every library author to copy first, before any of the API design. Automated ABI checking is cheap to set up — libabigail's abidiff is a single tool — and it converts a fuzzy social promise ("we try not to break things") into a hard, reviewable artifact ("here is the baseline; here is the diff; this change is or isn't compatible"). Distributions deciding whether to package your library, and companies deciding whether to dynamically link it, are really evaluating that artifact. The reason Neovim's maintainers were waiting on a tagged release before merging isn't ceremony — it's that distributions need a versioned, separately packageable dependency with a compatibility story they can defend.

A sentry figure measuring a stone bridge at its entrance, checking it before allowing passage.
ABI stability enforced like a checkpoint: every change is measured against the baseline before it crosses.

Packaging and Licensing: The Boring Work That Ships Libraries

Ask any distribution maintainer what kills a library's chances and they'll rarely say "the code." It's the build that doesn't honor --prefix or DESTDIR, the missing SONAME, the vendored dependencies with unclear licenses, the tarball that can't build offline. Libghostty 1.0 treats all of this as release surface: signed source tarballs, a companion dependencies tarball in Zig's cache layout for fully offline builds, proper SONAMEs, pkg-config files, CMake package configs, debug info kept by default so distros can strip it. There's a PACKAGING-LIBGHOSTTY.md that ships in the tarball — written for the packager, not the end user.

Licensing got the same treatment, and it's more strategic than it looks. The library is MIT, needs nothing beyond libc at runtime (and can be built freestanding without even that), and compiles in a handful of permissively licensed dependencies — simdutf and Google Highway for SIMD, a compact Unicode table, Wuffs for Kitty graphics decoding — built without libc++ so there's no C++ standard library dependency. Zero copyleft anywhere in the tree. Every dependency is listed in a machine-readable manifest with version, SPDX license, and hash, specifically so distros can fill in bundled-library metadata without archaeology. There's even a build flag to dynamically link the system simdutf or Highway instead.

Every one of those choices removes a specific objection a specific gatekeeper would have raised. That's what "enterprise-ready" actually means in practice — not a sales page, but a hundred small frictions sanded off before anyone had to ask. It's also a reminder of why great software takes time: none of this work is hard, and all of it is slow.

Portability and Resource Discipline as API Promises

The tested platform matrix spans Linux (glibc and musl), macOS, iOS, FreeBSD, Windows, Android, and freestanding WebAssembly, with a second tier — bare-metal RISC-V and ARM thumb, WASI, Windows ARM64, illumos, 32-bit x86 — that builds in CI but doesn't run tests yet. Each platform gets the artifacts its ecosystem expects: dylibs with @rpath and XCFrameworks for Apple, a DLL with PDB and import library for Windows (MSVC linking verified in CI), a 16 KB-page-size Android build for Android 15+, and a WASM module under a megabyte with every feature on — halvable by compiling out subsystems like search, selection, and Kitty graphics, with every function still exported and returning GHOSTTY_UNSUPPORTED so embedder code never has to change.

But the portability story I keep coming back to is behavioral. The library creates no threads. It allocates only through an allocator you supply. The author reports running 10,000 live terminals, each driving a real shell producing output, on a 4-core, 8 GB Linux server — and notes the bottleneck was bash's memory appetite, not the library's; he had to switch to dash to fit the shells in RAM while libghostty-vt hummed along. "We don't spawn threads" and "we don't own your allocator" are API promises as real as any function signature, and they're what make a library embeddable in contexts — game engines, embedded devices, fuzzing harnesses, other people's event loops — where a thread-happy dependency would be a dealbreaker.

What libghostty Teaches About Library-First Architecture

The obvious comparison is libvte, the GTK-bound emulation library underneath GNOME Terminal, XFCE's terminal, and half a dozen others. Libvte proved the model years ago — one shared core, many thin wrappers — but its GTK coupling narrowed its world to Linux desktops with a specific toolkit. Libghostty's bet is that the same model, decoupled from any UI toolkit and hardened into a stable C ABI, travels much further: into IDEs written in Java, editors written in C, TUIs written in Go, browsers via WASM, and commercial products that could never ship a GTK dependency. Early evidence says the bet is right. More people already use a libghostty-powered terminal than use Ghostty itself, by a large multiple.

The deeper lesson is about sequencing. Library-first architecture doesn't mean writing a library before you have a use case — that's how you get beautiful abstractions nobody needs. Ghostty did the opposite: it built a real application, let the domain boundaries emerge under production pressure, and then hardened the seam it had been maintaining all along. The C API arrived late, which is precisely why it arrived clean. If you're sitting on an application with a genuinely hard, reusable core — a parser, an emulator, a layout engine, a protocol stack — the playbook is visible here: keep the boundary honest from the start, expose it through the narrowest possible contract, put the ABI under CI surveillance, and do the packaging drudgery like you mean it. The ecosystem effects compound from there. Every bug one embedder reports makes every other consumer's terminal better, and every new protocol lands everywhere at once instead of fragmenting across a dozen private forks.

Hashimoto claims you can now build a terminal in roughly 1,500 lines of C that out-features nearly anything that existed a year ago. That's the kind of sentence I'd normally file under maintainer enthusiasm — except that a hundred-plus tracked projects and the entire JetBrains IDE fleet suggest the claim survives contact with reality. The era of every application hand-rolling its own terminal emulator may finally be ending, and it ended the way these things usually do: not with a better application, but with a better library.