ghostel.el - Terminal emulator powered by libghostty

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
    # Open a file in Emacs from the terminal
    e()   { ghostel_cmd find-file-other-window "$@"; }

    # Open dired in another window
    dow() { ghostel_cmd dired-other-window "$@"; }

    # Open magit for the current directory
    gst() { ghostel_cmd magit-status-setup-buffer "$(pwd)"; }
fi

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.

(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.

(add-to-list 'load-path "/path/to/ghostel/lisp")
(require 'ghostel)

Then M-x ghostel to open a terminal.

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/).

The compiled xterm-ghostty terminfo entry ships pre-built in etc/terminfo/ and is identical to what tic would produce locally - no build step needed, and the file format is portable across BSD and ncurses systems. Maintainers regenerate it via make regen-terminfo after bumping libghostty.

Available from every mode except char mode:

Most keys are sent to the terminal. Keys in ghostel-keymap-exceptions (default: C-c, C-x, C-u, C-h, M-x, M-:, C-\) pass through to Emacs.

Entered with C-c M-d. All keys (including ghostel-keymap-exceptions) are sent to the terminal. Useful for TUI apps that want to bind C-x, M-x, C-h, etc. themselves. M-RET (or C-M-m) is the sole escape hatch.

Entered with C-c C-e. The terminal keeps running, the buffer is read-only, and standard Emacs bindings fall through to the global map. isearch-forward, occur, M-x, C-SPC + M-w, arrow keys, wheel scroll - all work unmodified. The terminal keeps producing output and the buffer keeps growing, but your point stays where you navigated it (the delayed-redraw path preserves point in Emacs mode).

Typed keys do not reach the shell - Emacs mode is a "look but don't touch" view. Self-insert, RET, TAB, DEL fall through to the read-only buffer and trigger text-read-only, so a stray keystroke cannot accidentally land at the prompt. Switch to semi-char mode (C-c C-j) when you want to type to the shell. C-y is the exception: it pastes via bracketed paste as a deliberate action and snaps point back to the live cursor.

C-c C-e toggles Emacs mode off again (returning to the mode you came from), and C-c C-t switches to copy mode to freeze the output.

Use this for searching through scrollback while a build is running, filtering streaming logs with M-x occur, marking and copying across the visible history, or running any buffer-based command over the terminal's output without having to freeze it.

Entered with C-c C-t. The terminal is frozen - no live output updates the buffer until you exit. Use this when you want to select text precisely without the terminal scrolling underneath your cursor. The aggressive copy-mode keymap exits on self-insert, so typing a letter sends it to the terminal and returns to semi-char mode (controlled by ghostel-readonly-fast-exit).

C-c C-t toggles copy mode off again, and C-c C-e switches to Emacs mode - read-only but live, so output resumes - without going through semi-char.

Soft-wrapped newlines are automatically stripped from copied text.

Click-and-drag inside a ghostel buffer creates a region. On release, ghostel-mouse-drag-or-set-region switches input mode so streaming terminal output cannot clobber the selection - the target is picked by ghostel-mouse-drag-input-mode (default copy):

• copy - enter copy mode. Redraws pause; the selection is stable regardless of where it sits.
• emacs - enter Emacs mode. The terminal keeps streaming and the buffer becomes read-only; selections wholly in scrollback survive, selections over rows the live program rewrites can still be lost.
• nil - stay in semi-char. Same selection-survival guarantees as emacs, but M-w is forwarded to the shell so it cannot copy the region - pick this only if you copy via primary selection or the GUI menu.

A single click inside a window that is already selected sets point and then switches input mode per ghostel-mouse-drag-input-mode, the same as a drag. A click that focuses a previously-unselected window only gives that window focus: point lands at the terminal's input cursor (not the click) and the input mode is unchanged. A click meant just to focus a window therefore never freezes the buffer. (Set ghostel-mouse-drag-input-mode to nil to turn the click feature off, so a click sets point like in any Emacs buffer.) When a TUI has DEC mouse-tracking enabled (1000/1002/1003 - htop, lazygit, etc.) the click is forwarded to the program and none of the above applies.

Double- and triple-click select the word and line under the cursor respectively, and protect that region the same way a drag does (from any window, focused or not).

The same protection exists for keyboard selections: when a command activates the mark in semi-char mode - C-SPC (set-mark-command), an expand-region variant, C-x h, anything that turns the region on - ghostel switches to the input mode picked by ghostel-mark-activation-input-mode (copy by default, emacs, or nil to stay in semi-char). This hooks mark activation rather than any particular key, so custom bindings like set-mark-or-expand trigger it too. Note that on a TTY Ctrl+Space is indistinguishable from C-@ (NUL) and is forwarded to the terminal instead; in char mode Ctrl+Space always reaches the terminal as NUL (GUI and TTY alike).

Entered with C-c C-l. Line mode buffers the user's input locally in Emacs - no keystrokes are forwarded to the shell while composing. Full Emacs editing (M-b, M-DEL, C-y yank, transpose-words, etc.) works on the input region. Pressing RET sends the whole line to the shell in one write; bash receives it atomically, echoes and executes it.

The terminal stays live: output keeps streaming and the buffer keeps re-rendering while you compose. A snapshot/restore step in the delayed-redraw path captures the in-progress input before each redraw and re-inserts it at the new prompt-end afterwards, so async output or a fresh prompt arriving mid-edit does not clobber what you typed. After RET, line mode stays active - the next prompt is found on the following redraw cycle and the input marker moves there.

Line mode uses the terminal cursor as the input-area boundary, so REPLs without shell integration (python3, irb, sqlite3, …) work too. When OSC 133 prompt markers are present on the cursor's row, the prompt prefix is recognised and the input boundary lands right after it. As a fallback without OSC 133, the prompt prefix is matched against ghostel-prompt-regexp.

Line mode and fullscreen TUIs (vim, less, htop, …) cannot share the same keystroke stream - the TUI needs every key forwarded raw, while line mode buffers them locally. Ghostel handles this transparently: when an alt-screen TUI starts, line mode drops to semi-char so the TUI gets its keys, with a brief message that it will resume on exit. When the TUI exits, line mode resumes at the new prompt.

Pressing C-c C-l on the alt screen does the right thing for what is running. Over a raw TUI it arms that same auto-resume, so line mode activates when the TUI exits; an explicit mode switch (C-c C-j, ghostel-char-mode, etc.) cancels the arming. At an inner shell prompt - a tmux=/=screen session whose OSC 133 markers reach Ghostel via passthrough - C-c C-l enters line mode at that prompt directly. When those markers do not pass through, C-u C-c C-l forces entry anyway.

TAB completes the input via ghostel-line-mode-completion-at-point-functions (comint filename/command completion by default), and optionally layers bash programmable completion on top via ghostel-line-mode-use-bash-completion.

The full scrollback is always rendered into the buffer as styled text, so isearch, consult-line, occur, M-x flush-lines, C-x h to select all, and any other buffer-based command work across the full history in any mode that has a read-only buffer (Emacs or copy).

• Full VT terminal emulation via libghostty-vt.
• 256-color and RGB (24-bit true color) support.
• TERM=xterm-ghostty with bundled terminfo - apps that consult terminfo for capabilities (Claude Code, neovim, tmux, modern TUIs) discover synchronized output (DEC 2026), the Kitty keyboard protocol, true color, colored underlines, focus reporting, etc., and use their fast paths. Synchronized output in particular eliminates the choppy partial-redraw effect when Claude Code repaints over a large scrollback. OSC 52 (clipboard) is supported but intentionally not advertised in the bundled terminfo (see Clipboard). Override via ghostel-term.
• OSC 4 / 10 / 11 color queries - TUI programs can query the current palette, foreground, and background colors, so tools like duf, btop, delta, and anything else using termenv auto-detect the right light/dark theme from the Emacs face colors.
• OSC 9 / OSC 777 - desktop notifications and ConEmu progress reports (see Notifications and Progress).
• Text attributes: bold, italic, faint, underline (single/double/curly/dotted/dashed, with color), strikethrough, inverse.
• Cursor styles: block, bar, underline, hollow block.
• Alternate screen buffer (for TUI apps like htop, vim, etc.).
• Scrollback buffer (configurable, default 5 MB / ~5,000 lines, materialized into the Emacs buffer so isearch / consult-line work over history).

Local ghostel buffers use a native PTY path by default (ghostel-use-native-pty). The native reader consumes PTY output on a background thread, updates libghostty-vt asynchronously, and notifies Emacs through an event pipe when callbacks or redraws are needed. This keeps large log streams and full-screen TUI redraws from running through Emacs process filters byte-for-byte.

Remote TRAMP buffers still use Emacs process machinery so TRAMP can spawn the shell on the remote host and apply its file handlers. The rendering and input APIs are shared by both paths.

• OSC 8 hyperlinks - clickable URLs emitted by terminal programs (click or RET to open).
• Plain-text URL detection - automatically linkifies http:// and https:// URLs even without OSC 8 (toggle with ghostel-enable-url-detection).
• File path detection - patterns like /path/to/file.el:42 become clickable, opening the file at the given line (toggle with ghostel-enable-file-detection; tune the path pattern with ghostel-file-detection-path-regex).

• OSC 52 clipboard - terminal programs can set the Emacs kill ring and system clipboard (opt-in via ghostel-enable-osc52, useful for remote SSH sessions). The bundled xterm-ghostty terminfo intentionally does not advertise the Ms capability, so apps do not auto-discover it. This avoids silent clipboard drops when ghostel-enable-osc52 is at its default nil. If you enable OSC 52 and want apps (neovim, tmux) to auto-detect it, install upstream Ghostty's terminfo on the same path or override TERMINFO.
• Bracketed paste - yank from the kill ring sends text as a bracketed paste so shells handle it correctly.

• Full keyboard input with the Ghostty key encoder (respects terminal modes, Kitty keyboard protocol).
• Mouse tracking (press, release, drag) via the SGR mouse protocol - TUI apps receive full mouse input.
• Focus events gated by DEC mode 1004.
• Drag-and-drop (file paths and text).

When sudo, ssh, gpg, passwd, etc. ask for a password, ghostel pops up read-passwd and sends the answer through the PTY - keystrokes never flow through Emacs's normal key pipeline, so the password does not land in view-lossage, the recent-keys ring, or any keyboard-macro recording. This is controlled by ghostel-detect-password-prompts (default t).

Detection has two layers. The primary signal mirrors libghostty's heuristic: the slave tty is in canonical mode with echo off, read via a small tcgetattr Zig binding. This catches local programs that flip !ECHO (sudo, ssh's own prompt, gpg, …). A cursor-row regex fallback (ghostel-password-prompt-regex, defaulting to comint-password-prompt-regexp) covers cases the tty signal cannot see, but runs only when the foreground shell is on a remote host (ghostel--remote-shell-p, derived from the TRAMP default-directory ghostel keeps in sync via OSC 7). Gating it on remote-only avoids false positives from local raw-mode TUIs like vim or less, and structural anchoring keeps shell-typed lines such as $ echo Password: from triggering. See ghostel-debug-start / ghostel-debug-password-events-show for diagnostics.

The mode line shows = 🔒Password= while a prompt is open. Wrong-password retries are detected automatically (the cursor moves to the new prompt row). The wire copy of the password is clear-string'd immediately after sending, so it does not linger in the heap.

Detection is extensible via ghostel-password-prompt-functions - a chain of (ROW) -> string-or-nil sources tried in order. The default reads with read-passwd; users prepend their own (auth-source / KeePass / pass / etc.) and the default acts as the fallback. The defcustom docstring includes a TRAMP-aware auth-source-pick-first-password example.

• Automatic injection for bash, zsh, and fish - no shell RC edits needed.
• OSC 7 - directory tracking (default-directory follows the shell's cwd, TRAMP-aware for remote hosts).
• OSC 133 - semantic prompt markers, enabling prompt-to-prompt navigation with C-c M-n / C-c M-p.
• OSC 2 - title tracking (the buffer is renamed from the terminal title; see ghostel-buffer-name-function).
• OSC 52;e - call whitelisted Emacs functions from shell scripts (see Calling Elisp from the Shell).
• OSC 52 - clipboard support (opt-in, for remote sessions).
• INSIDE_EMACS and EMACS_GHOSTEL_PATH environment variables.

• Incremental redraw - only dirty rows are re-rendered.
• Timer-based batched updates with adaptive frame rate.
• Immediate redraw for interactive typing echo - PTY output arriving shortly after a keystroke bypasses the timer, eliminating 16-33ms of latency per keypress.
• Asynchronous local PTY output - local PTY output is parsed by the native reader and Emacs is notified only when callbacks or redraws are needed.
• Cursor position updates even without cell changes.
• Theme-aware color palette (syncs with the Emacs theme via ghostel-sync-theme).

Ghostel renders inline images using the Kitty graphics protocol via libghostty. It supports both placement modes used by real-world tools:

• Traditional placements - timg, kitty +kitten icat, and any tool that emits direct kitty graphics commands.
• Unicode-placeholder placements (U+10EEEE) - used by yazi and other modern image previewers to anchor images to the buffer's text grid.

Pixel data is rendered through Emacs's built-in image support: PNG payloads are decoded by a vendored stb_image, and raw RGB/RGBA/Gray/GrayAlpha transmissions are converted to PPM in the native module - no external ImageMagick dependency.

XTWINOPS size queries (CSI 14 / 16 / 18 t) are answered so apps can detect graphics support and pick image dimensions; without that, timg falls back to half-block rendering even when TERM_PROGRAM=ghostty.

Cell pixel sizes are reported as physical pixels via ghostel-cell-pixel-scale (default auto, derived from display DPI). On most displays this approximates standalone Ghostty's output; for pixel-perfect parity (especially on Linux Wayland with fractional scaling or non-standard DPI), set an explicit number.

Shell scripts running inside ghostel can call whitelisted Elisp functions via the ghostel_cmd helper (provided by the shell integration scripts):

ghostel_cmd find-file "/path/to/file"
ghostel_cmd message "Hello from the shell"

This uses an OSC 52 escape sequence with a reserved kind byte (\e]52;e;<payload>\e\\) - a ghostel-private extension. Only functions listed in ghostel-eval-cmds are allowed.

Default whitelisted commands: find-file, find-file-other-window, dired, dired-other-window, message.

Add your own with:

(add-to-list 'ghostel-eval-cmds '("magit-status-setup-buffer" magit-status-setup-buffer))

Example shell aliases (add to your .bashrc / .zshrc):

if [[ "${INSIDE_EMACS%%,*}" = 'ghostel' ]]; then
    # Open a file in Emacs from the terminal
    e()   { ghostel_cmd find-file-other-window "$@"; }

    # Open dired in another window, defaulting to the current directory
    dow() { ghostel_cmd dired-other-window "${1:-$PWD}"; }

    # Open magit for the current directory
    gst() { ghostel_cmd magit-status-setup-buffer "$(pwd)"; }
fi

Ghostel recognises two notification protocols used by terminal programs:

• OSC 9 (iTerm2 form): ESC ] 9 ; BODY ST - body only.
• OSC 777 (rxvt notify): ESC ] 777 ; notify ; TITLE ; BODY ST - title + body.

Both route to ghostel-notification-function with (TITLE BODY). The default handler, ghostel-default-notify, uses the alert package when installed - it picks a sensible backend per platform (osascript on macOS, libnotify on Linux, Growl, terminal-notifier, etc.) and is configurable via alert-default-style. Install it from MELPA with M-x package-install RET alert RET.

When alert is not available, ghostel falls back to message, which only appears in the echo area. Set ghostel-notification-function to nil to silence notifications entirely, or to your own function to route them elsewhere.

A custom handler receives the title and body and can route them anywhere:

(setq ghostel-notification-function
      (lambda (title body)
        (alert body :title (or title "ghostel") :category 'ghostel)))

ConEmu's OSC 9;4 progress protocol is also recognised: build tools, AI agents like Claude Code, and other long-running commands emit it to report completion percentage. Ghostel dispatches these to ghostel-progress-function with (STATE PROGRESS) where STATE is one of remove, set, error, indeterminate, pause and PROGRESS is an integer 0-100 or nil.

Two built-in handlers are available:

• ghostel-default-progress - plain text in mode-line-process: [42%], [...], [err 73%], [paused 25%], or cleared on remove. Zero dependencies.
• ghostel-spinner-progress - animates mode-line-process via spinner.el during indeterminate (e.g. while Claude Code is working) and falls back to the same text indicator for the other states.

ghostel-progress-function defaults to ghostel-spinner-progress when spinner.el is on the load-path at ghostel load time, otherwise to ghostel-default-progress. Pin a specific handler explicitly:

;; Pin to spinner (errors with a hint if spinner.el isn't installed):
(setq ghostel-progress-function #'ghostel-spinner-progress)
;; Or stay on the plain text indicator:
(setq ghostel-progress-function #'ghostel-default-progress)
;; Pick a different spinner style - see `spinner-types' in spinner.el:
(setq ghostel-spinner-type 'horizontal-moving)

The 16 ANSI colors are defined as Emacs faces inheriting from term-color-*:

ghostel-color-black         ghostel-color-bright-black
ghostel-color-red           ghostel-color-bright-red
ghostel-color-green         ghostel-color-bright-green
ghostel-color-yellow        ghostel-color-bright-yellow
ghostel-color-blue          ghostel-color-bright-blue
ghostel-color-magenta       ghostel-color-bright-magenta
ghostel-color-cyan          ghostel-color-bright-cyan
ghostel-color-white         ghostel-color-bright-white

Themes that customize term-color-* faces automatically apply. Customize individual faces with M-x customize-face.

Default foreground/background are read from the ghostel-default face, which inherits from default. Customize it to give ghostel terminals different default colors than the rest of Emacs (e.g. a dark terminal inside a light Emacs):

(set-face-attribute 'ghostel-default nil
                    :foreground "#cdd6f4"
                    :background "#1e1e2e")

Bold text coloring follows ghostel-bold-color (nil = same color as normal text, bright = use the bright ANSI variant, or a fixed #RRGGBB string), matching Ghostty 1.2.0's bold-color configuration.

By default, shell integration scripts are not injected for remote sessions. There are two ways to enable it.

Ghostel sets TERM=xterm-ghostty so apps inside the buffer get the full capability set (synchronized output, Kitty keyboard, etc.). That same TERM value gets inherited by anything spawned inside the buffer - including ssh REMOTE and M-x ghostel from a TRAMP default-directory. Remote hosts without the xterm-ghostty entry will then print Error opening terminal: xterm-ghostty.

ghostel-ssh-install-terminfo (default auto) handles both cases. auto is enabled when ghostel-tramp-shell-integration is on, so turning on remote integration also turns on terminfo install - one switch.

Ghostel includes optional evil-mode support via evil-ghostel.el. It synchronizes the terminal cursor with Emacs point during evil state transitions so that normal-mode navigation (hjkl etc.) works correctly.

evil-ghostel is distributed as an independent MELPA package that depends on ghostel. Install it alongside ghostel:

(use-package evil-ghostel
  :ensure t
  :after (ghostel evil)
  :hook (ghostel-mode . evil-ghostel-mode))

Or from source (Emacs 30+); :lisp-dir points package-vc at this extension's subdirectory inside the ghostel monorepo:

(use-package evil-ghostel
  :vc (:url "https://github.com/dakra/ghostel"
       :lisp-dir "extensions/evil-ghostel"
       :rev :newest)
  :after (ghostel evil)
  :hook (ghostel-mode . evil-ghostel-mode))

When evil-ghostel-mode is active:

• Ghostel starts in insert state (terminal input works normally).
• Pressing ESC enters normal state and snaps point to the terminal cursor.
• Normal-mode navigation (h, j, k, l, w, b, e, 0, $, …) works as expected.
• Insert/append (i, a, I, A) sync the terminal cursor to point before entering insert state.
• Delete (d, dw, dd, D, x, X) yanks text to the kill ring and deletes via the shell.
• Change (c, cw, cc, C, s, S) deletes then enters insert state.
• Replace (r) replaces the character under the cursor.
• Paste (p, P) pastes from the kill ring via bracketed paste.
• Undo (u) sends readline undo (Ctrl+_).
• Cursor shape follows evil state (block for normal, bar for insert).
• Alt-screen programs (vim, less, htop) are unaffected.

The initial state and the ESC behavior are configurable via evil-ghostel-initial-state (default insert) and evil-ghostel-escape (default auto).

ghostel-compile runs a shell command in a ghostel buffer and presents the result like M-x compile - a compilation-mode-style header, footer, error highlighting, and next-error navigation - but backed by a real TTY so programs that probe isatty(3) (coloured output, progress bars, curses tools) behave as they do in a normal shell.

Each invocation spawns a fresh process via shell-file-name -c COMMAND through a PTY rendered by ghostel - no interactive shell sits between the command and the user, so multi-line shell scripts are passed through verbatim and no shell-integration setup is required. The process sentinel delivers the real exit status.

ghostel-compile inherits the same TERM=xterm-ghostty and TERMINFO…= env as M-x ghostel, so build output gets synchronized output, true color, etc. If a test runner or build tool gets confused by the unfamiliar TERM, set (setq ghostel-term "xterm-256color").

(require 'ghostel-compile)

(global-set-key (kbd "C-c c") #'ghostel-compile)

Commands:

A run looks like a M-x compile buffer:

-*- mode: ghostel-compile -*-
Compilation started at Wed Apr 15 08:30:11

make -j4 test

...command output (live, with full TTY)...

Compilation finished at Wed Apr 15 08:30:19, duration 8.20 s

By default the buffer is read-only and navigable from the start - just like a M-x compile buffer. g reruns, n / p walk errors (parsed once the run finishes), RET jumps to the source. Keystrokes do not reach the running process, so the "compile-mode" UX (read coloured output, kill with C-c C-c) is available even mid-run.

Pass a prefix arg (C-u M-x ghostel-compile, mirroring C-u M-x compile) to launch in interactive mode instead - the buffer stays writable for the duration of the run, so programs like htop and less, test runners that prompt for input, or anything that wants live keystrokes work. ghostel-recompile (g) preserves whichever mode the buffer was launched in.

When the command finishes, the live process and ghostel renderer are torn down and the buffer's major mode is switched to ghostel-compile-view-mode (derived from compilation-mode). mode-line-process shows :run while the command runs and :exit [N] afterwards; an interactive run reads :run/i instead of :run.

ghostel-eshell-visual-command-mode makes eshell run "visual" commands - programs in eshell-visual-commands, eshell-visual-subcommands, and eshell-visual-options (vim, htop, less, top, git log's pager, …) - inside a dedicated ghostel buffer instead of the default term-mode fallback, so they get a real terminal emulator.

(require 'ghostel-eshell)
(add-hook 'eshell-load-hook #'ghostel-eshell-visual-command-mode)

When the program exits, the buffer stays on [Process exited] so you can read any remaining output (window point snaps to the end so it is visible without scrolling). Press q to dismiss the dead buffer. Set eshell-destroy-buffer-when-process-dies to t to kill the buffer automatically on exit instead.

To run an ad-hoc command in a ghostel buffer without editing eshell-visual-commands, use the ghostel eshell built-in:

~ $ ghostel nethack

Add a shorter alias if you like:

(defalias 'eshell/v 'eshell/ghostel)    ;; then:  ~ $ v nethack

The public primitive behind the mode is ghostel-exec BUFFER PROGRAM &optional ARGS, which launches an arbitrary program in a ghostel buffer with no shell integration applied. Useful for building your own integrations.

ghostel-comint-mode replaces comint's built-in ansi-color-process-output with a stream filter that runs every chunk of process output through libghostty-vt's VT parser. In M-x shell (and any other comint-derived buffer - REPLs, etc.) output renders with the same SGR fidelity a real ghostel terminal would give it, plus OSC 8 hyperlinks and OSC 7 directory tracking.

(require 'ghostel-comint)
(add-hook 'shell-mode-hook #'ghostel-comint-mode)

Or, to enable it for every comint-derived buffer at once:

(ghostel-comint-global-mode 1)

What you get over the stock filter (and xterm-color):

It is still a stream filter - not a full terminal. Cursor-positioning escapes, alt-screen entry (\e[?1049h), and full-screen redraws are silently dropped: programs like htop or less will not render correctly under it. Use M-x ghostel (a real terminal) for those.

CR / BS / TAB pass through unchanged so comint's own comint-carriage-motion filter continues to handle progress bars, read -s prompts, etc.

For best performance, xterm-color's advice to disable font-locking in shell buffers applies here too - see the docstring of ghostel-comint-mode.

Some Emacs Lisp input methods (hangul-input-method is the common example) commit text by inserting it into the current buffer instead of returning key events. Inside a ghostel buffer that insert lands in the buffer but is never sent to the PTY, so the next redraw erases it.

ghostel-ime-mode is an optional minor mode that wraps the buffer-local input-method-function. When the input method commits by buffer insertion, the wrapper deletes the transient insert and forwards the committed text to the PTY as UTF-8, letting the shell echo it back through the normal redraw path. While a Quail-style composition is in flight it also asks ghostel to defer redraws (via ghostel-inhibit-redraw-functions) so the renderer does not rewrite the buffer mid-composition. GUI native preedit handling is unaffected.

(use-package ghostel-ime
  :hook (ghostel-mode . ghostel-ime-mode))

This generalizes to any Lisp input method that uses quail-overlay (Korean Hangul, Japanese, Chinese, …).

For packages that need to inject input into a running ghostel buffer (agent integrations, custom keymaps, …), two public functions are provided:

(ghostel-send-string "ls -la\n")      ; send raw bytes, newline included
(ghostel-send-key "return")           ; send a named key through the encoder
(ghostel-send-key "a" "ctrl")         ; C-a - respects the current terminal mode
(ghostel-send-key "up" "shift,ctrl")  ; modifiers are comma-separated

Both operate on the current buffer; wrap in with-current-buffer when driving another ghostel buffer. Calling either outside a ghostel buffer signals a user-error.

ghostel-project opens a terminal in the current project's root directory with a project-prefixed buffer name. To make it available from project-switch-project (C-x p p):

(add-to-list 'project-switch-commands '(ghostel-project "Ghostel") t)

The table above drives ghostel on the Emacs-process path so it can be compared apples-to-apples against vterm/eat/term. For local shells ghostel defaults to its own native PTY (ghostel-use-native-pty), where a Zig background thread reads the PTY and feeds libghostty-vt directly, waking Emacs only when the read would block. This avoids running the per-chunk filter on the main thread, so bulk output is faster and the UI stays responsive during floods.

bench/run-bench.sh --backends runs the same cat workload through both backends and reports the ratio. On a sustained multi-MB dump the native path runs roughly 2x the Emacs path, and the gap widens with size - the remaining distance to a standalone GPU terminal is Emacs's own buffer-materialization and redisplay cost, which both backends share.

Interactive keystrokes are optimized separately from bulk throughput. When you type a character, the PTY echo is detected and rendered immediately (bypassing the 33ms redraw timer), so the character appears on screen with minimal delay. Use M-x ghostel-debug-typing-latency to measure the end-to-end latency on your system - it reports per-keystroke PTY, render, and total latency with min/median/p99/max statistics.

Run the benchmarks yourself:

bench/run-bench.sh              # full suite (throughput)
bench/run-bench.sh --quick      # quick sanity check
bench/run-bench.sh --backends   # native vs Emacs PTY (ghostel only)

Terminal engine. libghostty-vt comes from Ghostty, a modern GPU-accelerated terminal, and supports the Kitty keyboard/mouse protocols, rich underline styles, and OSC 8 hyperlinks. libvterm targets VT220/xterm emulation and is more conservative in protocol support.

Mouse handling. Ghostel encodes mouse events (press, release, drag) and passes them through to the terminal via the SGR mouse protocol. TUI apps like htop or lazygit receive full mouse input. vterm intercepts mouse clicks for Emacs point movement and does not forward them to the terminal.

Input modes. Ghostel offers five eat.el-style input modes (semi-char, char, Emacs, copy, line) selected from a single base keymap; see Input modes. vterm's default mode is roughly equivalent to ghostel's semi-char, and vterm-copy-mode lines up with ghostel's copy mode - both freeze incoming output. Three of ghostel's modes have no vterm equivalent: line mode buffers input locally so full Emacs editing works on the in-progress line and RET sends it atomically; Emacs mode keeps the terminal streaming live but locks the buffer read-only; char mode is a runtime toggle that forwards every key (including C-c, C-x, M-x) to the terminal - vterm requires editing vterm-keymap-exceptions and reloading the buffer to get the same effect.

Rendering. Both use text properties (not overlays) and batch consecutive cells with identical styles. Ghostel's engine provides three-level dirty tracking (none / partial / full) with per-row granularity. vterm uses damage-rectangle callbacks and redraws entire invalidated rows. Ghostel defaults to ~30 fps redraw; vterm defaults to ~10 fps.

Shell integration. Ghostel auto-injects shell integration scripts for bash, zsh, and fish - no shell RC changes needed. vterm requires manually sourcing scripts in your shell configuration. Both support Elisp eval from the shell and TRAMP-aware remote directory tracking.

Password prompts. Ghostel detects when the foreground program is reading a password (sudo, ssh, gpg, …) and prompts via read-passwd, sending the answer down the PTY without routing keystrokes through Emacs's normal key pipeline. vterm has no such interception: each character of your password is a regular keypress, so it ends up in view-lossage, the recent-keys ring, and anything else that observes the key pipeline. Ghostel's hook also lets you plug in auth-source to satisfy known prompts without typing - see Password prompt detection.

Performance. In PTY throughput benchmarks (1 MB streamed, both backends with ~1,000 lines of scrollback), ghostel is roughly 2.4x faster than vterm on plain ASCII data (81 vs 34 MB/s). On URL-heavy output ghostel pulls further ahead (77 vs 28 MB/s). See Performance for full numbers.

Installation. Ghostel can automatically download a pre-built native module or compile from source with Zig. vterm uses CMake with a single C dependency (libvterm) and can auto-compile on first load from Elisp.

For a detailed architectural comparison, see ARCHITECTURE.md.