Skip to content

Home

Jump to bottom
mike-ward edited this page Aug 7, 2026 · 3 revisions

go-term

go-term is an embeddable terminal-emulator widget for the go-gui framework, written in Go. You embed it into an app the way you embed a text widget. What you get is a real terminal: a shell over a PTY, rendered cell by cell through a GPU-accelerated gui.DrawCanvas.

It targets macOS, Linux, and Windows (ConPTY). It is pre-1.0, and the API is deliberately small and stable. See Embedding for the contract.

Terminal support

The escape-sequence parser is the core of the project, and its coverage is the reason modern TUIs work. The surface is verified against recorded byte streams, fuzzed input, and vttest-parity checks that run in CI on every push. docs/terminal-verification.md in the repository carries the capability matrix.

What the parser covers:

  • The full legacy surface: SGR and truecolor, the alternate screen, scroll regions, rectangular area operations, selective erase, and device replies
  • Modern protocols: the Kitty Graphics Protocol, sixel, iTerm2 images, OSC 8 hyperlinks, the Kitty Keyboard Protocol, bracketed paste, focus reporting, and synchronized output
  • Shell-aware sequences: OSC 7 working-directory reports, OSC 133 semantic shell marks, and mode 2031 color-scheme notifications

The one deliberate omission is xterm's modifyOtherKeys. The Kitty Keyboard Protocol is implemented, and it disambiguates strictly more. It distinguishes release events and left and right modifiers. It also resolves the Ctrl+I versus Tab collisions that modifyOtherKeys level 2 exists to fix. The decision is documented in the repository, with the cost spelled out.

Wide characters and bidirectional text

Text rendering handles the cases that trip terminals up: East Asian wide characters, grapheme clusters, emoji with ZWJ joins, variation selectors, flags, and full UAX#9 bidirectional text for right-to-left scripts. The grid tracks wide-cell state, so reflow, selection, and copy all stay consistent across wrapped and RTL lines.

Falcon

Falcon is the example app that ships with go-term. It is a full terminal emulator: tabs, split panes, workspace save and restore, a live browser over 602 color themes, session recording and replay, and a reloadable config file. It is the reference embedder for term/workspace and a daily driver on macOS.

cd examples/falcon && go run .

See Falcon for installation, flags, and how it compares to the other terminal programs.

Pages

  • Embedding — build a terminal into your own go-gui app
  • Configuration — the user config file
  • Usage — keys, mouse, copy mode, shell integration, recording
  • Falcon — the falcon example app and its place among terminals

Repository

The source lives at github.com/go-gui-org/go-term. The repository's docs/ directory is the reference for this wiki: docs/config.md is the complete config reference, and docs/terminal-verification.md is the verified protocol surface.

Clone this wiki locally