Ghostel: A High-Performance Emacs Terminal Emulator powered by libghostty

Ghostel: A High-Performance Emacs Terminal Emulator powered by libghostty

Ghostel is a high-performance terminal emulator for Emacs that leverages libghostty-vt, the same VT engine powering the Ghostty terminal. By using a native dynamic module written in Zig, Ghostel offloads terminal state management, rendering, and local PTY I/O from the Emacs main thread, resulting in significant performance gains and support for modern terminal protocols that are typically unavailable in Emacs.

Key Takeaways

Ghostel provides a modern alternative to vterm and eat, offering substantially higher throughput (up to 75 MB/s) and support for the Kitty graphics and keyboard protocols. Its architecture allows for a responsive UI even during massive data bursts, while its deep integration with Emacs enables features like password prompt detection, clickable file paths, and the ability to call Elisp functions directly from the shell.

Performance and Architecture

Ghostel is designed to solve the "frozen UI" problem common in terminal emulators that parse output on the Emacs main thread.

Native PTY and Asynchronous Processing

For local terminals, Ghostel uses a native PTY path. A Zig background thread reads PTY output and updates the terminal state asynchronously. Emacs is notified only when a redraw or a specific callback (like an OSC handler) is required. This prevents large log streams from blocking the Emacs event loop.

Throughput Benchmarks

In benchmarks on an Apple M4 Max, Ghostel significantly outperforms other popular Emacs terminals in plain-ASCII throughput:

Backend Plain ASCII URL-heavy
Ghostel 75 MB/s 36 MB/s
vterm 18 MB/s 15 MB/s
eat 6.2 MB/s 4.5 MB/s
term 7.2 MB/s 5.9 MB/s

Burst Absorption

When processing a 10 MB cat command, Ghostel's native PTY path absorbs the data in approximately 110ms—roughly 5x faster than vterm and 16x faster than eat. Because the parsing happens on a background thread, the Emacs UI remains responsive throughout the process.

Advanced Terminal Features

By utilizing libghostty-vt, Ghostel brings several modern capabilities to Emacs:

  • Kitty Graphics Protocol: Supports inline images (PNG, RGB, RGBA) rendered via Emacs's built-in image support. This allows tools like yazi or timg to display images directly in the buffer.
  • Synchronized Output (DEC 2026): Eliminates choppy partial-redraws in modern TUIs (e.g., Claude Code).
  • Rich Text Attributes: Supports five types of underlines (single, double, curly, dotted, dashed) with independent colors, as well as faint/dim text and strikethrough.
  • OSC 8 Hyperlinks: Native support for clickable URLs emitted by terminal programs.
  • Color Queries: Supports OSC 4/10/11, allowing TUI programs to auto-detect the Emacs theme's light/dark mode.

Input Modes and User Experience

Ghostel implements five distinct input modes to balance terminal control with Emacs productivity:

  1. Semi-char mode (Default): Most keys go to the terminal, but a few (e.g., C-x, M-x) are reserved for Emacs.
  2. Char mode: All keys are forwarded to the terminal; used for TUIs that bind reserved Emacs keys.
  3. Emacs mode: The buffer becomes a read-only view. The terminal continues to run, but the user can use standard Emacs navigation and search without affecting the shell.
  4. Copy mode: Similar to Emacs mode, but the terminal is frozen, providing a stable snapshot for precise text selection.
  5. Line mode: Input is buffered locally in Emacs for full editing (using Emacs keys) and sent to the shell atomically upon pressing RET.

Deep Emacs Integration

Ghostel extends the terminal experience by bridging the gap between the shell and the editor:

  • Password Prompt Detection: Ghostel detects when a program (like sudo or ssh) requests a password. It opens a native Emacs read-passwd prompt, ensuring the password never enters the view-lossage or keyboard-macro recordings.
  • Calling Elisp from Shell: Through a whitelisted system (ghostel-eval-cmds), shell scripts can trigger Emacs functions. For example, a shell alias can be created to open the current directory in Dired via ghostel_cmd dired-other-window "$(pwd)".
  • TRAMP Support: Ghostel integrates with TRAMP for remote terminals. It includes automated terminfo installation for xterm-ghostty on remote hosts to ensure that remote TUIs maintain their high-fidelity rendering.
  • Compilation Mode: ghostel-compile provides a TTY-backed alternative to M-x compile, allowing programs that require a real TTY (for colors or progress bars) to run while maintaining the compilation-mode UX for error navigation.

Community Insights

Early adopters report that Ghostel is a viable daily driver, though some polish remains. Users have highlighted the utility of clicking code references in summaries to open them directly in Emacs buffers. However, some users have noted occasional issues with terminal clearing or rare freezes, suggesting that while the performance is a breakthrough, the project is still maturing.

"I recently switched from vterm to ghostel, and it is generally much, much better - noticeably faster... more reliable input handling, and a nicer ELisp API."

Installation

Ghostel is available via MELPA. The native module is automatically downloaded on first use, removing the need for a local Zig toolchain for most users.

(use-package ghostel
  :ensure t)

Sources