Ghostty Terminal Emulator

This example demonstrates the core capabilities of the Ghostty VT library when compiled to WebAssembly. It shows how to:

1. Initialize a terminal instance.
2. Write VT-encoded (Virtual Terminal) data to the terminal.
3. Format and extract the terminal contents as plain text.

Ghostty provides libghostty, a cross-platform, zero-dependency C and Zig library designed for building terminal emulators or embedding terminal functionality (like style parsing) into existing applications.

Key components:

• libghostty-vt: A library focused on parsing terminal sequences and maintaining terminal state. It is compatible with macOS, Linux, Windows, and WebAssembly.
• libghostty: The broader library for embedding a full terminal experience.

For implementation guidance, refer to:

• The examples directory for small C and Zig snippets.
• The Ghostling project for a minimal, complete project example.
• The Doxygen website for the C API documentation.

The ghostty-vt C library allows developers to register and handle specific terminal effect callbacks. This enables programmatic responses to terminal events. Supported callbacks include:

• write_pty: Intercepts data written to the PTY.
• bell: Triggered when a terminal bell is requested.
• title_changed: Triggered when the terminal title changes.
• clipboard_write: Triggered when a clipboard write is requested. Unlike standard OSC 52 sequences, this callback receives a single atomic write containing decoded, binary-safe MIME representations.

The special.zig file is used for drawing logic that is not tied to specific Unicode codepoints. Instead, function names in this file must match the enum tag names defined in the Sprite enum located in src/font/sprite.zig.

These functions receive the exact same arguments as standard draw* functions:

• cp: u32
• canvas: *font.sprite.Canvas
• width: u32
• height: u32
• metrics: font.Metrics

They must return DrawFnError!void.

The compiled WASM module cannot be loaded via file:// URLs due to browser security restrictions. You must serve the files using an HTTP server.

From the root of the ghostty repository, use one of the following commands to serve the example:

Using Python (Recommended)

python3 -m http.server 8000

Using Node.js

npx serve .

Using PHP

php -S localhost:8000

Once the server is running, navigate to http://localhost:8000/example/wasm-key-encode/ in your browser. Focus the text input field to see key events encoded into terminal escape sequences.

# Example using Python
python3 -m http.server 8000

Shell integration for Nushell is automatic when running Nushell in Ghostty via the vendor autoload mechanism. If integration is disabled or you need to load it manually, use the following commands:

source $GHOSTTY_RESOURCES_DIR/shell-integration/nushell/vendor/autoload/ghostty.nu
use ghostty *

Ghostty provides shell integration for Bash. While automatic integration works by starting Bash in POSIX mode, the version of Bash distributed with macOS (/bin/bash) does not support automatic integration.

To ensure integration works on macOS or to manually source it, add the following snippet to the top of your .bashrc file. This uses the GHOSTTY_RESOURCES_DIR environment variable to locate the integration script.

# Ghostty shell integration for Bash. This must be at the top of your bashrc!
if [ -n "${GHOSTTY_RESOURCES_DIR}" ]; then
    builtin source "${GHOSTTY_RESOURCES_DIR}/shell-integration/bash/ghostty.bash"
fi

This example demonstrates how to use the pre-built libghostty-vt XCFramework within a Swift Package. The workflow involves creating a terminal instance, writing VT (Virtual Terminal) sequences into it, and extracting the screen contents as plain text.

Prerequisites

You must build the XCFramework from the Ghostty repository root before attempting to build the Swift example.

# 1. Build the XCFramework from the repository root
zig build -Demit-lib-vt

# 2. Build and run the Swift package
cd example/swift-vt-xcframework
swift build
swift run

The example/ directory contains standalone projects demonstrating the Ghostty library APIs. Examples are categorized by the API they use:

• Directories starting with c- demonstrate the C API.
• Directories starting with zig- demonstrate the Zig API.

To build and run an example, navigate to the specific example directory and use the Zig build system.

cd example/<dir>
zig build run

If you want to build the example against a local version of the Ghostty repository instead of downloading it from GitHub via FetchContent, use the FETCHCONTENT_SOURCE_DIR_GHOSTTY CMake variable to point to your local checkout path.

cmake -B build -DFETCHCONTENT_SOURCE_DIR_GHOSTTY=../..
cmake --build build