stvt — SteVio Terminal

Minimal terminal emulator for macOS. Inspired by foot: fast, lean, no bloat.

No tabs, no splits, no config file — tmux handles multiplexing.

About This Code

The code on main is fully vibe-coded — generated by Claude Code as a rapid prototype. It works, but it was never hand-written or manually reviewed line by line.

This repo exists for two reasons:

1. Prototype — a working reference for my own terminal implementation
2. Tutorial base — the reference implementation for an upcoming step-by-step tutorial series, built with the stevio-claude-tutorial Claude plugin, where I rebuild the entire project by hand

The tutorial branch (coming soon) is where the real learning happens.

Stack

Layer	Technology
Core logic	Zig 0.15.2+
VT parsing & terminal state	libghostty-vt (prebuilt xcframework)
Window & events	AppKit (native macOS)
Rendering	Metal (CAMetalLayer, 3-pass GPU pipeline)
Font rasterization	Core Text (glyph atlas with on-demand rasterization)

Architecture

Zig core (all logic)                        ObjC shell (display + events)
┌─────────────────────────────────────┐     ┌───────────────────────────────┐
│ pty.zig      — PTY spawn, I/O       │     │ app.m                         │
│ terminal.zig — ghostty C API wrapper│     │   NSApplication               │
│ input.zig    — keycode → ghostty    │     │   StvtWindow (titled, no      │
│ font.zig     — glyph atlas, cache   │     │     chrome, tiling WM compat) │
│ color.zig    — Gruvbox dark palette │     │   StvtView (NSView)           │
│ stvt_api.zig — C bridge (~40 fns)   │     │   Metal rendering             │
└────────────┬────────────────────────┘     │   NSVisualEffectView blur     │
             │ C ABI (exported fns)         └───────────┬───────────────────┘
             └──────────────────────────────────────────┘
                              ↕
              lib/ghostty-vt.xcframework (prebuilt)

Zig owns all logic. ObjC handles display, events, and Metal rendering. The boundary is a C ABI with ~40 exported functions.

Features

• Native AppKit window (titled style, hidden chrome, tiling WM compatible)
• Metal GPU rendering with triple-buffered vertices and glyph atlas texture
• HiDPI/Retina support
• Full keyboard input via NSTextInputClient
• Mouse reporting (press, release, trackpad scroll with momentum filtering)
• Text selection + Cmd+C copy
• Bracketed paste mode
• Dynamic window title (OSC 0/2)
• Scrollback (Shift+PageUp/Down, Cmd+Up/Down, scroll wheel)
• Alt screen detection with DECCKM-aware scroll behavior
• 256-color Gruvbox dark theme with 75% background opacity + blur
• Inverse video (SGR 7)
• Font fallback via CTFontCreateForString (emoji/symbols rendered as grayscale)
• dispatch_source-based I/O (near-zero idle CPU)

Known Limitations

• Color emoji: Emoji and symbols render as grayscale glyphs, not color bitmaps
• macOS only: Targets aarch64-macos (Apple Silicon)

Hardcoded Defaults

No config file. All values are constants in the source.

Parameter	Value
Font	JetBrainsMonoNL Nerd Font @ 14pt
Grid	80 x 24 (initial)
Scrollback	10,000 lines
Theme	Gruvbox dark (fg #EBDBB2, bg #282828)
Background opacity	75%
PTY buffer	64 KB

Prerequisites

• macOS (Apple Silicon)
• devbox — manages Zig and dev environment
• just — command runner
• JetBrainsMonoNL Nerd Font installed

Build & Run

devbox shell          # enter dev environment (installs Zig)
just build            # debug build
just release          # release build (ReleaseFast)
just bundle           # release build + macOS .app bundle
just run              # build + run

Performance Targets

Metric	Target
Keypress-to-screen	< 5 ms
cat throughput	> 50 MB/s
Idle CPU	< 0.5%
Memory	< 30 MB RSS

Credits

• foot — architecture inspiration
• ghostty / libghostty-vt — VT parsing, terminal state, key/mouse encoding
• ghostling — minimal libghostty-vt example that served as primary reference

License

MIT