Terminal emulator powered by libghostty

Table of Contents 1. Quick Start 1.1. Shell integration at a glance 1.2. Input modes at a glance 2. Requirements 3. Installation 3.1. MELPA 3.2. use-package with :vc (Emacs 30+) 3.3. use-package with :load-path 3.4. Manual 3.5. Native module 3.6. Platform notes 3.6.1. Windows 4. Building from source 4.1. Bundled terminfo 5. Shell integration 6. Input modes 6.1. Mode-switch keybindings 6.2. Semi-char mode (default) 6.3. Char mode 6.4. Emacs mode 6.5. Copy mode 6.6. Mouse selection 6.7. Line mode 6.8. Scrollback search outside copy mode 7. Features 7.1. Terminal emulation 7.2. Process model 7.3. Bookmarks 7.4. Links and file detection 7.5. Clipboard 7.6. Input 7.7. Password prompt detection 7.8. Shell integration features 7.9. Rendering 7.10. Inline images (Kitty graphics protocol) 7.10.1. Limitations 7.11. Calling Elisp from the shell 7.12. Notifications and progress 7.13. Color palette 8. TRAMP (Remote Terminals) 8.1. Remote shell integration 8.1.1. Option 1: Automatic injection (recommended for convenience) 8.1.2. Option 2: Manual setup (recommended for permanent remote hosts) 8.2. Remote xterm-ghostty terminfo 8.2.1. TRAMP-launched ghostel 8.2.2. Outbound ssh from a local ghostel buffer 8.2.3. Manual install (no auto-machinery) 8.2.4. Drop the Ghostty advertisement entirely 9. Configuration 9.1. Process and environment 9.2. Native module 9.3. TRAMP and remote 9.4. Rendering and performance 9.5.

Images 9.6. Links, clipboard, and detection 9.7. Password prompts 9.8. Notifications and progress 9.9. Input and interaction 9.10. Line mode 10. Extensions 10.1. Evil-mode 10.2. Compilation mode 10.2.1. Live mode switching 10.2.2. Keybindings (ghostel-compile-view-mode, also active during a read-only run) 10.2.3. Make compile / recompile / project-compile use ghostel 10.2.4. Hooks for your own integrations 10.3. Eshell integration 10.4. Comint integration 10.5. Emacs Lisp input methods 11. Commands 11.1. Sending input from Lisp 11.2. Project integration 12. Running tests 13. Performance 13.1. Native vs Emacs PTY 13.2. Burst absorption (cat a 10 MB file) 13.3. Typing latency 14. Ghostel vs vterm and eat 14.1. Feature comparison 14.2. Key differences 15. Architecture 15.1. PTY and process ownership 15.2. Renderer and buffer positions 15.2.1. Renderer-owned buffer position preservation 15.2.2. Avoid around-redraw semantic patching in Elisp 16. Contributing 17. Changelog 18. License 19. Indices 19.1. Command and function index 19.2. Concept index Ghostel is an Emacs terminal emulator powered by libghostty-vt - the same VT engine that drives the Ghostty terminal. A native dynamic module written in Zig handles terminal state, rendering, and local PTY I/O; Elisp manages keymaps, buffers, commands, and remote process integration. Ghostel is inspired by emacs-libvterm and follows the same two-layer design, but uses Ghostty's modern VT engine instead of libvterm.

This brings the Kitty keyboard and graphics protocols, rich underline styles, OSC 8 hyperlinks, OSC 4/10/11 color queries, and synchronized output (DEC 2026) - none of which libvterm supports. See Ghostel vs vterm and eat for a detailed comparison. The native module is downloaded automatically on first use, so no toolchain is required for the common case. Open a terminal with M-x ghostel. Table of Contents 1. Quick Start 1.1. Shell integration at a glance 1.2. Input modes at a glance 2. Requirements 3. Installation 3.1. MELPA 3.2. use-package with :vc (Emacs 30+) 3.3. use-package with :load-path 3.4. Manual 3.5. Native module 3.6. Platform notes 3.6.1. Windows 4. Building from source 4.1. Bundled terminfo 5. Shell integration 6. Input modes 6.1. Mode-switch keybindings 6.2. Semi-char mode (default) 6.3. Char mode 6.4. Emacs mode 6.5. Copy mode 6.6. Mouse selection 6.7. Line mode 6.8. Scrollback search outside copy mode 7. Features 7.1. Terminal emulation 7.2. Process model 7.3. Bookmarks 7.4. Links and file detection 7.5. Clipboard 7.6. Input 7.7. Password prompt detection 7.8. Shell integration features 7.9. Rendering 7.10. Inline images (Kitty graphics protocol) 7.10.1. Limitations 7.11. Calling Elisp from the shell 7.12. Notifications and progress 7.13. Color palette 8. TRAMP (Remote Terminals) 8.1. Remote shell integration 8.1.1. Option 1: Automatic injection (recommended for convenience) 8.1.2. Option 2: Manual setup (recommended for permanent remote hosts) 8.2. Remote xterm-ghostty terminfo 8.2.1.

TRAMP-launched ghostel 8.2.2. Outbound ssh from a local ghostel buffer 8.2.3. Manual install (no auto-machinery) 8.2.4. Drop the Ghostty advertisement entirely 9. Configuration 9.1. Process and environment 9.2. Native module 9.3. TRAMP and remote 9.4. Rendering and performance 9.5. Images 9.6. Links, clipboard, and detection 9.7. Password prompts 9.8. Notifications and progress 9.9. Input and interaction 9.10. Line mode 10. Extensions 10.1. Evil-mode 10.2. Compilation mode 10.2.1. Live mode switching 10.2.2. Keybindings (ghostel-compile-view-mode, also active during a read-only run) 10.2.3. Make compile / recompile / project-compile use ghostel 10.2.4. Hooks for your own integrations 10.3. Eshell integration 10.4. Comint integration 10.5. Emacs Lisp input methods 11. Commands 11.1. Sending input from Lisp 11.2. Project integration 12. Running tests 13. Performance 13.1. Native vs Emacs PTY 13.2. Burst absorption (cat a 10 MB file) 13.3. Typing latency 14. Ghostel vs vterm and eat 14.1. Feature comparison 14.2. Key differences 15. Architecture 15.1. PTY and process ownership 15.2. Renderer and buffer positions 15.2.1. Renderer-owned buffer position preservation 15.2.2. Avoid around-redraw semantic patching in Elisp 16. Contributing 17. Changelog 18. License 19. Indices 19.1. Command and function index 19.2. Concept index 1. Quick Start (use-package ghostel :bind (("C-x m" .

ghostel) :map ghostel-semi-char-mode-map ("C-s" . consult-line) ("M-<backspace>" . ghostel-backward-kill-word) ("M-p" . (lambda () (interactive) (ghostel-send-key "p" "ctrl"))) ("M-n" . (lambda () (interactive) (ghostel-send-key "n" "ctrl"))) :map project-prefix-map ("m" . ghostel-project) ("M" . ghostel-project-list-buffers)) :config (defun ghostel-send-C-k-and-kill () "Send `C-k' to ghostel. Like normal Emacs `C-k'. Kill to end of line and put content in kill-ring." (interactive) (kill-ring-save (point) (line-end-position)) (ghostel-send-key "k" "ctrl")) (add-to-list 'project-switch-commands '(ghostel-project "Ghostel") t) (add-to-list 'project-switch-commands '(ghostel-project-list-buffers "Ghostel buffers") t) (add-to-list 'ghostel-eval-cmds '("magit-status-setup-buffer" magit-status-setup-buffer))) (use-package ghostel-eshell :hook (eshell-load . ghostel-eshell-visual-command-mode)) (use-package ghostel-compile :hook (after-init . ghostel-compile-global-mode)) (use-package ghostel-comint :hook (after-init . ghostel-comint-global-mode)) If you are an evil user you can install the evil-ghostel extension: (use-package evil-ghostel :after (ghostel evil) :hook (ghostel-mode . evil-ghostel-mode)) 1.1. Shell integration at a glance Directory tracking and prompt navigation are automatically on by default for local bash, zsh, or fish sessions. See shell integration for TRAMP support and more.

To call Emacs functions from your shell you have to add them to the ghostel-eval-cmds whitelist and then add something like this to your bashrc: if [[ "$INSIDE_EMACS" = 'ghostel' ]]; then e() { ghostel_cmd find-file-other-window "$@"; } dow() { ghostel_cmd dired-other-window "$@"; } gst() { ghostel_cmd magit-status-setup-buffer "$(pwd)"; } fi 1.2. Input modes at a glance Ghostel offers five eat.el-style input modes. The default is semi-char mode, which forwards almost all keys to the terminal besides a few exceptions (e.g. M-x, C-c). In char mode, all keys go to the terminal. Press M-RET to exit. In line mode Ghostel behaves like M-x shell: the buffer is a normal Emacs buffer and no key is sent to the terminal. Only after you finish typing a line and press RET is the whole line sent to the terminal at once. emacs mode and copy mode make the buffer temporarily a normal Emacs buffer that you can use to navigate, look around, and copy text. The difference between the two is that copy mode freezes the terminal, so if you have continuous output nothing "scrolls away" while you try to select something. emacs mode is live, so new output keeps coming in while you scroll and select. Those read-only modes have ghostel-readonly-fast-exit enabled by default (it defaults to t), which automatically exits them on most keys that you expect to be sent to the terminal. This makes for seamless transitions: say you have some output running and see something you want to copy - you press C-c C-t to enter copy mode, navigate like in a normal Emacs buffer, and select your text. When you copy something or type any character you are automatically back in your normal ghostel terminal session. Some actions also activate copy mode automatically, like selecting with the mouse, navigating to hyperlinks (C-c C-p), or activating the mark. 2. Requirements Emacs 28.1+ with dynamic module support macOS, Linux, FreeBSD, or native Windows The native module is automatically downloaded on first use.

Pre-built binaries are available for: aarch64-macos (Apple Silicon) x86_64-macos (Intel Mac) x86_64-linux aarch64-linux x86_64-freebsd x86_64-windows aarch64-windows If you prefer to build from source or need a different platform, you will also need Zig 0.15.2 - see Building from source. 3. Installation 3.1. MELPA (use-package ghostel :ensure t) 3.2. use-package with :vc (Emacs 30+) (use-package ghostel :vc (:url "https://github.com/dakra/ghostel" :lisp-dir "lisp" :rev :newest)) :lisp-dir "lisp" is only required on Emacs < 31.1. 3.3. use-package with :load-path (use-package ghostel :load-path "/path/to/ghostel/lisp") 3.4. Manual (add-to-list 'load-path "/path/to/ghostel/lisp") (require 'ghostel) Then M-x ghostel to open a terminal. 3.5. Native module When the native module is missing, Ghostel offers to download a pre-built binary or compile from source. This is controlled by ghostel-module-auto-install (default ask). You can also trigger these manually: M-x ghostel-download-module - download the minimum supported pre-built binary. C-u M-x ghostel-download-module - choose a specific release tag (leave blank for the latest). M-x ghostel-module-compile - build from source via zig build. By default the module is read from and written to the package directory. If your package manager rebuilds or reinstalls the tree while Emacs has the module loaded, point ghostel-module-directory at a stable location outside the package tree (for example ~/.config/emacs/ghostel/). 3.6. Platform notes 3.6.1. Windows Ghostel supports native Windows Emacs builds with dynamic module support. The pre-built release modules target the common x86_64 and aarch64 native Emacs architectures; the module DLL must match the architecture of Emacs, not merely the architecture of Windows itself.