From 1f2a3b8a830aad15a72fec41e386fa4db4ab6804 Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Sun, 22 Mar 2026 07:28:52 -0700 Subject: [PATCH] update README The README hasn't been updated in years basically! This updates the README to make libghostty a first class citizen of the project and to update our roadmap and goals for the project to more accurately reflect our current state and future plans. --- README.md | 143 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 961968097..293f5a6e2 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@

Fast, native, feature-rich terminal emulator pushing modern features.
+ A native GUI or embeddable library via libghostty. +
About · Download @@ -26,20 +28,13 @@ fast, feature-rich, and native. While there are many excellent terminal emulators available, they all force you to choose between speed, features, or native UIs. Ghostty provides all three. -In all categories, I am not trying to claim that Ghostty is the -best (i.e. the fastest, most feature-rich, or most native). But -Ghostty is competitive in all three categories and Ghostty -doesn't make you choose between them. - -Ghostty also intends to push the boundaries of what is possible with a -terminal emulator by exposing modern, opt-in features that enable CLI tool -developers to build more feature rich, interactive applications. - -While aiming for this ambitious goal, our first step is to make Ghostty -one of the best fully standards compliant terminal emulator, remaining -compatible with all existing shells and software while supporting all of -the latest terminal innovations in the ecosystem. You can use Ghostty -as a drop-in replacement for your existing terminal emulator. +**`libghostty`** is a cross-platform, zero-dependency C and Zig library +for building terminal emulators or utilizing terminal functionality +(such as style parsing). Anyone can use `libghostty` to build a terminal +emulator or embed a terminal into their own applications. See +[Ghostling](https://github.com/ghostty-org/ghostling) for a minimal complete project +example or the [`examples` directory](https://github.com/ghostty-org/ghostty/tree/main/example) +for smaller examples of using `libghostty` in C and Zig. For more details, see [About Ghostty](https://ghostty.org/docs/about). @@ -61,30 +56,37 @@ to get involved with Ghostty's development as well should also read the ## Roadmap and Status +Ghostty is stable and in use by millions of people and machines daily. + The high-level ambitious plan for the project, in order: -| # | Step | Status | -| :-: | --------------------------------------------------------- | :----: | -| 1 | Standards-compliant terminal emulation | ✅ | -| 2 | Competitive performance | ✅ | -| 3 | Basic customizability -- fonts, bg colors, etc. | ✅ | -| 4 | Richer windowing features -- multi-window, tabbing, panes | ✅ | -| 5 | Native Platform Experiences (i.e. Mac Preference Panel) | ⚠️ | -| 6 | Cross-platform `libghostty` for Embeddable Terminals | ⚠️ | -| 7 | Windows Terminals (including PowerShell, Cmd, WSL) | ❌ | -| N | Fancy features (to be expanded upon later) | ❌ | +| # | Step | Status | +| :-: | ------------------------------------------------------- | :----: | +| 1 | Standards-compliant terminal emulation | ✅ | +| 2 | Competitive performance | ✅ | +| 3 | Rich windowing features -- multi-window, tabbing, panes | ✅ | +| 4 | Native Platform Experiences | ✅ | +| 5 | Cross-platform `libghostty` for Embeddable Terminals | ✅ | +| 6 | Ghostty-only Terminal Control Sequences | ❌ | Additional details for each step in the big roadmap below: #### Standards-Compliant Terminal Emulation -Ghostty implements enough control sequences to be used by hundreds of -testers daily for over the past year. Further, we've done a -[comprehensive xterm audit](https://github.com/ghostty-org/ghostty/issues/632) +Ghostty implements all of the regularly used control sequences and +can run every mainstream terminal program without issue. For legacy sequences, +we've done a [comprehensive xterm audit](https://github.com/ghostty-org/ghostty/issues/632) comparing Ghostty's behavior to xterm and building a set of conformance test cases. -We believe Ghostty is one of the most compliant terminal emulators available. +In addition to legacy sequences (what you'd call real "terminal" emulation), +Ghostty also supports more modern sequences than almost any other terminal +emulator. These features include things like the Kitty graphics protocol, +Kitty image protocol, clipboard sequences, synchronized rendering, +light/dark mode notifications, and many, many more. + +We believe Ghostty is one of the most compliant and feature-rich terminal +emulators available. Terminal behavior is partially a de jure standard (i.e. [ECMA-48](https://ecma-international.org/publications-and-standards/standards/ecma-48/)) @@ -96,33 +98,30 @@ views as a "standard." #### Competitive Performance -We need better benchmarks to continuously verify this, but Ghostty is -generally in the same performance category as the other highest performing -terminal emulators. +Ghostty is generally in the same performance category as the other highest +performing terminal emulators. -For rendering, we have a multi-renderer architecture that uses OpenGL on -Linux and Metal on macOS. As far as I'm aware, we're the only terminal -emulator other than iTerm that uses Metal directly. And we're the only -terminal emulator that has a Metal renderer that supports ligatures (iTerm -uses a CPU renderer if ligatures are enabled). We can maintain around 60fps -under heavy load and much more generally -- though the terminal is -usually rendering much lower due to little screen changes. +"The same performance category" means that Ghostty is much faster than +traditional or "slow" terminals and is within an unnoticeable margin of the +well-known "fast" terminals. For example, Ghostty and Alacritty are usually within +a few percentage points of each other on various benchmarks, but are both +something like 100x faster than Terminal.app and iTerm. However, Ghostty +is much more feature rich than Alacritty and has a much more native app +experience. -For IO, we have a dedicated IO thread that maintains very little jitter -under heavy IO load (i.e. `cat .txt`). On benchmarks for IO, -we're usually within a small margin of other fast terminal emulators. -For example, reading a dump of plain text is 4x faster compared to iTerm and -Kitty, and 2x faster than Terminal.app. Alacritty is very fast but we're still -around the same speed (give or take) and our app experience is much more -feature rich. +This performance is achieved through high-level architectural decisions and +low-level optimizations. At a high-level, Ghostty has a multi-threaded +architecture with a dedicated read thread, write thread, and render thread +per terminal. Our renderer uses OpenGL on Linux and Metal on macOS. +Our read thread has a heavily optimized terminal parser that leverages +CPU-specific SIMD instructions. Etc. -> [!NOTE] -> Despite being _very fast_, there is a lot of room for improvement here. - -#### Richer Windowing Features +#### Rich Windowing Features The Mac and Linux (build with GTK) apps support multi-window, tabbing, and -splits. +splits with additional features such as tab renaming, coloring, etc. These +features allow for a higher degree of organization and customization than +single-window terminals. #### Native Platform Experiences @@ -133,10 +132,15 @@ in Zig but we do a lot of platform-native things: - The macOS app is a true SwiftUI-based application with all the things you would expect such as real windowing, menu bars, a settings GUI, etc. - macOS uses a true Metal renderer with CoreText for font discovery. +- macOS supports AppleScript, Apple Shortcuts (AppIntents), etc. - The Linux app is built with GTK. +- The Linux app integrates deeply with systemd if available for things + like always-on, new windows in a single instance, cgroup isolation, etc. -There are more improvements to be made. The macOS settings window is still -a work-in-progress. Similar improvements will follow with Linux. +Our goal with Ghostty is for users of whatever platform they run Ghostty +on to think that Ghostty was built for their platform first and maybe even +exclusively. We want Ghostty to feel like a native app on every platform, +for the best definition of "native" on each platform. #### Cross-platform `libghostty` for Embeddable Terminals @@ -151,15 +155,34 @@ terminal state. This is covered in more detail in this [blog post](https://mitchellh.com/writing/libghostty-is-coming). `libghostty-vt` is already available and usable today for Zig and C and -is compatible for macOS, Linux, Windows, and WebAssembly. At the time of -writing this, the API isn't stable yet and we haven't tagged an official -release, but the core logic is well proven (since Ghostty uses it) and -we're working hard on it now. +is compatible for macOS, Linux, Windows, and WebAssembly. The functionality +is extremely stable (since its been proven in Ghostty GUI for a long time), +but the API signatures are still in flux. -The ultimate goal is not hypothetical! The macOS app is a `libghostty` consumer. -The macOS app is a native Swift app developed in Xcode and `main()` is -within Swift. The Swift app links to `libghostty` and uses the C API to -render terminals. +`libghostty` is already heavily in use. See [`examples`](https://github.com/ghostty-org/ghostty/tree/main/example) +for small examples of using `libghostty` in C and Zig or the +[Ghostling](https://github.com/ghostty-org/ghostling) project for a +complete example. See [awesome-libghostty](https://github.com/Uzaaft/awesome-libghostty) +for a list of projects and resources related to `libghostty`. + +We haven't tagged libghostty with a version yet and we're still working +on a better docs experience, but our [Doxygen website](https://libghostty.tip.ghostty.org/) +is a good resource for the C API. + +#### Ghostty-only Terminal Control Sequences + +We want and believe that terminal applications can and should be able +to do so much more. We've worked hard to support a wide variety of modern +sequences created by other terminal emulators towards this end, but we also +want to fill the gaps by creating our own sequences. + +We've been hesitant to do this up until now because we don't want to create +more fragmentation in the terminal ecosystem by creating sequences that only +work in Ghostty. But, we do want to balance that with the desire to push the +terminal forward with stagnant standards and the slow pace of change in the +terminal ecosystem. + +We haven't done any of this yet. ## Crash Reports