# Ghostty Admin & Architecture Guide

This guide is for administrators, packagers, distributors, and developers who
need to **build, deploy, integrate, secure, or understand the internals** of
Ghostty. It assumes familiarity with the end-user features documented in the
companion **User Guide**.

Ghostty is a cross-platform terminal emulator written in [Zig](https://ziglang.org)
with native platform frontends (AppKit/SwiftUI on macOS, GTK4 + libadwaita on
Linux), GPU-accelerated rendering (Metal/OpenGL), and a reusable terminal-engine
library (`libghostty-vt`) exposed to C, C++, Swift, Zig, and WebAssembly.

---

## 1. Executive Summary

| Aspect | Detail |
|--------|--------|
| **Language** | Zig (core), Swift (macOS app), with vendored C dependencies |
| **Platforms** | macOS (AppKit/SwiftUI), Linux (GTK4 + libadwaita), WASM (terminal engine) |
| **Rendering** | Metal (macOS), OpenGL (Linux), WebGL (browser) — comptime-selected |
| **Concurrency** | Multi-threaded: GUI thread + per-surface IO thread + per-surface render thread |
| **Async IO** | `libxev` event loop; `io_uring`/`epoll` on Linux, `kqueue` on macOS |
| **Config** | Single plain-text file; ~200 options; one giant `Config.zig` struct |
| **App ID** | `com.mitchellh.ghostty` |
| **`TERM`** | `xterm-ghostty` |
| **Build system** | Zig build (`build.zig`) + Xcode project for the macOS app bundle |
| **Distribution** | macOS app (Sparkle auto-update), Linux package managers, Flatpak, Snap |
| **Reusable lib** | `libghostty-vt` — standalone VT engine with C/C++/Swift/Zig/WASM bindings |

The codebase at the documented commit is large (~5,400 files, ~8.5 MB of source
across `src/`, `macos/`, `pkg/`, `example/`, and build tooling). The terminal
emulation core (`src/terminal/`) alone is the single largest subsystem.

> [!NOTE]
> Ghostty draws a clean compile-time boundary between **core logic** (Zig,
> platform-agnostic) and **platform runtimes** (`apprt`). Each build selects
> exactly one application runtime, one renderer, and one font backend at compile
> time, so there is no runtime plugin system to manage.

---

## 2. Architecture Overview

### 2.1 High-level component map

```text
                         ┌─────────────────────────────────────────┐
                         │            Application Runtime            │
                         │   (apprt: GTK4/libadwaita | AppKit/Swift) │
                         │   windows, tabs, splits, input, clipboard │
                         └───────────────┬───────────────────────────┘
                                         │ owns
                                ┌────────▼─────────┐
                                │   Core Surface    │  src/Surface.zig
                                │  (one terminal)   │  src/App.zig
                                └───┬──────────┬────┘
                  drives           │          │           drives
            ┌────────────────────▼──┐    ┌───▼─────────────────────┐
            │     Render Thread       │    │       IO Thread         │
            │  src/renderer/*         │    │     src/termio/*        │
            │  Metal | OpenGL | WebGL │    │  PTY + subprocess +     │
            │  GPU draw of the grid   │    │  VT stream handler      │
            └───────────┬─────────────┘    └───────────┬─────────────┘
                        │ reads                          │ writes
                        │                  ┌─────────────▼──────────────┐
                        └─────────────────►│   Terminal Engine (VT)     │
                                           │   src/terminal/*           │
                                           │   parser, screen/page,     │
                                           │   modes, OSC/CSI/DCS,      │
                                           │   Kitty graphics/keyboard  │
                                           └────────────┬───────────────┘
                                                        │ uses
                  ┌─────────────────────────────────────┼───────────────────────┐
            ┌─────▼──────┐  ┌──────────────┐  ┌─────────▼────────┐  ┌────────────▼──┐
            │   Fonts     │  │   Config     │  │     Input        │  │   OS / utils  │
            │ src/font/*  │  │ src/config/* │  │  src/input/*     │  │ src/os/*      │
            │ discovery,  │  │ ~200 opts,   │  │ keybinds, kitty  │  │ unicode, simd │
            │ shaping,    │  │ themes, CLI  │  │ keyboard, mouse  │  │ crash, pty    │
            │ sprites     │  │ flags        │  │ encoding         │  │               │
            └─────────────┘  └──────────────┘  └──────────────────┘  └───────────────┘
```

### 2.2 The compile-time runtime selection

Three major subsystems are chosen at compile time via `src/build_config.zig`,
which reads build options into comptime constants:

```zig
// src/apprt.zig
pub const runtime = switch (build_config.artifact) {
    .exe => switch (build_config.app_runtime) {
        .none => none,   // embedded library (used by the macOS Swift app)
        .gtk  => gtk,    // GTK4 + libadwaita (Linux)
    },
    .lib => embedded,
    .wasm_module => browser,
};

// src/renderer.zig
pub const Renderer = switch (build_config.renderer) {
    .metal  => GenericRenderer(Metal),
    .opengl => GenericRenderer(OpenGL),
    .webgl  => WebGL,
};
```

| Build artifact | Runtime | Used by |
|----------------|---------|---------|
| `exe` + `gtk` | GTK4/libadwaita | The Linux executable |
| `exe` + `none` / `lib` | `embedded` | The macOS Swift app links Ghostty core as a library |
| `wasm_module` | `browser` | The WebAssembly demos |

> [!IMPORTANT]
> On macOS, the user-facing `Ghostty.app` is a **Swift/AppKit application** that
> embeds the Ghostty Zig core as a library (the `embedded` apprt). On Linux, the
> `ghostty` binary is a single Zig executable using the GTK apprt. This is why
> macOS and Linux have different feature sets and platform-specific options.

### 2.3 Threading model

Ghostty is heavily multi-threaded for low latency and high throughput:

- **GUI / main thread** — owned by the app runtime (GTK main loop or AppKit run
  loop). Handles window management, input events, and dispatches to surfaces.
- **IO thread** (`src/termio/Thread.zig`) — one per surface. Reads/writes the
  PTY, runs the VT stream handler, and updates the terminal screen state.
- **Render thread** (`src/renderer/Thread.zig`) — one per surface. Reads the
  terminal screen state and issues GPU draw calls.

Cross-thread communication uses **mailboxes** (message queues) rather than shared
mutable state where possible. The async event loop is provided by `libxev`,
configurable via `async-backend` (`io_uring`/`epoll` on Linux, `kqueue` on
macOS).

### 2.4 Source tree map

| Path | Responsibility |
|------|----------------|
| `src/main.zig`, `src/main_ghostty.zig` | Executable entry points |
| `src/App.zig` | Top-level application state (across surfaces) |
| `src/Surface.zig` | Core terminal "surface" logic (one terminal) |
| `src/apprt/` | Application runtime abstraction (`gtk/`, `embedded`, `none`, `browser`) |
| `src/apprt/gtk/` | GTK4 + libadwaita frontend (windows, tabs, splits, IPC, portals) |
| `src/terminal/` | **Terminal engine**: VT parser, screen/page model, modes, OSC/CSI/DCS, Kitty graphics, search, tmux control mode |
| `src/terminal/c/` + `include/ghostty/` | C API surface for `libghostty-vt` |
| `src/termio/` | PTY I/O, subprocess exec, stream handler, shell integration |
| `src/renderer/` | GPU renderers (`Metal.zig`, `OpenGL.zig`, `WebGL.zig`), shaders, shadertoy |
| `src/font/` | Font discovery, shaping (HarfBuzz/CoreText), sprite/box-drawing, Nerd Font |
| `src/input/` | Keyboard model, keybindings (`Binding.zig`), Kitty keyboard protocol, mouse encoding |
| `src/config/` | Configuration (`Config.zig`), themes, formatter, CLI parsing glue |
| `src/cli/` | `+action` implementations (`list-*`, `show-config`, `ssh`, etc.) |
| `src/lib/`, `src/lib_vt.zig` | libghostty / libghostty-vt library entry points |
| `src/os/` | OS abstractions (PTY, processes, paths, cgroups, hostname) |
| `src/unicode/`, `src/simd/` | Unicode tables and SIMD helpers |
| `src/crash/` | Crash handling and reporting (Sentry/Breakpad) |
| `src/inspector/` | Built-in terminal inspector (Dear ImGui) |
| `src/synthetic/`, `src/benchmark/` | Synthetic data generation and benchmarks |
| `macos/` | The native macOS Swift/AppKit/SwiftUI application |
| `pkg/` | Zig build wrappers for vendored C dependencies |
| `example/` | Sample programs using `libghostty-vt` (C, C++, Swift, Zig, WASM) |
| `nix/`, `flatpak/`, `snap/` | Packaging support |
| `po/` | Translations (i18n) |
| `test/` | Fuzzing corpora and test utilities |

---

## 3. The Configuration System

### 3.1 Design

The entire configuration surface is a single Zig struct: `src/config/Config.zig`.
Each field maps **directly** to both a config-file key and a CLI flag (hence the
heavy use of `@"hyphenated-name"` field syntax). Field doc comments are written in
Pandoc Markdown and are the source of truth for generated documentation and the
`+show-config --docs` output.

```zig
/// Font size in points...
@"font-size": f32 = switch (builtin.os.tag) {
    .macos => 13,
    else => 12,
},
```

Supporting modules in `src/config/`:

| Module | Role |
|--------|------|
| `Config.zig` | The option struct + parsing/validation hooks |
| `file_load.zig` | Locating and loading config files (XDG, `config-file` includes) |
| `theme.zig` | Theme resolution (built-in dir, user dir, light/dark) |
| `formatter.zig`, `formatter_file.zig` | Serializing config back to text |
| `conditional.zig` | Conditional configuration (e.g. light/dark state) |
| `command.zig` | Parsing the `command`/`initial-command` value (`direct:`/`shell:`) |
| `CApi.zig`, `Wasm.zig` | C and WASM access to config |

### 3.2 Load order and precedence

1. Default values (struct field defaults).
2. The default config file (`$XDG_CONFIG_HOME/ghostty/config`) unless
   `config-default-files = false` is passed on the CLI.
3. `config-file` includes, applied **after** the file that references them.
4. CLI arguments (highest precedence; also auto-clear repeatable lists).

### 3.3 Backwards compatibility

`Config.zig` declares a `compatibility` table that renames or remaps deprecated
options so old configs keep working, e.g.:

- `background-blur-radius` → `background-blur` (1.1)
- `adw-toolbar-style` → `gtk-toolbar-style` (1.2)
- `bold-is-bright` → `bold-color = bright` (1.2)
- `cursor-invert-fg-bg` → `cell-foreground`/`cell-background` color values (1.2)

> [!TIP]
> When packaging or writing migration tooling, the `compatibility` map in
> `Config.zig` is the authoritative list of renamed/removed options per version.

### 3.4 Operational validation

```bash
ghostty +validate-config --config-file=/etc/ghostty/config
ghostty +show-config --default --docs        # full effective config + docs
ghostty +explain-config <key>
```

These are the tools to use in CI or post-deploy smoke tests to confirm a managed
configuration is valid.

---

## 4. Building from Source

### 4.1 Toolchain

Ghostty builds with the Zig build system. The required Zig version is pinned in
`build.zig.zon` as `minimum_zig_version`, and `build.zig` enforces it at comptime:

```zig
comptime { buildpkg.requireZig(minimum_zig_version); }
```

> [!WARNING]
> You must use the exact pinned Zig version (or newer where the build allows).
> Mismatched Zig versions are the most common build failure for packagers.

### 4.2 Common build commands

```bash
# Standard optimized build
zig build -Doptimize=ReleaseFast

# Run directly
zig build run

# Run the test suite
zig build test

# Build the dist tarball and validate it
zig build dist
zig build distcheck
```

```text
Build output lands in zig-out/, including:
  zig-out/bin/ghostty        the executable (GTK/Linux)
  zig-out/share/             terminfo, themes, shell integration, man pages
```

### 4.3 Key build options and artifacts

`build.zig` (via `src/build/Config.zig`) exposes many `-D` options. Notable
artifacts it can produce:

| Step / artifact | Description |
|-----------------|-------------|
| `ghostty` exe | The terminal application |
| `GhosttyResources` | terminfo, shell integration scripts, themes |
| `GhosttyDocs` | Man pages / docs (Pandoc) |
| `GhosttyI18n` | Translation catalogs |
| `libghostty-vt` (shared/static) | The standalone VT engine library |
| `libghostty-vt` xcframework | Apple universal binary (macOS host only) |
| `GhosttyBench` | Benchmark tools |
| `GhosttyDist` | Source dist tarball |

Build-time configuration (`src/build_config.zig`) determines `app_runtime`,
`renderer`, `font_backend`, `i18n`, release channel, and the version string
(from a `VERSION` file if present in a tarball, else `build.zig.zon`).

### 4.4 The macOS app

The macOS application is built from the Xcode project in `macos/`
(`Ghostty.xcodeproj`). It links the Ghostty core compiled as a library
(`GhosttyKit`/`ghostty-internal`) and provides the AppKit/SwiftUI UI, App Intents,
AppleScript dictionary, Services, Quick Terminal, and custom icon system.

> [!NOTE]
> Building the macOS app requires macOS with Xcode (for `xcodebuild` and the
> xcframework step). The Linux GTK build does not require any of the `macos/`
> tree.

---

## 5. Dependencies

Ghostty vendors its native dependencies and pins them by hash in
`build.zig.zon` (mirrored as `build.zig.zon.json`). Most are fetched from
`deps.files.ghostty.org` for reproducibility. The `pkg/` directory contains the
Zig build wrappers for the C libraries.

### 5.1 Core libraries

| Dependency | Purpose |
|------------|---------|
| `libxev` | Async event loop (io_uring/epoll/kqueue) |
| `harfbuzz` | Text shaping (Linux; macOS can use CoreText) |
| `freetype` | Font rasterization (Linux) |
| `fontconfig` | Font discovery (Linux) |
| `oniguruma` | Regex engine (link/URL matching) |
| `uucode` | Unicode property tables |
| `z2d` | 2D vector drawing (sprite/box glyphs) |
| `zf` | Fuzzy matching (command palette / theme search) |
| `vaxis` | TUI rendering (for CLI `+list-themes` previews etc.) |

### 5.2 Graphics / rendering

| Dependency | Purpose |
|------------|---------|
| `glslang`, `spirv_cross` | Shader compilation/translation (custom shaders, Metal) |
| `wuffs` | Safe image decoding |
| `zigimg`, `libpng`, `zlib` | Image decoding (background images, Kitty graphics) |
| `highway` | SIMD primitives |
| Dear ImGui (`imgui` + `DearBindings`) | Terminal inspector UI |

### 5.3 Platform integration

| Dependency | Purpose |
|------------|---------|
| `gobject`, `gtk4_layer_shell` | GTK4/libadwaita bindings; Wayland layer-shell (quick terminal) |
| `wayland`, `wayland_protocols`, `plasma_wayland_protocols`, `zig_wayland` | Wayland protocols |
| `zig_objc` | Objective-C interop (macOS) |
| `zig_js` | JS interop (WASM) |
| `libxml2`, `gettext`/libintl | XML (fontconfig), i18n |

### 5.4 Crash reporting & fonts

| Dependency | Purpose |
|------------|---------|
| `sentry`, `breakpad` | Crash capture and minidump generation |
| `jetbrains_mono`, `nerd_fonts_symbols_only`, `iterm2_themes` | Bundled fonts and themes |

> [!IMPORTANT]
> Because dependencies are content-addressed (sha256) in `build.zig.zon`,
> downstream packagers can vendor or mirror them deterministically. Air-gapped
> builds need a local mirror of `deps.files.ghostty.org` artifacts.

---

## 6. Deployment and Packaging

### 6.1 What gets installed

A complete install consists of the executable plus a `share/` resources tree:

```text
bin/ghostty
share/ghostty/themes/          built-in color themes
share/ghostty/shell-integration/   bash, zsh, fish, elvish, nushell scripts
share/terminfo/                xterm-ghostty terminfo
share/man/                     man pages (if docs emitted)
share/locale/                  translations (if i18n enabled)
share/applications/            .desktop file (Linux)
```

Resources are produced by the `GhosttyResources` build step. The terminfo
(`xterm-ghostty`) is important — without it, remote/legacy programs may misbehave.

### 6.2 Linux packaging

| Format | Location |
|--------|----------|
| Flatpak | `flatpak/` (app ID `com.mitchellh.ghostty`) |
| Snap | `snap/` (classic confinement) |
| Nix | `nix/` (build support, packages, VM tests) |
| Distro packages | maintained per-distro |

> [!NOTE]
> The GTK `class`/app-ID is `com.mitchellh.ghostty`. Changing it breaks `.desktop`
> launching, DBus activation, and systemd user services that expect the default
> name. Keep it consistent across the desktop file, DBus, and the binary.

### 6.3 macOS distribution and auto-update

The macOS app is signed and distributed as `Ghostty.app` with **Sparkle**-based
auto-update. Update behavior is governed by the `auto-update` and
`auto-update-channel` options:

- `auto-update`: `off` / `check` / `download` (unset defers to Sparkle defaults).
- `auto-update-channel`: `stable` or `tip` (pre-release). Requires a full restart.

Linux has no built-in updater; updates flow through package managers.

### 6.4 Single-instance and process isolation (Linux)

```ini
gtk-single-instance = detect    # detect | true | false
linux-cgroup = single-instance  # never | always | single-instance
linux-cgroup-memory-limit = 2147483648
linux-cgroup-processes-limit = 512
linux-cgroup-hard-fail = false
```

When `linux-cgroup` is active, each surface (tab/split/window) is placed in a
transient **systemd scope** so per-surface resource limits and OOM isolation
apply. This requires systemd; by default a failure to create the scope is
non-fatal unless `linux-cgroup-hard-fail = true`.

> [!TIP]
> For fleet/managed deployments where one runaway shell shouldn't take down the
> whole terminal, enable cgroup isolation and pair it with `systemd-oom`.

---

## 7. Security

Ghostty implements several defenses against classic terminal-emulator attack
classes. Administrators deploying managed configs should understand each.

### 7.1 Clipboard access (OSC 52)

```ini
clipboard-read = ask      # ask | allow | deny
clipboard-write = allow   # ask | allow | deny
```

Programs can read/write the system clipboard via OSC 52. Reads prompt by default;
writes are allowed by default. In hostile environments, set `clipboard-read =
deny`.

### 7.2 Paste protection

```ini
clipboard-paste-protection = true
clipboard-paste-bracketed-safe = true
```

Pastes containing newlines or control characters are flagged to prevent
"paste-injection" attacks where pasted text auto-executes commands. Keep this on.

### 7.3 Title reporting

```ini
title-report = false   # default
```

The CSI 21 t sequence lets programs query the terminal title. This is **disabled
by default** because a malicious title plus minor user interaction can lead to
information disclosure or, in the worst case, command execution. Leave it off
unless required.

### 7.4 Secure Input (macOS)

```ini
macos-auto-secure-input = true
macos-secure-input-indication = true
```

Ghostty can auto-enable macOS "Secure Input" at detected password prompts,
preventing other applications from reading keystrokes. Note detection is
heuristic and does not work over SSH.

### 7.5 Automation surfaces (macOS)

```ini
macos-applescript = true
macos-shortcuts = ask    # ask | allow | deny
```

Ghostty exposes an AppleScript dictionary and macOS Shortcuts actions that can
create terminals, send text, and invoke any keybind action. These are powerful
and can be abused by a malicious script — `macos-shortcuts` gates Shortcuts
access (prompting by default), and `macos-applescript = false` disables
AppleScript entirely.

### 7.6 Theme and shader trust

- **Theme files can set any option**, not just colors (but not `theme`/
  `config-file`). Only ship/allow themes from trusted sources; the bundled themes
  are audited.
- **Custom shaders** run on the GPU and can be passed arbitrary GLSL. A bad
  shader can blank the window. Validate shaders before deploying.

### 7.7 Resource limits

`scrollback-limit` (per-surface, in memory) and `image-storage-limit` (Kitty
images per screen, default 320 MB; `0` disables image protocols) bound memory.
Background images live in VRAM per terminal. On Linux, cgroup limits (§6.4) cap
per-surface memory/process counts.

### 7.8 Crash reporting

Crash handling uses Sentry/Breakpad to capture minidumps. Reports are managed
locally via `ghostty +crash-report`. Administrators concerned about telemetry
should review the crash subsystem (`src/crash/`) and Sentry configuration before
deployment.

> [!CAUTION]
> The `crash` keybind action (and command-palette entry) deliberately crashes
> Ghostty to test crash handling. Do not expose it in managed configs for general
> users — it causes data loss in the affected surface.

---

## 8. Operations

### 8.1 Inspecting a running install

```bash
ghostty +version            # version, build config, library versions
ghostty +show-config        # effective non-default config
ghostty +list-keybinds      # active keybindings
ghostty +crash-report       # list captured crash reports
```

### 8.2 Logs and debugging

| Mechanism | How |
|-----------|-----|
| Application logs | Ghostty logs to stderr / the platform log (run from a terminal to see them). Shader and theme errors appear here, not as config errors. |
| GTK inspector | `show_gtk_inspector` action, or launch with `GTK_DEBUG=interactive ghostty` |
| OpenGL debug (GTK) | `gtk-opengl-debug = true` |
| Terminal inspector | `inspector:toggle` action — keyboard events, modes, screen state |
| Custom CSS live-edit (GTK) | `GTK_DEBUG=interactive` + `gtk-custom-css` |

### 8.3 IPC control

A running Ghostty can be controlled out-of-band:

```bash
ghostty +new-window
ghostty +toggle-quick-terminal
```

These use IPC (DBus on GTK) to message the running instance — useful for global
shortcuts and scripting. On macOS, App Intents / Shortcuts / AppleScript provide
equivalent automation.

### 8.4 Managed configuration

For fleet deployments:

- Ship a base config and use `config-file` includes for layering.
- Validate with `ghostty +validate-config` in CI/post-deploy.
- Remember CLI args override file config and auto-clear repeatable lists, which is
  handy for one-off overrides (`ghostty --theme=...`).

---

## 9. The Terminal Engine and `libghostty-vt`

### 9.1 The engine

`src/terminal/` is the heart of Ghostty: a from-scratch VT (DEC/ANSI/xterm)
emulator. It includes the escape-sequence parser, the screen/page memory model
(a paged, scrollback-aware grid), terminal modes, OSC/CSI/DCS/APC handlers, the
Kitty graphics protocol, terminal search, and tmux control-mode support
(`src/terminal/tmux/`). It is the largest subsystem and is exercised by extensive
fuzzing corpora under `test/fuzz-libghostty/`.

### 9.2 libghostty-vt

A standout architectural feature: the VT engine is shipped as a **standalone,
embeddable library**, `libghostty-vt`, with a stable C API
(`include/ghostty/vt.h`, implemented by `src/terminal/c/` and `src/lib_vt.zig`).
The build produces shared, static, WASM, and Apple xcframework variants.

The `example/` directory demonstrates consuming it from many languages:

| Example prefix | Language / use |
|----------------|----------------|
| `example/c-vt-*` | C — streaming, SGR, selection, Kitty graphics, key/mouse encoding, formatter, grid traversal, size reports |
| `example/cpp-vt-stream` | C++ |
| `example/swift-vt-xcframework` | Swift via xcframework |
| `example/zig-vt*`, `example/zig-formatter` | Zig |
| `example/wasm-*` | WebAssembly (browser) |

> [!TIP]
> If you need a correct, well-tested terminal parser/state machine for your own
> application (a multiplexer, a recording tool, a web terminal), `libghostty-vt`
> lets you reuse Ghostty's engine without the GUI. Build it with the
> `libghostty-vt` build steps and link against the generated header.

### 9.3 Rendering pipeline

The renderer (`src/renderer/`) consumes terminal screen state on a dedicated
thread and draws the cell grid via a backend (`Metal.zig`, `OpenGL.zig`, or
`WebGL.zig`) wrapped by a `GenericRenderer`. It handles cursor styling, custom
shaders (`shadertoy.zig`, compiled via glslang/spirv-cross), background images,
and overlays (resize/size reports). VSync is configurable on macOS
(`window-vsync`).

### 9.4 Fonts

`src/font/` handles discovery (CoreText on macOS, fontconfig on Linux), shaping
(CoreText or HarfBuzz), fallback chains, variable fonts, font features, and a
sprite generator for box-drawing, Powerline, and Nerd Font glyphs (with codegen
from `nerd_font_codegen.py`). Metric adjustments (`adjust-*`) are applied here.

---

## 10. Code Quality and Conventions

| Aspect | Observation |
|--------|-------------|
| **Language idioms** | Idiomatic modern Zig: comptime configuration, tagged unions for actions, arena allocators for config lifetimes, `@"name"` for hyphenated fields. |
| **Module pattern** | Each subsystem has a `main.zig` (or top-level `foo.zig`) that re-exports the public API, keeping the dependency graph shallow. |
| **Comptime selection** | Runtime/renderer/font backend chosen at comptime — zero runtime dispatch cost, one implementation per build. |
| **Documentation** | Config and action fields carry rich Pandoc-Markdown doc comments that double as generated docs and `+show-config --docs`. |
| **Testing** | In-source Zig `test` blocks throughout, plus dedicated fuzzing corpora (`test/fuzz-libghostty/`) for the parser/OSC/stream. |
| **Safety** | `slow_runtime_safety` build flag enables thorough (but slow) page/pagelist integrity checks for debugging. |
| **Linting** | `.swiftlint.yml` (Swift), `typos.toml` (spelling), `.editorconfig`-style conventions. |
| **i18n** | `po/` translation catalogs; `language` option (GTK). |

---

## 11. Potential Improvements & Known Constraints

These are drawn from in-code comments (`TODO`, `BUG`, `WARNING`), community
issues, and architectural observations.

### 11.1 From the code

- **Background images use VRAM per-terminal** and are duplicated across splits; a
  noted future improvement is sharing image textures across terminals
  (`background-image` doc comment).
- **`link` is not currently settable** — the doc comment for `link` notes "This
  can't currently be set!", so custom link patterns aren't yet user-configurable
  (only the default URL matcher via `link-url`).
- **GTK window sizing ignores decorations** — `window-width`/`window-height` don't
  account for window decorations on GTK, so grid dimensions can be off unless
  decorations are disabled (documented BUG).
- **Unlimited scrollback is not yet supported** — `scrollback-limit` is always
  bounded; scrollback is fully in-memory.
- **PDF/printing, RTL, and tmux control mode** are partially supported or
  in-progress (see community issues below).

### 11.2 From community issues

The fetched issues highlight active work areas:

| Issue | Area |
|-------|------|
| #1935 | tmux Control Mode support |
| #1442 / #12183 | RTL (right-to-left) text support |
| #8272 / #12852 | Kitty graphics & drag-and-drop (OSC 72) protocol improvements |
| #9932 | macOS accessibility (AXVisibleCharacterRange) correctness |
| #1847 | Including scrollback history in state restoration |
| #5491 (closed) | GTK CPU/memory leak when windows/tabs/splits close |

### 11.3 Operational recommendations

- [ ] Mirror `deps.files.ghostty.org` artifacts for reproducible/air-gapped builds.
- [ ] Pin and track the required Zig version per release.
- [ ] In managed environments, audit any non-bundled themes (they can set any option).
- [ ] Validate distributed configs in CI with `+validate-config`.
- [ ] Enable Linux cgroup isolation for multi-tenant or resource-constrained hosts.
- [ ] Review the crash/Sentry subsystem before enabling crash reporting in privacy-sensitive deployments.
- [ ] Ensure the `xterm-ghostty` terminfo is installed (or rely on the SSH terminfo features) to avoid remote-program breakage.

---

## 12. Quick Reference

**Identity:** app ID `com.mitchellh.ghostty` · `TERM=xterm-ghostty`

**Build:**

```bash
zig build -Doptimize=ReleaseFast    # build (requires pinned Zig)
zig build test                      # tests
zig build dist && zig build distcheck
```

**Artifacts:** `zig-out/bin/ghostty`, `zig-out/share/` (themes, terminfo, shell
integration, man pages), `libghostty-vt` (shared/static/wasm/xcframework).

**Operate:**

```bash
ghostty +version           # version + build config
ghostty +show-config       # effective config
ghostty +validate-config   # validate
ghostty +crash-report      # crash reports
ghostty +new-window        # IPC to running instance
GTK_DEBUG=interactive ghostty   # GTK inspector (Linux)
```

**Architecture at a glance:** Zig core + comptime-selected apprt (GTK / embedded
macOS Swift / browser WASM) + comptime-selected renderer (Metal/OpenGL/WebGL).
Multi-threaded: GUI + per-surface IO + per-surface render. VT engine reusable as
`libghostty-vt`.

**Security defaults to verify:** `clipboard-read=ask`, `clipboard-write=allow`,
`clipboard-paste-protection=true`, `title-report=false`,
`macos-auto-secure-input=true`, `macos-shortcuts=ask`.

---

_Generated June 2026 from ghostty-org/ghostty at bfe633a. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._