thrupty

thruPTY

throughput + through PTY + True PTY — a high-throughput, cross-platform GPU-accelerated terminal emulator in Go, built to move bytes fast and behave like a real PTY.

thrupty keeps the architecture that makes refterm — Casey Muratori's reference terminal renderer — fast, and replaces the Windows-specific C layer with idiomatic, cross-platform Go. The design follows Casey's lecture series; the solutions we deliberately preserve:

• Circular source buffer with double mapping — the scrollback ring is mapped twice back-to-back in the virtual address space, so a read that wraps around the physical end is returned as one contiguous slice (zero-copy).
• SIMD parser with runtime dispatch — the hot scan path selects AVX2, SSE2, or SWAR at startup depending on CPU features (~32/18/5.6 GB/s on plain text).
• Double-buffered line table — layout replays into a fresh line table and swaps it atomically; the render thread never blocks on the parser.
• Cell-expansion rendering — the whole grid is drawn in a single fullscreen-triangle GPU pass; the shader expands each pixel into the correct glyph sample.

Features (MVP 0.1)

• Full VT/ANSI coverage — the state machine is ported from f4 together with its test suite: SGR, scroll regions, alt-screen, 256-color/TrueColor with an OSC 4 palette, and more.
• Unicode done right — MSDF text rendering with CJK wide glyphs, combining marks, and ligatures.
• Pluggable render hosts — thrupty's own WebGPU renderer (cellgpu) or embedding into the vtui renderers: gogpu (GPU window), x11, wayland, or the console ANSI path (--tty).
• Fast interactive shell — on Windows the default is direct anonymous pipes (no ConPTY) with thrupty's own line discipline: a vtui-based command line editor with history, completion, and busy-switching between the editor and the running child.
• Modern input protocols — Kitty keyboard protocol, win32-input-mode, SGR mouse, bracketed paste, far2l extensions (clipboard, notifications, window size), OSC 52 clipboard.

Quick start

go build ./cmd/thrupty
./thrupty          # thrupty.exe on Windows

Command-line flags:

All options accept both POSIX dashes (--gui, -g) and, on Windows, slash style (/gui, /g); run thrupty --help for the full reference.

Debug helpers: --smoke-test runs a headless parser/renderer self-check; THRUPTY_INPUT_LOG=1 (or a file path) traces input translation into thrupty_input.log.

Embedding

The executable is a thin wrapper over the root package, so thrupty can be driven in-process:

package main

import (
	"os"

	"github.com/Dazzar56/thrupty"
)

func main() {
	os.Exit(thrupty.Main(os.Args))
}

Architecture

shell ──pty/pipes──▶ Session ──▶ ByteRing ──▶ parser ──▶ text grid (termcell)
                        (termui goroutine)        │            │
                          versioned snapshots ◀───┘            ▼
                              │                     renderer: bake ▶ 1 GPU pass
                              ▼
                    vtuibridge ▶ vtui hosts (gogpu / x11 / wayland / ANSI)

• ByteRing — double-mapped circular source buffer + SIMD scanner.
• terminal — VT/ANSI state machine, line table, layout.
• termcell — cell value types shared by terminal and renderer.
• renderer — WebGPU cell-expansion renderer (the cellgpu host).
• pty — ConPTY on Windows, /dev/ptmx on Unix, behind one interface.
• termui — the terminal as a self-contained vtui component (session goroutine, snapshots, command line).
• vtuibridge — composites vtui overlays over the live grid.
• cmd/thrupty — the executable (thin wrapper over thrupty.Main).

Status

MVP 0.1. Targets Windows, Linux, and macOS; runtime-verified on Windows and Linux so far (macOS builds cleanly but is untested on real hardware).

Roadmap: packaging thrupty as an embeddable component and swapping it in for the built-in terminal of f4 — see F4_INTEGRATION.md for the readiness assessment and plan. Developer-facing architecture notes live in AGENTS.md.

License

thruPTY is distributed under the GNU General Public License v2 — see LICENSE. As a Go port of refterm (GPL-2.0), it is a derivative work and carries the same license. Code ported from f4, vtui and vtinput (BSD 3-Clause, © unxed) is used in compliance with its permissive terms — credits and notices live in NOTICE.