ghostty-rs

A Rust rewrite of the Ghostty 1.3.1 terminal emulator for Linux (GTK4 + libadwaita, OpenGL).

It aims for behavioural parity with Ghostty: the same configuration file format, options, defaults and documentation; the same keybindings and actions; the same ghostty +action CLI; the same terminal emulation (including kitty keyboard/graphics protocols, OSC 8 hyperlinks, semantic prompts, synchronized output, tmux control mode); the same shell integration, themes and terminfo.

All of Ghostty's Zig code is ported: the Linux GTK app (verified at runtime and pixel-identical to Ghostty 1.3.1), the libghostty and libghostty-vt C APIs (same headers/ABI), WASM, crash reporting, and the macOS (Metal/CoreText) and Windows (ConPTY) code paths. macOS and Windows are compile-checked on Linux (just check-macos, just check-windows); the Windows test suites also run under Wine (just test-windows-wine), macOS has not been run natively. The Swift macOS app is not part of the port; it is a client of the libghostty C API.

The macOS app (original Swift app on the Rust core)

Ghostty's macOS app stays the original Swift app, unchanged. It is wired to the Rust core instead of the Zig core: the Rust libghostty exports the identical include/ghostty.h ABI. On a Mac with Xcode:

just macos-swift-app ../ghostty          # Release; or: just macos-swift-app ../ghostty Debug

This builds the Rust core as GhosttyKit.xcframework into <ghostty>/macos/, installs the resources into <ghostty>/zig-out/share (what the Xcode project bundles) and runs xcodebuild, mirroring zig build -Demit-macos-app. Not runnable on this Linux machine (DRY_RUN=1 previews the steps).

Building and running

Requirements: Rust (edition 2024), GTK ≥ 4.14, libadwaita ≥ 1.5, fontconfig, freetype, harfbuzz, Oniguruma, libepoxy, blueprint-compiler and glib-compile-resources at build time.

cargo run                      # open a terminal window running your shell
cargo run -- -e htop           # run a command
cargo run -- +list-themes      # CLI actions work like Ghostty's
cargo run --profile production # optimized build (LTO, no debug assertions)

Binaries run from this checkout's target/ (any profile) find resources/ (shell integration, themes, terminfo) automatically; installed binaries use the installed resources or GHOSTTY_RESOURCES_DIR. Your existing Ghostty config (~/.config/ghostty/config[.ghostty]) is used as-is.

Installing

just install /usr/local          # binary, share/ghostty, terminfo, desktop files,
                                 # completions, man pages, translations, icons
just install /usr false true     # system-package layout (lib/systemd/user)

Build-time resource directory

Set GHOSTTY_BUILD_RESOURCES_DIR while building or installing to embed an explicit resource directory:

GHOSTTY_BUILD_RESOURCES_DIR=/usr/share/ghostty cargo build --profile production
GHOSTTY_BUILD_RESOURCES_DIR=/usr/share/ghostty cargo install --path . --profile production
GHOSTTY_BUILD_RESOURCES_DIR=../share/ghostty cargo build --profile production

Absolute paths are used directly. Relative paths resolve from the running executable's directory, not the current working directory; ../share/ghostty allows moving an installed bin/ and share/ tree together. The directory contains themes/ and shell-integration/; these files still need to be installed separately (cargo install only installs the executable).

A nonempty runtime GHOSTTY_RESOURCES_DIR overrides the embedded path in every profile. The embedded path takes precedence over automatic resource discovery and does not require a terminfo sentinel. An unset or empty build option keeps the existing discovery rules, including the debug profile's preference for installed resources over the runtime override. Changing or unsetting the build option causes Cargo to rebuild resource lookup. Paths are literal: ~ and shell variables are not expanded by Ghostty. Flatpak's sandbox resource layout remains managed by its runtime integration.

Testing

just test      # cargo test --workspace (~3000 tests)
just clippy    # clippy with -D warnings

Every Zig test block of the ported files was ported to a Rust test. crates/ghostty-core/tests holds end-to-end tests that drive the real core, terminal and a real pty through a fake app runtime. ghostty-bench mirrors Ghostty's benchmark tool; terminal stream throughput is on par with the Zig build (see docs/rewrite/notes/perf-P1.md).

Verification

• just difftest — differential fuzzing of the terminal core against Ghostty's own Zig code (sets up Zig 0.15.2 under target/).
• just visual-parity — pixel comparison against the installed Ghostty in a headless nested weston.
• just test-windows-wine — runs the Windows test suites (incl. ConPTY / cmd.exe end-to-end tests) under Wine with mingw-w64.
• just check-all — native gate plus macOS/Windows/WASM checks.

Documentation

• docs/rewrite/ARCHITECTURE.md – top-down decomposition, crate map, key design decisions, intentional omissions
• docs/rewrite/STATUS.md – work package history
• docs/rewrite/DEVIANT_FIXES.md – every intentional deviation from Ghostty (upstream bugs fixed instead of replicated; commits titled fix-deviant(...))
• docs/rewrite/KNOWN_DIFFERENCES.md – remaining minor differences
• docs/rewrite/notes/ – per-crate porting notes, deviations from Zig, audits and verification reports

License

MIT, like Ghostty. Bundled fonts and themes carry their own licenses (see crates/ghostty-font/res/ and resources/LICENSE-iTerm2-Color-Schemes).