ghostling-libghostty-terminal by aradotso/trending-skills
npx skills add https://github.com/aradotso/trending-skills --skill ghostling-libghostty-terminal技能来自 ara.so — Daily 2026 技能集合。
Ghostling 是一个基于 libghostty-vt 构建的最小可行终端模拟器,libghostty-vt 是从 Ghostty 中提取的可嵌入 C 库。它使用 Raylib 进行窗口管理和渲染,并仅包含一个 C 文件。该项目展示了如何将 libghostty-vt 的 VT 解析、终端状态和渲染状态 API 连接到任何 2D 或 GPU 渲染器。
libghostty-vt 不提供: 窗口管理、渲染、PTY 管理、标签页、分屏或配置。
| 工具 | 版本 |
|---|---|
| CMake | 3.19+ |
| Ninja | 任意 |
| C 编译器 | clang/gcc |
| Zig | 0.15.x(在 PATH 中) |
| macOS | Xcode CLT 或 Xcode |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
# 克隆
git clone https://github.com/ghostty-org/ghostling.git
cd ghostling
# 调试构建(慢 — 启用安全检查)
cmake -B build -G Ninja
cmake --build build
./build/ghostling
# 发布构建(优化)
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/ghostling
首次配置后,只需执行构建步骤:
cmake --build build
警告: 由于 Ghostty 的安全/正确性断言,调试构建非常慢。请始终使用发布构建进行基准测试。
ghostling/
├── main.c # 整个终端实现(单个文件)
├── CMakeLists.txt # 构建配置;获取 libghostty-vt + Raylib
└── demo.gif
所有实现都位于 main.c 中。以下是从中提取的关键模式。
#include "ghostty.h" // 由 libghostty-vt 通过 CMake 提供
// 创建具有 cols x rows 个单元格的终端
ghostty_terminal_t *terminal = ghostty_terminal_new(
&(ghostty_terminal_config_t){
.cols = cols,
.rows = rows,
}
);
if (!terminal) { /* 处理错误 */ }
// 从 PTY 文件描述符读取,将原始字节提供给 libghostty-vt
ssize_t n = read(pty_fd, buf, sizeof(buf));
if (n > 0) {
ghostty_terminal_write(terminal, buf, (size_t)n);
}
// libghostty-vt 编码正确的转义序列
ghostty_key_event_t ev = {
.key = GHOSTTY_KEY_A, // 键枚举
.mods = GHOSTTY_MODS_CTRL, // 修饰符标志
.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);
// 将编码后的字节写入 PTY
if (out_len > 0) write(pty_fd, out, out_len);
ghostty_mouse_event_t mev = {
.x = cell_col, // 单元格列
.y = 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);
ghostty_terminal_resize(terminal, new_cols, new_rows);
// libghostty-vt 自动处理文本重排
// 在此之后向子进程发送 SIGWINCH
struct winsize ws = { .ws_col = new_cols, .ws_row = new_rows };
ioctl(pty_fd, TIOCSWINSZ, &ws);
kill(child_pid, SIGWINCH);
渲染状态 API 会精确地告诉你哪些单元格已更改以及如何绘制它们 — 无需每帧都重绘所有内容。
// 获取渲染状态句柄
ghostty_render_state_t *rs = ghostty_terminal_render_state(terminal);
// 开始一个渲染过程(快照当前状态)
ghostty_render_state_begin(rs);
// 迭代脏单元格
ghostty_render_cell_iter_t iter = {0};
ghostty_render_cell_t cell;
while (ghostty_render_state_next_cell(rs, &iter, &cell)) {
// cell.col, cell.row — 网格位置
// cell.codepoint — Unicode 码位(0 = 空)
// cell.fg.r/g/b — 前景色 RGB
// cell.bg.r/g/b — 背景色 RGB
// cell.attrs.bold — 粗体标志
// cell.attrs.italic — 斜体标志
// cell.attrs.reverse — 反色标志
// 示例:使用 Raylib 绘制
Color fg = { cell.fg.r, cell.fg.g, cell.fg.b, 255 };
Color bg = { cell.bg.r, cell.bg.g, cell.bg.b, 255 };
Rectangle rect = {
.x = cell.col * cell_width,
.y = cell.row * cell_height,
.width = cell_width,
.height = cell_height,
};
DrawRectangleRec(rect, bg);
if (cell.codepoint != 0) {
char glyph[8] = {0};
// 自行将码位编码为 UTF-8 或使用辅助函数
encode_utf8(cell.codepoint, glyph);
DrawText(glyph, (int)rect.x, (int)rect.y, font_size, fg);
}
}
// 结束渲染过程(将单元格标记为已清理)
ghostty_render_state_end(rs);
// 将视口向上/向下滚动 N 行
ghostty_terminal_scroll(terminal, -3); // 向上滚动 3 行
ghostty_terminal_scroll(terminal, 3); // 向下滚动 3 行
// 滚动到底部
ghostty_terminal_scroll_bottom(terminal);
ghostty_cursor_t cursor;
ghostty_terminal_cursor(terminal, &cursor);
// cursor.col, cursor.row — 单元格位置
// cursor.visible — 布尔值
// cursor.shape — GHOSTTY_CURSOR_BLOCK, _UNDERLINE, _BAR
ghostty_terminal_free(terminal);
libghostty-vt 不提供 PTY 管理 — 你需要自行处理:
#include <pty.h> // openpty
#include <unistd.h>
#include <stdlib.h>
int master_fd, slave_fd;
struct winsize ws = { .ws_row = rows, .ws_col = cols,
.ws_xpixel = 0, .ws_ypixel = 0 };
openpty(&master_fd, &slave_fd, NULL, NULL, &ws);
pid_t child = fork();
if (child == 0) {
// 子进程:成为会话领导者,附加从属 PTY
setsid();
ioctl(slave_fd, TIOCSCTTY, 0);
dup2(slave_fd, STDIN_FILENO);
dup2(slave_fd, STDOUT_FILENO);
dup2(slave_fd, STDERR_FILENO);
close(master_fd);
close(slave_fd);
char *shell = getenv("SHELL");
if (!shell) shell = "/bin/sh";
execl(shell, shell, NULL);
_exit(1);
}
// 父进程:使用 master_fd 进行读/写
close(slave_fd);
项目通过 CMake FetchContent 自动获取 libghostty-vt:
cmake_minimum_required(VERSION 3.19)
project(ghostling C)
include(FetchContent)
# libghostty-vt
FetchContent_Declare(
libghostty
URL https://release.files.ghostty.org/tip/libghostty-vt-<platform>.tar.gz
)
FetchContent_MakeAvailable(libghostty)
# Raylib
FetchContent_Declare(
raylib
GIT_REPOSITORY https://github.com/raysan5/raylib.git
GIT_TAG 5.0
)
FetchContent_MakeAvailable(raylib)
add_executable(ghostling main.c)
target_link_libraries(ghostling PRIVATE ghostty-vt raylib)
// 键
GHOSTTY_KEY_A … GHOSTTY_KEY_Z
GHOSTTY_KEY_UP, GHOSTTY_KEY_DOWN, GHOSTTY_KEY_LEFT, GHOSTTY_KEY_RIGHT
GHOSTTY_KEY_ENTER, GHOSTTY_KEY_BACKSPACE, GHOSTTY_KEY_ESCAPE, GHOSTTY_KEY_TAB
GHOSTTY_KEY_F1 … GHOSTTY_KEY_F12
// 修饰符(位掩码)
GHOSTTY_MODS_NONE
GHOSTTY_MODS_SHIFT
GHOSTTY_MODS_CTRL
GHOSTTY_MODS_ALT
GHOSTTY_MODS_SUPER
// 鼠标按钮
GHOSTTY_MOUSE_LEFT, GHOSTTY_MOUSE_RIGHT, GHOSTTY_MOUSE_MIDDLE
GHOSTTY_MOUSE_WHEEL_UP, GHOSTTY_MOUSE_WHEEL_DOWN
// 光标形状
GHOSTTY_CURSOR_BLOCK, GHOSTTY_CURSOR_UNDERLINE, GHOSTTY_CURSOR_BAR
// 将 master_fd 设置为非阻塞
fcntl(master_fd, F_SETFL, O_NONBLOCK);
// 在你的主循环中:
uint8_t buf[4096];
ssize_t n;
while ((n = read(master_fd, buf, sizeof(buf))) > 0) {
ghostty_terminal_write(terminal, buf, (size_t)n);
}
// EAGAIN 表示没有可用数据 — 不是错误
ghostty_key_t raylib_key_to_ghostty(int rl_key) {
switch (rl_key) {
case KEY_A: return GHOSTTY_KEY_A;
case KEY_ENTER: return GHOSTTY_KEY_ENTER;
case KEY_BACKSPACE: return GHOSTTY_KEY_BACKSPACE;
case KEY_UP: return GHOSTTY_KEY_UP;
case KEY_DOWN: return GHOSTTY_KEY_DOWN;
// ... 等等
default: return GHOSTTY_KEY_INVALID;
}
}
int total_rows = ghostty_terminal_total_rows(terminal);
int viewport_rows = rows; // 你的网格高度
int scroll_offset = ghostty_terminal_scroll_offset(terminal);
float bar_h = (float)viewport_rows / total_rows * window_height;
float bar_y = (float)scroll_offset / total_rows * window_height;
DrawRectangle(window_width - SCROLLBAR_W, (int)bar_y,
SCROLLBAR_W, (int)bar_h, GRAY);
| 问题 | 解决方法 |
|---|---|
构建失败:zig not found | 安装 Zig 0.15.x 并确保其在 $PATH 中 |
| 调试构建极慢 | 使用发布构建:cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release |
| 终端渲染乱码 | 确认在迭代单元格之前调用了 ghostty_render_state_begin,之后调用了 ghostty_render_state_end |
| 子进程未收到调整大小信号 | 在 ghostty_terminal_resize 之后调用 ioctl(pty_fd, TIOCSWINSZ, &ws) 和 kill(child_pid, SIGWINCH) |
| Kitty 键盘协议失效 | 已知的上游 Raylib/GLFW 限制 — libghostty-vt 正确支持它,但需要更丰富的输入事件 |
| 颜色显示错误 | 检查 cell.fg/cell.bg — libghostty-vt 将调色板解析为 RGB,直接使用这些值 |
ghostty_terminal_write 崩溃 | 确保传递的缓冲区有效且 len > 0;切勿传递 NULL |
你必须自己实现以下内容:
完整的 libghostty-vt C API 文档:https://libghostty.tip.ghostty.org/group__render.html
每周安装数
78
代码仓库
GitHub 星标数
8
首次出现
2 天前
安全审计
安装于
github-copilot78
codex78
warp78
kimi-cli78
gemini-cli78
amp78
Skill by ara.so — Daily 2026 Skills collection.
Ghostling is a minimal viable terminal emulator built on libghostty-vt , the embeddable C library extracted from Ghostty. 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.
libghostty-vt does NOT provide: windowing, rendering, PTY management, tabs, splits, or configuration.
| Tool | Version |
|---|---|
| CMake | 3.19+ |
| Ninja | any |
| C compiler | clang/gcc |
| Zig | 0.15.x (on PATH) |
| macOS | Xcode CLT or Xcode |
# 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:
cmake --build build
Warning: Debug builds are very slow due to Ghostty's safety/correctness assertions. Always benchmark with Release builds.
ghostling/
├── main.c # Entire terminal implementation (single file)
├── CMakeLists.txt # Build config; fetches libghostty-vt + Raylib
└── demo.gif
All implementation lives in main.c. Below are the key patterns extracted from it.
#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 */ }
// 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);
}
// 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);
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);
ghostty_terminal_resize(terminal, new_cols, new_rows);
// libghostty-vt handles text reflow automatically
// Send SIGWINCH to the child process after this
struct winsize ws = { .ws_col = new_cols, .ws_row = new_rows };
ioctl(pty_fd, TIOCSWINSZ, &ws);
kill(child_pid, SIGWINCH);
The render state API tells you exactly which cells changed and how to draw them — no need to redraw everything every frame.
// Get render state handle
ghostty_render_state_t *rs = ghostty_terminal_render_state(terminal);
// Begin a render pass (snapshot current state)
ghostty_render_state_begin(rs);
// Iterate dirty cells
ghostty_render_cell_iter_t iter = {0};
ghostty_render_cell_t cell;
while (ghostty_render_state_next_cell(rs, &iter, &cell)) {
// cell.col, cell.row — grid position
// cell.codepoint — Unicode codepoint (0 = empty)
// cell.fg.r/g/b — foreground RGB
// cell.bg.r/g/b — background RGB
// cell.attrs.bold — bold flag
// cell.attrs.italic — italic flag
// cell.attrs.reverse — reverse video
// Example: draw with Raylib
Color fg = { cell.fg.r, cell.fg.g, cell.fg.b, 255 };
Color bg = { cell.bg.r, cell.bg.g, cell.bg.b, 255 };
Rectangle rect = {
.x = cell.col * cell_width,
.y = cell.row * cell_height,
.width = cell_width,
.height = cell_height,
};
DrawRectangleRec(rect, bg);
if (cell.codepoint != 0) {
char glyph[8] = {0};
// encode codepoint to UTF-8 yourself or use a helper
encode_utf8(cell.codepoint, glyph);
DrawText(glyph, (int)rect.x, (int)rect.y, font_size, fg);
}
}
// End render pass (marks cells as clean)
ghostty_render_state_end(rs);
// Scroll viewport up/down by N rows
ghostty_terminal_scroll(terminal, -3); // scroll up 3
ghostty_terminal_scroll(terminal, 3); // scroll down 3
// Scroll to bottom
ghostty_terminal_scroll_bottom(terminal);
ghostty_cursor_t cursor;
ghostty_terminal_cursor(terminal, &cursor);
// cursor.col, cursor.row — cell position
// cursor.visible — bool
// cursor.shape — GHOSTTY_CURSOR_BLOCK, _UNDERLINE, _BAR
ghostty_terminal_free(terminal);
libghostty-vt has no PTY management — you own this:
#include <pty.h> // openpty
#include <unistd.h>
#include <stdlib.h>
int master_fd, slave_fd;
struct winsize ws = { .ws_row = rows, .ws_col = cols,
.ws_xpixel = 0, .ws_ypixel = 0 };
openpty(&master_fd, &slave_fd, NULL, NULL, &ws);
pid_t child = fork();
if (child == 0) {
// Child: become session leader, attach slave PTY
setsid();
ioctl(slave_fd, TIOCSCTTY, 0);
dup2(slave_fd, STDIN_FILENO);
dup2(slave_fd, STDOUT_FILENO);
dup2(slave_fd, STDERR_FILENO);
close(master_fd);
close(slave_fd);
char *shell = getenv("SHELL");
if (!shell) shell = "/bin/sh";
execl(shell, shell, NULL);
_exit(1);
}
// Parent: use master_fd for read/write
close(slave_fd);
The project fetches libghostty-vt automatically via CMake FetchContent:
cmake_minimum_required(VERSION 3.19)
project(ghostling C)
include(FetchContent)
# libghostty-vt
FetchContent_Declare(
libghostty
URL https://release.files.ghostty.org/tip/libghostty-vt-<platform>.tar.gz
)
FetchContent_MakeAvailable(libghostty)
# Raylib
FetchContent_Declare(
raylib
GIT_REPOSITORY https://github.com/raysan5/raylib.git
GIT_TAG 5.0
)
FetchContent_MakeAvailable(raylib)
add_executable(ghostling main.c)
target_link_libraries(ghostling PRIVATE ghostty-vt raylib)
// Keys
GHOSTTY_KEY_A … GHOSTTY_KEY_Z
GHOSTTY_KEY_UP, GHOSTTY_KEY_DOWN, GHOSTTY_KEY_LEFT, GHOSTTY_KEY_RIGHT
GHOSTTY_KEY_ENTER, GHOSTTY_KEY_BACKSPACE, GHOSTTY_KEY_ESCAPE, GHOSTTY_KEY_TAB
GHOSTTY_KEY_F1 … GHOSTTY_KEY_F12
// Modifiers (bitmask)
GHOSTTY_MODS_NONE
GHOSTTY_MODS_SHIFT
GHOSTTY_MODS_CTRL
GHOSTTY_MODS_ALT
GHOSTTY_MODS_SUPER
// Mouse buttons
GHOSTTY_MOUSE_LEFT, GHOSTTY_MOUSE_RIGHT, GHOSTTY_MOUSE_MIDDLE
GHOSTTY_MOUSE_WHEEL_UP, GHOSTTY_MOUSE_WHEEL_DOWN
// Cursor shapes
GHOSTTY_CURSOR_BLOCK, GHOSTTY_CURSOR_UNDERLINE, GHOSTTY_CURSOR_BAR
// Set master_fd non-blocking
fcntl(master_fd, F_SETFL, O_NONBLOCK);
// In your main loop:
uint8_t buf[4096];
ssize_t n;
while ((n = read(master_fd, buf, sizeof(buf))) > 0) {
ghostty_terminal_write(terminal, buf, (size_t)n);
}
// EAGAIN means no data available — not an error
ghostty_key_t raylib_key_to_ghostty(int rl_key) {
switch (rl_key) {
case KEY_A: return GHOSTTY_KEY_A;
case KEY_ENTER: return GHOSTTY_KEY_ENTER;
case KEY_BACKSPACE: return GHOSTTY_KEY_BACKSPACE;
case KEY_UP: return GHOSTTY_KEY_UP;
case KEY_DOWN: return GHOSTTY_KEY_DOWN;
// ... etc
default: return GHOSTTY_KEY_INVALID;
}
}
int total_rows = ghostty_terminal_total_rows(terminal);
int viewport_rows = rows; // your grid height
int scroll_offset = ghostty_terminal_scroll_offset(terminal);
float bar_h = (float)viewport_rows / total_rows * window_height;
float bar_y = (float)scroll_offset / total_rows * window_height;
DrawRectangle(window_width - SCROLLBAR_W, (int)bar_y,
SCROLLBAR_W, (int)bar_h, GRAY);
| Problem | Fix |
|---|---|
Build fails: zig not found | Install Zig 0.15.x and ensure it's on $PATH |
| Debug build extremely slow | Use Release: cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release |
| Terminal renders garbage | Verify you're calling ghostty_render_state_begin before iterating cells and ghostty_render_state_end after |
| Child process not getting resize | Call ioctl(pty_fd, TIOCSWINSZ, &ws) AND kill(child_pid, SIGWINCH) after |
You must implement these yourself:
Full libghostty-vt C API docs: https://libghostty.tip.ghostty.org/group__render.html
Weekly Installs
78
Repository
GitHub Stars
8
First Seen
2 days ago
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
github-copilot78
codex78
warp78
kimi-cli78
gemini-cli78
amp78
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
120,000 周安装
ghostty_terminal_resize| Kitty keyboard protocol broken | Known upstream Raylib/GLFW limitation — libghostty-vt supports it correctly but needs richer input events |
| Colors look wrong | Check cell.fg/cell.bg — libghostty-vt resolves palette to RGB, use those values directly |
ghostty_terminal_write crashes | Ensure buffer passed is valid and len > 0; never pass NULL |