### Install Ghostel with use-package and load-path

Source: https://github.com/dakra/ghostel/blob/main/README.md

Install Ghostel by specifying its load path using use-package.

```elisp
(use-package ghostel
  :load-path "/path/to/ghostel")
```

--------------------------------

### Manual Terminfo Installation via SCP (Linux/macOS)

Source: https://github.com/dakra/ghostel/blob/main/README.md

Manually install the compiled xterm-ghostty terminfo binary on a remote host using scp. This example includes steps for both Linux and macOS terminfo directory layouts.

```bash
ssh REMOTE 'mkdir -p ~/.terminfo/x'
scp <package-dir>/etc/terminfo/x/xterm-ghostty REMOTE:~/.terminfo/x/
# Ghostty also looks in 78/ on macOS:
ssh REMOTE 'uname' | grep -q Darwin && {
    ssh REMOTE 'mkdir -p ~/.terminfo/78'
    scp <package-dir>/etc/terminfo/78/xterm-ghostty REMOTE:~/.terminfo/78/
}
```

--------------------------------

### Complete Ghostel Setup with Keybindings

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Configures the core Ghostel package, enables comint, compile, and eshell modules, and sets up a keybinding for recompilation. Requires the 'ghostel' package to be installed.

```emacs-lisp
;; Core ghostel
(use-package ghostel
  :ensure t
  :config
  (add-hook 'shell-mode-hook #'ghostel-comint-enable)
  (ghostel-compile-global-mode 1)
  (add-hook 'eshell-mode-hook #'ghostel-eshell-setup))

;; Keybindings
(bind-keys
  :map ghostel-mode-map
  ("C-c C-r" . ghostel-recompile))
```

--------------------------------

### Manual Terminfo Installation via SSH

Source: https://github.com/dakra/ghostel/blob/main/README.md

Manually install the xterm-ghostty terminfo entry on a remote host by piping infocmp output.

```bash
infocmp -x xterm-ghostty | ssh REMOTE 'mkdir -p ~/.terminfo && tic -x -'
```

--------------------------------

### Install Ghostel with use-package and vc

Source: https://github.com/dakra/ghostel/blob/main/README.md

Install Ghostel using use-package and version control, suitable for Emacs 30+.

```elisp
(use-package ghostel
  :vc (:url "https://github.com/dakra/ghostel"
       :lisp-dir "lisp"
       :rev :newest))
```

--------------------------------

### Install Ghostel with MELPA

Source: https://github.com/dakra/ghostel/blob/main/README.md

Use this snippet to install Ghostel using the MELPA package manager.

```elisp
(use-package ghostel
  :ensure t)
```

--------------------------------

### Manual Installation of Ghostel

Source: https://github.com/dakra/ghostel/blob/main/README.md

Manually add Ghostel to your load path and require it.

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

--------------------------------

### Shell Specification Example

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/types.md

Illustrates specifying a shell executable, either as a string for a simple path or a list for a path with arguments.

```elisp
"/bin/bash" or '("/bin/zsh" "--login")
```

--------------------------------

### Install evil-ghostel from source

Source: https://github.com/dakra/ghostel/blob/main/README.md

Install evil-ghostel from source for Emacs 30+ by specifying the Git repository URL and the lisp directory within the monorepo. This method also hooks evil-ghostel-mode into ghostel-mode.

```elisp
(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))
```

--------------------------------

### Manual Remote Shell Integration Setup

Source: https://github.com/dakra/ghostel/blob/main/README.md

Copy integration scripts and terminfo to the remote host and source them from your shell configuration. This is recommended for permanent remote hosts.

```bash
ssh REMOTE 'mkdir -p ~/.local/share/ghostel/terminfo'
scp "$EMACS_GHOSTEL_PATH"/etc/shell/ghostel.{bash,zsh,fish} REMOTE:.local/share/ghostel/
scp -r "$EMACS_GHOSTEL_PATH"/etc/terminfo/{x,78} REMOTE:.local/share/ghostel/terminfo/
```

--------------------------------

### Setup Imenu for Ghostel Buffer

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Configures Imenu integration for Ghostel buffers to enable navigation by prompts (OSC 133).

```emacs-lisp
(ghostel-imenu-setup)
```

--------------------------------

### ghostel-beginning-of-input-or-line

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Moves the cursor to the beginning of the input line in line mode. Repeating the command moves to the absolute start of the visual line.

```APIDOC
## `ghostel-beginning-of-input-or-line` — Jump to Input Start

### Description
In line mode, move to the start of the input line. Repeat to move to the absolute start of the visual line.

### Function Signature
```elisp
(ghostel-beginning-of-input-or-line)
```

### Return Value
nil
```

--------------------------------

### Create Terminal Handle

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/types.md

Example of creating a terminal handle using ghostel--new with specified rows and columns.

```elisp
(ghostel--new 24 80)
```

--------------------------------

### Setup Eshell Integration

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Enables Ghostel integration for Eshell, adding support for interactive TUI commands and Ghostel-aware visual command handlers. This should be added to the `eshell-mode-hook`.

```elisp
(add-hook 'eshell-mode-hook #'ghostel-eshell-setup)
```

--------------------------------

### Get Ghostel Input Start Point

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Returns the buffer position where the input line begins in line mode, after the prompt. Returns nil if the terminal is not in line mode.

```elisp
(ghostel-input-start-point)
```

--------------------------------

### Kitty Image Mediums Bitfield Examples

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/types.md

Illustrates different bitfield combinations for Kitty image mediums. Only enable file-based mediums for trusted commands due to security implications.

```elisp
#b000  ; Only direct (base64 inline) — safe, default
```

```elisp
#b001  ; Enable file reading — requires trust
```

```elisp
#b011  ; Enable file + temp-file
```

```elisp
#b111  ; Enable all mediums — maximum functionality, lowest security
```

--------------------------------

### Jump to Start of Input or Line

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

In line mode, moves the cursor to the start of the input line. Repeating the command moves to the absolute start of the visual line.

```emacs-lisp
(ghostel-beginning-of-input-or-line)
```

--------------------------------

### Install evil-ghostel with MELPA

Source: https://github.com/dakra/ghostel/blob/main/README.md

Install the evil-ghostel package alongside ghostel using use-package for MELPA distribution. This hook ensures evil-ghostel-mode is activated when ghostel-mode is enabled.

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

--------------------------------

### Interactive Terminal Usage

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/README.md

Integrates the ghostel package for interactive terminal use. Ensure the package is installed and bind a key for activation.

```elisp
(use-package ghostel
  :ensure t
  :bind (("C-=" . ghostel)))
```

--------------------------------

### Mode-Specific Keybindings

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/README.md

Defines custom keybindings for ghostel-char-mode. This example binds 'C-c C-b' to send a 'cd ~/projects\n' command to the shell.

```elisp
(define-key ghostel-char-mode-map (kbd "C-c C-b")
  (lambda () (interactive)
    (ghostel-send-string "cd ~/projects\n")))
```

--------------------------------

### Build Ghostel from Source

Source: https://github.com/dakra/ghostel/blob/main/README.md

Clone the repository and build the project using Zig.

```sh
git clone https://github.com/dakra/ghostel.git
cd ghostel

# Build everything (fetches ghostty automatically via Zig package manager)
zig build -Doptimize=ReleaseFast
```

--------------------------------

### ghostel-imenu-setup

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Configures Imenu integration for Ghostel buffers, enabling navigation by prompts (OSC 133). This command is essential for structured navigation within Ghostel sessions.

```APIDOC
## `ghostel-imenu-setup` — Imenu Setup

### Description
Set up Imenu for the Ghostel buffer to navigate by prompts (OSC 133).

### Function Signature
```elisp
(ghostel-imenu-setup)
```

### Return Value
nil
```

--------------------------------

### ghostel-eshell-setup

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Enables Ghostel integration for Eshell, allowing visual commands to be run through Ghostel terminals. This provides a TTY experience for interactive commands within Eshell, preserving colors and interactivity.

```APIDOC
## `ghostel-eshell-setup`

### Description
Enable Ghostel integration for Eshell. This function enhances Eshell by allowing visual commands to be executed in a proper TTY environment provided by Ghostel, improving the experience for interactive terminal applications.

### Usage
```elisp
(add-hook 'eshell-mode-hook #'ghostel-eshell-setup)
```

### Effect
- Adds Ghostel-aware visual command handlers
- Enables support for interactive TUI commands in Eshell
```

--------------------------------

### ghostel-download-module

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Downloads a pre-built native module binary for the current platform. With `prompt-for-version`, prompts for a specific release tag.

```APIDOC
## `ghostel-download-module` — Download Native Module

### Description
Download a pre-built native module binary for the current platform. With `prompt-for-version`, prompts for a specific release tag.

### Function Signature
```elisp
(ghostel-download-module &optional prompt-for-version)
```

### Parameters
#### Optional Parameters
- **prompt-for-version** (boolean) - Default: nil - Prompt for release version if non-nil

### Return Value
nil

### Example
```elisp
(ghostel-download-module)
(ghostel-download-module t)  ; Prompt for version
```
```

--------------------------------

### Get Module Version

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/native-module.md

Retrieves the version string of the Ghostel native module. Useful for checking compatibility.

```elisp
(ghostel--module-version)
```

```elisp
(message "Ghostel module: %s" (ghostel--module-version))
```

--------------------------------

### ghostel-exec

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Execute a program in the given Ghostel buffer's terminal. Useful for starting subprocesses within the terminal.

```APIDOC
## `ghostel-exec` — Execute Command in Terminal

### Description
Execute a program in the given Ghostel buffer's terminal. Useful for starting subprocesses within the terminal.

### Parameters
#### Path Parameters
- **buffer** (buffer) - Required - Target Ghostel buffer
- **program** (string) - Required - Program name or path
- **args** (list) - Optional - List of string arguments

### Return Value
nil

### Example

```elisp
(ghostel-exec (current-buffer) "vim" '("file.txt"))
```
```

--------------------------------

### Load and Enable Eshell Module

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Loads the eshell module and sets it up for eshell mode. Ensure 'ghostel-eshell' is available.

```emacs-lisp
;; Load eshell module
(require 'ghostel-eshell)
(add-hook 'eshell-mode-hook #'ghostel-eshell-setup)
```

--------------------------------

### Download Native Module

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Downloads a pre-built native module binary for the current platform. Optionally prompts for a specific release version if `prompt-for-version` is non-nil.

```elisp
(ghostel-download-module)
```

```elisp
(ghostel-download-module t)  ; Prompt for version
```

--------------------------------

### ghostel--new

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/native-module.md

Creates a new terminal instance with specified dimensions and configuration.

```APIDOC
## ghostel--new — Create Terminal Instance

### Description
Create a new terminal instance with the specified dimensions and configuration.

### Parameters
#### Path Parameters
- **rows** (integer) - Required - Number of rows (1–65535)
- **cols** (integer) - Required - Number of columns (1–65535)
- **max-scrollback** (integer) - Optional - Maximum scrollback buffer size in bytes (default: 5242880)
- **kitty-storage-limit** (integer) - Optional - Kitty graphics storage limit in bytes (0 disables) (default: 335544320)
- **kitty-mediums** (integer) - Optional - Bitfield enabling image load mediums: bit 0 = file, bit 1 = temp-file, bit 2 = shared-mem (default: 0)

### Return Value
Terminal handle (opaque user pointer).

### Throws
`error.OutOfRange` if dimensions or limits exceed valid ranges.

### Example
```elisp
(let ((term (ghostel--new 24 80)))
  ;; Use term...
  )
```
```

--------------------------------

### Pin Ghostel Progress Handler

Source: https://github.com/dakra/ghostel/blob/main/README.md

Explicitly set the ghostel-progress-function to either ghostel-spinner-progress or ghostel-default-progress. Errors if spinner.el is not installed when attempting to use ghostel-spinner-progress.

```emacs-lisp
(setq ghostel-progress-function #'ghostel-spinner-progress)
```

```emacs-lisp
(setq ghostel-progress-function #'ghostel-default-progress)
```

--------------------------------

### Get Ghostel Cursor Position

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Returns the current buffer position of the terminal's cursor. This is a direct integer representation of the cursor's location.

```elisp
(ghostel-cursor-point)
```

--------------------------------

### Configure Ghostel Shell Program

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/configuration.md

Set the shell program and arguments for Ghostel. Use a string for just the executable or a list for executable and arguments.

```elisp
;; Use zsh with login shell
(setq ghostel-shell '("/bin/zsh" "--login"))
```

```elisp
;; Use bash
(setq ghostel-shell "/bin/bash")
```

--------------------------------

### Get Terminal Title

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/native-module.md

Retrieves the current title of the terminal, typically set by an OSC 2 escape sequence. Returns nil if the title is not set.

```elisp
(ghostel--get-title term)
```

```elisp
(message "Terminal: %s" (ghostel--get-title term))
```

--------------------------------

### Build Ghostel with Local Ghostty Checkout

Source: https://github.com/dakra/ghostel/blob/main/README.md

Build Ghostel while pointing the ghostty dependency to a local path.

```sh
zig fetch --save=ghostty /path/to/ghostty
zig build -Doptimize=ReleaseFast
```

--------------------------------

### Select Ghostel Buffer Interactively

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Displays a completion menu for selecting a Ghostel buffer. `ghostel-list-buffers` shows all buffers, while `ghostel-project-list-buffers` filters by the current project.

```elisp
(call-interactively #'ghostel-list-buffers)
```

--------------------------------

### Run Quick Throughput Sanity Check

Source: https://github.com/dakra/ghostel/blob/main/README.md

Perform a quick sanity check of the throughput benchmarks. This is a faster, less comprehensive test than the full suite.

```sh
bench/run-bench.sh --quick
```

--------------------------------

### Get Terminal Working Directory

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/native-module.md

Retrieves the current working directory of the terminal, typically set by shell integration via an OSC 7 escape sequence. Returns nil if not set.

```elisp
(ghostel--get-pwd term)
```

```elisp
(let ((dir (ghostel--get-pwd term)))
  (when dir (cd dir)))
```

--------------------------------

### Manual Shell Integration for Fish

Source: https://github.com/dakra/ghostel/blob/main/README.md

Add this script to your ~/.config/fish/config.fish for manual shell integration with Ghostel.

```fish
string match -qr '^ghostel(,|$)' -- "$INSIDE_EMACS"; and source "$EMACS_GHOSTEL_PATH/etc/shell/ghostel.fish"
```

--------------------------------

### Execute Command in Ghostel Terminal

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Executes a program within a specified Ghostel buffer's terminal. This is useful for starting subprocesses directly from the terminal interface. Arguments can be provided as a list of strings.

```elisp
(ghostel-exec (current-buffer) "vim" '("file.txt"))
```

--------------------------------

### Compile Module from Source

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/README.md

Compiles the ghostel module from source. This is an alternative to downloading pre-compiled binaries and can be useful for development or when binary downloads fail.

```elisp
;; Or compile from source
(ghostel-module-compile)
```

--------------------------------

### Extend Whitelisted Eval Commands

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/configuration.md

Customize `ghostel-eval-cmds` to include additional Emacs functions that can be called from the terminal via OSC 52;e. This example adds 'magit-status' and a custom command handler.

```elisp
(setq ghostel-eval-cmds
      '(("find-file" find-file)
        ("magit-status" magit-status)
        ("custom-command" my-custom-handler)))
```

--------------------------------

### ghostel--enable-vt-log

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/native-module.md

Enables debug logging for libghostty, routing output to the `*ghostel-debug*` buffer.

```APIDOC
## ghostel--enable-vt-log — Enable Debug Logging

### Description
Enable libghostty internal log routing to the `*ghostel-debug*` buffer. Used for debugging VT parsing issues.

### Return Value
t

### Example
```elisp
(ghostel--enable-vt-log)
```
```

--------------------------------

### Manual Shell Integration for Zsh

Source: https://github.com/dakra/ghostel/blob/main/README.md

Add this script to your ~/.zshrc for manual shell integration with Ghostel.

```zsh
[[ "${${INSIDE_EMACS-}%%,*}" = 'ghostel' ]] && source "$EMACS_GHOSTEL_PATH/etc/shell/ghostel.zsh"
```

--------------------------------

### Create New Terminal Instance

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/native-module.md

Creates a new terminal instance with specified dimensions and optional scrollback and Kitty graphics limits. The returned handle is automatically managed by garbage collection.

```elisp
(ghostel--new rows cols &optional max-scrollback kitty-storage-limit kitty-mediums)
```

```elisp
(let ((term (ghostel--new 24 80)))
  ;; Use term...
  )
```

--------------------------------

### Directory-Local Configuration for Ghostel

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/configuration.md

Use this snippet in a `.dir-locals.el` file to configure Ghostel settings on a per-directory or per-project basis. Only 'safe' variables like `ghostel-environment` can be set without prompting.

```emacs-lisp
((nil . ((ghostel-shell . ("/bin/zsh" "--login"))
         (ghostel-environment . ("PROJ_ROOT=/path/to/proj"))
         (ghostel-tramp-shell-integration . t))))
```

--------------------------------

### ghostel-input-start-point

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Return the buffer position where the input line (after the prompt) begins in line mode.

```APIDOC
## `ghostel-input-start-point` — Get Input Start

### Description
Return the buffer position where the input line (after the prompt) begins in line mode.

### Return Value
Integer position or nil if not in line mode.

### Source
`lisp/ghostel.el:3190`
```

--------------------------------

### Open Ghostel Terminal at Project Root

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Opens a Ghostel terminal at the current project root. If the current directory is not in a project, it prompts for project selection. A prefix argument allows overriding the directory.

```elisp
;; Open terminal at project root
(ghostel-project)

;; With prefix: override directory
(ghostel-project '(4))
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/native-module.md

Enables internal logging for libghostty to the `*ghostel-debug*` buffer. Use this for debugging VT parsing issues.

```elisp
(ghostel--enable-vt-log)
```

--------------------------------

### Run Full Test Suite

Source: https://github.com/dakra/ghostel/blob/main/README.md

Execute the full test suite, including tests that require the built native module. This provides comprehensive testing of Ghostel functionality.

```sh
emacs --batch -Q -L . -l ert -l test/ghostel-test.el -f ghostel-test-run
```

--------------------------------

### ghostel-module-compile

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Compile the native module from source. This function requires Zig 0.15.2+ and spawns a compilation buffer.

```APIDOC
## `ghostel-module-compile` — Compile from Source

### Description
Compile the native module from source (requires Zig 0.15.2+). Spawns a compilation buffer.

### Return Value
The compilation buffer.

### Example

```elisp
(ghostel-module-compile)
```
```

--------------------------------

### Configure Ghostel Compilation Mode

Source: https://github.com/dakra/ghostel/blob/main/README.md

Sets up `ghostel-compile` for running shell commands with compilation-mode features. It also binds the `C-c c` key to invoke `ghostel-compile` globally.

```elisp
(require 'ghostel-compile)

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

--------------------------------

### Load and Enable Compile Module

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Loads the compile module and enables it globally. Ensure 'ghostel-compile' is available.

```emacs-lisp
;; Load compile module
(require 'ghostel-compile)
(ghostel-compile-global-mode 1)
```

--------------------------------

### `ghostel-project` — Open Terminal at Project Root

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Opens a Ghostel terminal at the current project root. It prompts for project selection if the current directory is not within a recognized project. A prefix argument allows overriding the directory.

```APIDOC
## `ghostel-project` — Open Terminal at Project Root

### Description
Opens a Ghostel terminal at the current project root (determined by `project-root`). Prompts for project selection if the current directory is not in a project. With prefix `arg`, prompts for directory override.

### Method
`ghostel-project`

### Parameters
#### Path Parameters
- **arg** (integer or nil) - Optional - Prefix argument for directory selection

### Return Value
The terminal buffer.

### Throws
Error if no project is found.

### Example
```elisp
;; Open terminal at project root
(ghostel-project)

;; With prefix: override directory
(ghostel-project '(4))
```
```

--------------------------------

### Compile Ghostel Module from Source

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Compiles the native module from source. Requires Zig 0.15.2 or later. This function spawns a compilation buffer and returns it.

```elisp
(ghostel-module-compile)
```

--------------------------------

### ghostel-line-mode-send-or-open-link

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

In line mode, this command first checks for a link at the cursor position and opens it if found. Otherwise, it sends the current input line.

```APIDOC
## `ghostel-line-mode-send-or-open-link` — Send or Open Link

### Description
In line mode, open a link at point if one exists, otherwise send the input line.

### Function Signature
```elisp
(ghostel-line-mode-send-or-open-link)
```

### Return Value
nil
```

--------------------------------

### Check Module Version Compatibility

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/README.md

Logs the current module version and the minimum required version to help diagnose compatibility issues. This is useful for troubleshooting module loading problems.

```elisp
;; Check version compatibility
(message "Module version: %s" (ghostel--module-version))
(message "Minimum required: 0.33.0")
```

--------------------------------

### Manual Shell Integration for Bash

Source: https://github.com/dakra/ghostel/blob/main/README.md

Add this script to your ~/.bashrc for manual shell integration with Ghostel.

```bash
[[ "${INSIDE_EMACS%%,*}" = 'ghostel' ]] && source "$EMACS_GHOSTEL_PATH/etc/shell/ghostel.bash"
```

--------------------------------

### Fish Shell Integration Configuration

Source: https://github.com/dakra/ghostel/blob/main/README.md

Add this snippet to `~/.config/fish/config.fish` on the remote host to source the Ghostel fish integration script conditionally.

```fish
if string match -qr '^ghostel(,|$)' -- "$INSIDE_EMACS"; or test "$TERM" = 'xterm-ghostty'
    source ~/.local/share/ghostel/ghostel.fish
end
```

--------------------------------

### Project-Specific Configuration

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/README.md

Configures ghostel settings on a per-project basis using a .dir-locals.el file. This allows customization of the shell, environment variables, and compile commands for specific projects.

```elisp
((nil . ((ghostel-shell . ("/bin/zsh" "--login"))
         (ghostel-environment . ("PROJ_ROOT=/home/user/proj"))
         (ghostel-compile-command . "cd ~/proj && make"))))
```

--------------------------------

### `ghostel-list-buffers` / `ghostel-project-list-buffers` — Interactive Buffer Selection

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Displays a completion menu for selecting a Ghostel buffer. `ghostel-list-buffers` shows all buffers, while `ghostel-project-list-buffers` filters to the current project's buffers.

```APIDOC
## `ghostel-list-buffers` / `ghostel-project-list-buffers` — Interactive Buffer Selection

### Description
Display a completion menu to select a Ghostel buffer. `ghostel-list-buffers` shows all Ghostel buffers; `ghostel-project-list-buffers` shows only those in the current project.

### Method
`ghostel-list-buffers` or `ghostel-project-list-buffers`

### Return Value
The selected buffer.

### Example
```elisp
(call-interactively #'ghostel-list-buffers)
```
```

--------------------------------

### ghostel-copy-all

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Copies all visible text from the terminal buffer to the kill ring.

```APIDOC
## `ghostel-copy-all` — Copy All Text

### Description
Copies the entire terminal buffer's visible text to the kill ring.

### Function Signature
```elisp
(ghostel-copy-all)
```

### Example
```elisp
(ghostel-copy-all)
```
```

--------------------------------

### Run Throughput Benchmarks

Source: https://github.com/dakra/ghostel/blob/main/README.md

Execute the full suite of throughput benchmarks for Ghostel. This script compares performance against other Emacs terminal emulators.

```sh
bench/run-bench.sh
```

--------------------------------

### Ghostel Elisp Commands

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/DOCUMENTATION_COVERAGE.md

This section details the Elisp commands available for interacting with Ghostel, including terminal creation, input handling, copy/paste operations, navigation, mode management, and utility functions.

```APIDOC
## Elisp Commands

### Description
Provides a comprehensive list of Elisp commands for controlling and interacting with Ghostel terminals.

### Terminal Creation & Management
- `ghostel` — Open terminal
- `ghostel-project` — Open at project root
- `ghostel-other` — Switch or create
- `ghostel-next` / `ghostel-previous` — Cycle buffers
- `ghostel-project-next` / `ghostel-project-previous` — Cycle in project
- `ghostel-list-buffers` / `ghostel-project-list-buffers` — Select buffer

### Input Commands
- `ghostel-send-string` — Send text
- `ghostel-send-key` — Send key sequence
- `ghostel-send-C-c`, `ghostel-send-C-z`, etc. — Control characters
- `ghostel-send-next-key` — Literal input
- `ghostel-paste-string` — Bracketed paste

### Copy & Paste
- `ghostel-paste` — Paste from kill ring
- `ghostel-yank` / `ghostel-yank-pop` — Yank operations
- `ghostel-copy-all` — Copy entire buffer
- `ghostel-xterm-paste` — X11 paste

### Navigation & Scrollback
- `ghostel-clear-scrollback` — Clear history
- `ghostel-clear` — Clear screen
- `ghostel-next-hyperlink` / `ghostel-previous-hyperlink` — Link navigation
- `ghostel-next-prompt` / `ghostel-previous-prompt` — Prompt navigation
- `ghostel-open-link-at-point` / `ghostel-open-link-at-click` — Open links

### Mode Management
- `ghostel-char-mode` — Character mode
- `ghostel-semi-char-mode` — Semi-char mode (default)
- `ghostel-emacs-mode` — Emacs mode
- `ghostel-copy-mode` — Read-only copy mode
- `ghostel-line-mode` — Line editing mode
- `ghostel-readonly-exit` — Exit readonly
- `ghostel-readonly-exit-and-clear` — Exit and clear
- `ghostel-readonly-exit-and-send` — Exit and send

### Line Mode Editing
- `ghostel-line-mode-send` — Send input
- `ghostel-line-mode-newline` — Insert newline
- `ghostel-line-mode-self-insert` — Insert character
- `ghostel-line-mode-interrupt` — Send Ctrl+C
- `ghostel-line-mode-delete-char-or-eof` — Delete or EOF
- `ghostel-line-mode-history-previous` / `-next` — History navigation
- `ghostel-line-mode-complete-at-point` — Completion
- `ghostel-beginning-of-input-or-line` — Jump to input

### Mouse & Selection
- `ghostel-mouse-press-or-copy-mode` — Left click
- `ghostel-mouse-drag-or-set-region` — Drag selection
- `ghostel-mouse-release-or-set-point` — Left release

### Module Installation
- `ghostel-download-module` — Download native binary
- `ghostel-module-compile` — Compile from source

### Utilities
- `ghostel-sync-theme` — Sync colors with theme
- `ghostel-force-redraw` — Force immediate redraw
- `ghostel-exec` — Execute command
- `ghostel-input-start-point` — Get input position
- `ghostel-cursor-point` — Get cursor position
- `ghostel-readonly-copy` — Copy selection
- `ghostel-default-notify` — Notification handler
- `ghostel-default-progress` — Progress handler
- `ghostel-buffer-name-by-title` — Buffer naming by title
- `ghostel-buffer-name-by-directory` — Buffer naming by directory
- `ghostel-ssh-clear-terminfo-cache` — Clear SSH cache
- `ghostel-imenu-setup` — Imenu integration
- `ghostel-readonly-end-of-line` / `-end-of-buffer` — Readonly navigation
- `ghostel-readonly-copy` — Copy in readonly
- `ghostel-line-mode-send-or-open-link` — Send or open link

### Mode Definition
- `ghostel-mode` — Major mode

**Total: 60+ exported commands**
```

--------------------------------

### Compilation with TTY Support

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/README.md

Activates ghostel-compile for compilation tasks, enabling TTY features. This configuration should be applied globally.

```elisp
(use-package ghostel-compile
  :after ghostel
  :config (ghostel-compile-global-mode 1))
```

--------------------------------

### Open Link at Point or Click

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Open a URL or file link located at the current cursor point. `ghostel-open-link-at-click` is used to handle mouse click events for opening links.

```elisp
(ghostel-open-link-at-point)
```

```elisp
(ghostel-open-link-at-click event)
```

--------------------------------

### Load and Enable Comint Module

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Loads the comint module and enables it for shell mode. Ensure 'ghostel-comint' is available.

```emacs-lisp
;; Load comint module
(require 'ghostel-comint)
(add-hook 'shell-mode-hook #'ghostel-comint-enable)
```

--------------------------------

### Configure Ghostel Keymap Exceptions

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/keybindings.md

Modify `ghostel-keymap-exceptions` to customize which key combinations are treated as exceptions and handled specially. After modification, rebuild the keymap using `ghostel--rebuild-semi-char-keymap`.

```elisp
(setq ghostel-keymap-exceptions
      '("C-x" "C-c" "M-x" "C-u"
        ;; Add custom exceptions
        "C-h" "C-l" "M-:"))
```

--------------------------------

### Create Terminal with Kitty Storage Limit

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/types.md

Use this function to create a new terminal, specifying the kitty graphics storage limit. A value of 0 disables kitty graphics.

```elisp
(ghostel--new rows cols max-scrollback kitty-storage-limit kitty-mediums)
```

--------------------------------

### Write ASCII and UTF-8 Input to Terminal

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/types.md

Demonstrates writing both ASCII and UTF-8 encoded strings to a terminal using ghostel--write-input. Elisp handles multibyte character encoding transparently.

```elisp
(ghostel--write-input term "hello\n")          ; ASCII
```

```elisp
(ghostel--write-input term "日本語\n")         ; UTF-8 multibyte
```

--------------------------------

### Open Ghostel Terminal

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Opens a new Ghostel terminal. If called with a prefix argument, it prompts for the initial working directory.

```elisp
(ghostel)
;; Open a terminal in the current directory

;; Open a terminal and prompt for a directory
(ghostel '(4))
```

--------------------------------

### Enable Kitty Graphics Support

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Enables the Kitty graphics protocol for displaying inline images within Ghostel buffers. This can be automatically enabled for all Ghostel buffers by adding it to `ghostel-mode-hook`.

```elisp
(add-hook 'ghostel-mode-hook #'ghostel-kitty-enable)
```

--------------------------------

### Check Ghostel Input Mode and Keymap Exceptions

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/README.md

Use these Elisp snippets to inspect the current input mode and keymap exceptions in Ghostel. This is useful for debugging why keys might not be reaching the terminal.

```elisp
;; Check current mode
(message "Mode: %s" ghostel--input-mode)

;; Check keymap exceptions
(message "Exceptions: %s" ghostel-keymap-exceptions)

;; Try char mode
(ghostel-char-mode)
```

--------------------------------

### Ghostel Commands

Source: https://github.com/dakra/ghostel/blob/main/README.md

A list of commands available in Ghostel for managing terminals, navigating buffers, and controlling input modes.

```APIDOC
## Commands

| Command                        | Description                                  |
|--------------------------------|----------------------------------------------|
| `M-x ghostel`                  | Open a new terminal (create new buffer with prefix arg) |
| `M-x ghostel-project`          | Open a terminal in the current project root (create new buffer with prefix arg)  |
| `M-x ghostel-other`            | Switch to next terminal or create one        |
| `M-x ghostel-next`             | Cycle to next ghostel buffer (sorted by name, wraps) |
| `M-x ghostel-previous`         | Cycle to previous ghostel buffer             |
| `M-x ghostel-list-buffers`     | Pick a ghostel buffer via `read-buffer`      |
| `M-x ghostel-project-next`     | Cycle to next ghostel buffer in current project |
| `M-x ghostel-project-previous` | Cycle to previous ghostel buffer in current project |
| `M-x ghostel-project-list-buffers` | Pick a project-scoped ghostel buffer     |
| `M-x ghostel-clear`            | Clear screen and scrollback                  |
| `M-x ghostel-clear-scrollback` | Clear scrollback only                        |
| `M-x ghostel-semi-char-mode`   | Switch to semi-char input mode (default)     |
| `M-x ghostel-char-mode`        | Switch to char input mode                    |
| `M-x ghostel-emacs-mode`       | Switch to Emacs input mode (read-only, live) |
| `M-x ghostel-copy-mode`        | Enter copy mode (frozen)                     |
| `M-x ghostel-line-mode`        | Switch to line input mode                    |
| `M-x ghostel-copy-all`         | Copy entire scrollback to kill ring          |
| `M-x ghostel-paste`            | Paste from kill ring                         |
| `M-x ghostel-send-next-key`    | Send next key literally                      |
| `M-x ghostel-next-prompt`      | Jump to next shell prompt                    |
| `M-x ghostel-previous-prompt`  | Jump to previous shell prompt                |
| `M-x ghostel-next-hyperlink`   | Jump to next hyperlink (OSC 8, URL, file ref) |
| `M-x ghostel-previous-hyperlink` | Jump to previous hyperlink                 |
| `M-x ghostel-force-redraw`     | Force a full terminal redraw                 |
| `M-x ghostel-debug-typing-latency` | Measure per-keystroke typing latency     |
| `M-x ghostel-sync-theme`       | Re-sync color palette after theme change     |
| `M-x ghostel-ssh-clear-terminfo-cache` | Clear outbound-ssh terminfo install cache (force re-probe) |
| `M-x ghostel-download-module`  | Download pre-built native module             |
| `M-x ghostel-module-compile`   | Compile native module from source            |
```

--------------------------------

### Configure Ghostel Environment Variables

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/configuration.md

Define extra environment variables for Ghostel shell processes. Use 'KEY=VALUE' strings, or a bare 'KEY' to unset a variable.

```elisp
(setq ghostel-environment
      '("LANG=en_US.UTF-8"
        "CC=clang"
        "LD_LIBRARY_PATH=/usr/local/lib"
        "UNWANTED_VAR"))  ; Unset UNWANTED_VAR
```

--------------------------------

### Bash Shell Integration Configuration

Source: https://github.com/dakra/ghostel/blob/main/README.md

Add this snippet to `~/.bashrc` on the remote host to source the Ghostel bash integration script conditionally.

```bash
if [[ "${INSIDE_EMACS%%,*}" = 'ghostel' || "$TERM" = 'xterm-ghostty' ]]; then
    source ~/.local/share/ghostel/ghostel.bash
fi
```

--------------------------------

### Enter Character-at-a-Time Mode

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Enter character mode, where each keystroke is sent directly to the terminal. This is the default mode, with exceptions defined in `ghostel-keymap-exceptions`.

```elisp
(ghostel-char-mode)
```

--------------------------------

### ghostel-eshell-visual-subcommands

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Defines subcommand prefixes that trigger visual mode in Eshell when used with Ghostel. This allows for finer control over which specific subcommands of a program should be handled by Ghostel.

```APIDOC
## `ghostel-eshell-visual-subcommands`

### Description
Subcommand prefixes that trigger visual mode in Eshell. This variable allows specifying combinations of a command and its subcommand that should be handled by Ghostel.

### Type
`(repeat (cons string string))`

### Default
Entries like `("git" "add")`, `("git" "commit")`, etc.

### Example
```elisp
(add-to-list 'ghostel-eshell-visual-subcommands '("myapp" "interactive"))
```
```

--------------------------------

### ghostel-line-mode-history-previous / ghostel-line-mode-history-next

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

In line mode, navigates the command history (captured from prompts and saved to `ghostel-line-mode-history`).

```APIDOC
## `ghostel-line-mode-history-previous` / `ghostel-line-mode-history-next` — Command History

### Description
In line mode, navigate the command history (captured from prompts and saved to `ghostel-line-mode-history`).

### Function Signature
```elisp
(ghostel-line-mode-history-previous)
(ghostel-line-mode-history-next)
```

### Return Value
nil
```

--------------------------------

### Run Pure Elisp Tests

Source: https://github.com/dakra/ghostel/blob/main/README.md

Execute pure Elisp tests without requiring a native module. This is useful for quick testing and verification of Elisp code.

```sh
emacs --batch -Q -L . -l ert -l test/ghostel-test.el -f ghostel-test-run-elisp
```

--------------------------------

### Enable Ghostel Eshell Visual Command Mode

Source: https://github.com/dakra/ghostel/blob/main/README.md

Add this hook to enable visual command mode for Eshell. This ensures programs like vim, htop, and less run in a dedicated ghostel buffer.

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

--------------------------------

### ghostel-eshell-visual-commands

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

A list of Eshell commands that should be executed through Ghostel terminals. This configuration allows users to specify which interactive commands, such as `less`, `vim`, or `man`, should leverage Ghostel's TTY capabilities.

```APIDOC
## `ghostel-eshell-visual-commands`

### Description
List of Eshell commands to run through Ghostel terminals. Commands in this list will spawn a Ghostel terminal instead of using pipes, preserving terminal features like pagination and colors for interactive tools.

### Type
`(repeat string)`

### Default
Common interactive commands: `less`, `more`, `vim`, `nano`, `man`, `git add -p`, etc.

### Example
```elisp
(setq ghostel-eshell-visual-commands
      '("less" "vim" "nano" "man" "git" "tmux" "my-interactive-script"))
```
```

--------------------------------

### ghostel--comint-set-palette / ghostel--comint-set-default-colors

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/native-module.md

Configures the color palette for the comint filter. `ghostel--comint-set-palette` takes a string of colors, while `ghostel--comint-set-default-colors` sets foreground and background colors using hex values.

```APIDOC
## `ghostel--comint-set-palette` / `ghostel--comint-set-default-colors` — Configure Comint Filter

### Description
Set colors for the comint filter, matching the terminal functions.

### Parameters
- **state** (user-ptr) - Required - Filter state from `ghostel--comint-make-state`
- **colors-string** (string) - Required - Palette string (for `ghostel--comint-set-palette`)
- **fg-hex** (string) - Required - Foreground color hex (for `ghostel--comint-set-default-colors`)
- **bg-hex** (string) - Required - Background color hex (for `ghostel--comint-set-default-colors`)
```

--------------------------------

### Add Ghostel Project Command

Source: https://github.com/dakra/ghostel/blob/main/README.md

Integrates `ghostel-project` into Emacs's project switching commands. This allows you to easily open a terminal in your project's root directory.

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

--------------------------------

### Add Custom Elisp Command

Source: https://github.com/dakra/ghostel/blob/main/README.md

Extend the list of callable Elisp functions by adding a new command and its corresponding function to ghostel-eval-cmds.

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

--------------------------------

### Set Shell Specification

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/types.md

Configures the shell executable to be used by Ghostel. This can be a simple string path or a list containing the executable and its arguments.

```elisp
(setq ghostel-shell "/bin/bash")
```

```elisp
(setq ghostel-shell '("/bin/zsh" "--login"))
```

--------------------------------

### Makefile Test Targets

Source: https://github.com/dakra/ghostel/blob/main/README.md

Convenient Makefile targets for running tests, building, and benchmarking. Use `make test` for pure Elisp tests.

```sh
make test        # pure Elisp tests (no native module required)
make all         # build + test + lint
make bench-quick # quick benchmark sanity check
```

--------------------------------

### ghostel-next-prompt / ghostel-previous-prompt

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Navigates to the next or previous shell prompt using OSC 133 semantic prompt markers, requiring shell integration.

```APIDOC
## `ghostel-next-prompt` / `ghostel-previous-prompt` — Navigate Prompts

### Description
Jumps to the next/previous shell prompt (OSC 133 semantic prompt marker). Requires shell integration.

### Function Signature
```elisp
(ghostel-next-prompt &optional n)
(ghostel-previous-prompt &optional n)
```

### Parameters
#### Path Parameters
- **n** (integer) - Optional - Number of prompts to skip (default: 1)

### Example
```elisp
(ghostel-next-prompt)
(ghostel-previous-prompt 3)  ; Jump back 3 prompts
```
```

--------------------------------

### `ghostel` — Open a Terminal

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/commands.md

Opens a new Ghostel terminal in a buffer. Optionally prompts for a specific directory to use as the initial working directory.

```APIDOC
## `ghostel` — Open a Terminal

### Description
Opens a new Ghostel terminal in a buffer. If `arg` is non-nil (called with prefix), prompts for the directory to use as the terminal's initial working directory.

### Method
`ghostel`

### Parameters
#### Path Parameters
- **arg** (integer or nil) - Optional - Prefix argument; non-nil triggers directory selection

### Return Value
The newly created buffer.

### Throws
Errors if module cannot be loaded or process cannot be spawned.

### Example
```elisp
;; Open a terminal in the current directory
(ghostel)

;; Open a terminal and prompt for a directory
(ghostel '(4))
```
```

--------------------------------

### ghostel-compile

Source: https://github.com/dakra/ghostel/blob/main/_autodocs/api-reference/supplementary-modules.md

Runs a specified shell command in a Ghostel terminal buffer, preserving terminal-aware output such as colors and interactive tools. It can optionally launch in interactive mode, allowing keystroke input.

```APIDOC
## ghostel-compile

### Description
Run a shell command in a Ghostel terminal buffer.

### Signature
```elisp
(ghostel-compile command &optional comint)
```

### Parameters
#### Path Parameters
- **command** (string) - Required - Shell command to run
- **comint** (boolean) - Optional - If non-nil, launch in interactive mode (allow keystroke input)

### Usage
```elisp
(ghostel-compile "cargo build --release")
(ghostel-compile "npm test" '(4)) ; Interactive mode with prefix
```

### Return Value
The compilation buffer.
```