Ghostling Libghostty Terminal

# Ghostling — libghostty Terminal Emulator

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Ghostling is a minimal viable terminal emulator built on **libghostty-vt**, the embeddable C library extracted from [Ghostty](https://ghostty.org). It uses Raylib for windowing/rendering and lives in a single C file. The project demonstrates how to wire libghostty-vt's VT parsing, terminal state, and render-state API to any 2D or GPU renderer.

## What libghostty-vt Provides

- VT sequence parsing (SIMD-optimized)
- Terminal state: cursor, styles, text reflow, scrollback
- Render state management (what cells changed and how to draw them)
- Unicode / multi-codepoint grapheme handling
- Kitty keyboard protocol, mouse tracking, focus reporting
- Zero dependencies (not even libc) — WASM-compatible

**libghostty-vt does NOT provide:** windowing, rendering, PTY management, tabs, splits, or configuration.

## Requirements

| Tool | Version |
|------|---------|
| CMake | 3.19+ |
| Ninja | any |
| C compiler | clang/gcc |
| Zig | 0.15.x (on PATH) |
| macOS | Xcode CLT or Xcode |

## Build & Run

```sh
# Clone
git clone https://github.com/ghostty-org/ghostling.git
cd ghostling

# Debug build (slow — safety checks enabled)
cmake -B build -G Ninja
cmake --build build
./build/ghostling

# Release build (optimized)
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/ghostling
```

After first configure, only the build step is needed:

```sh
cmake --build build
```

> **Warning:** Debug builds are very slow due to Ghostty's safety/correctness assertions. Always benchmark with Release builds.

## Project Structure

```
ghostling/
├── main.c          # Entire terminal implementation (single file)
├── CMakeLists.txt  # Build config; fetches libghostty-vt + Raylib
└── demo.gif
```

## Core libghostty-vt API Patterns

All implementation lives in `main.c`. Below are the key patterns extracted from it.

### 1. Initialize the Terminal

```c
#include "ghostty.h"  // provided by libghostty-vt via CMake

// Create terminal with cols x rows cells
ghostty_terminal_t *terminal = ghostty_terminal_new(
    &(ghostty_terminal_config_t){
        .cols = cols,
        .rows = rows,
    }
);
if (!terminal) { /* handle error */ }
```

### 2. Write Data from PTY into the Terminal

```c
// Read from PTY fd, feed raw bytes to libghostty-vt
ssize_t n = read(pty_fd, buf, sizeof(buf));
if (n > 0) {
    ghostty_terminal_write(terminal, buf, (size_t)n);
}
```

### 3. Send Keyboard Input

```c
// libghostty-vt encodes the correct escape sequences
ghostty_key_event_t ev = {
    .key       = GHOSTTY_KEY_A,          // key enum
    .mods      = GHOSTTY_MODS_CTRL,      // modifier flags
    .action    = GHOSTTY_ACTION_PRESS,
    .composing = false,
};

uint8_t out[64];
size_t  out_len = 0;
ghostty_terminal_key(terminal, &ev, out, sizeof(out), &out_len);

// Write encoded bytes to PTY
if (out_len > 0) write(pty_fd, out, out_len);
```

### 4. Send Mouse Events

```c
ghostty_mouse_event_t mev = {
    .x      = cell_col,   // cell column
    .y      = cell_row,   // cell row
    .button = GHOSTTY_MOUSE_LEFT,
    .action = GHOSTTY_MOUSE_PRESS,
    .mods   = GHOSTTY_MODS_NONE,
};

uint8_t out[64];
size_t  out_len = 0;
ghostty_terminal_mouse(terminal, &mev, out, sizeof(out), &out_len);
if (out_len > 0) write(pty_fd, out, out_len);
```

### 5. Resize the Terminal

```c
ghostty_terminal_resize(terminal, new_cols, new_rows);
// libghostty-vt handles text reflow automatically
// Send SIGWINCH to the c