Skip to content
nomad-softwarePublic

About

A terminal emulator written in Go.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Termite

A GPU-rendered terminal emulator for Linux, written in Go with Qt 6 (via qute) and OpenGL 3.3 core. It targets TERM=xterm-256color and implements the xterm subset that shells, vim, tmux, htop, less and fzf actually use, plus tabs, splits and saved layouts.

Termite with two tabs: the first split into vim editing Go source with syntax colours beside two stacked shells, one showing bold, italic, underlined, curly-underlined, struck-through and inverse text, the 16-colour palette, a truecolor gradient, box drawing around wide CJK characters and an emoji, braille and shade blocks and an underlined hyperlink, the other a coloured directory listing; each pane has a header with its directory

The screenshot is drawn by make screenshot (needs Xvfb, ImageMagick and vim).

Why Termite

  • Fast where it counts. The parser takes plain text at over 400 MB/s and full-colour output at 165 MB/s, with zero allocations in steady state. A 100 MB cat finishes in under a second, even on a software renderer. Frames draw only the cells in use and are paced to the display, so heavy output never wastes CPU on frames nobody sees. A keypress reaches the screen in single-digit milliseconds.
  • Costs nothing when idle. There are no polling timers: redraws happen only after output, nothing watches the config file, and the cursor blinks only when a program asks for it. An idle window uses 0 CPU ticks.
  • Light on memory. Each cell is 16 bytes with no pointers, and the scrollback is one ring buffer allocated up front. Scrolling moves an index and copies nothing, and pages are only touched once lines are written. Clear Scrollback gives the memory back to the system and wipes the old text, also while a full-screen program has the alternate screen up. Closed windows are deleted along with their scrollback.
  • Resizes smoothly. Reflow rewraps 10,000 lines of scrollback in about 12 ms, writing straight into the new buffer. Dragging a window edge doesn't stutter or pile up garbage.
  • Correct where others cut corners. Character widths follow glibc's wcwidth, so vim, shells and TUIs stay aligned. Wide characters wrap and reflow without stray spaces. Box drawing, braille and Powerline glyphs are drawn procedurally, so they join without gaps at any size.
  • The modern protocols programs use. Truecolor, every underline style and underline colours, OSC 8 hyperlinks, OSC 52 clipboard, OSC 7 directories, synchronized output (2026), bracketed paste, SGR and X10 mouse, focus events and the kitty keyboard protocol.
  • A workspace, not just a window. Flat tabs that share the window's width, splits that can be rearranged by dragging a pane's header, with cursor-aligned Alt+Arrow navigation, input broadcast to a tab or a group of panes (their headers take the focused pane's colours), saved layouts that reopen each pane in its directory and command, pane headers that show where each shell is, and a toolbar (new window, new tab, splits, zoom, broadcast, options, exit) that can be hidden.
  • Every pane at its own text size. Ctrl+= and Ctrl+- make the text of the pane you are typing in larger or smaller, not the whole window's: keep a log tailing in small text beside an editor at a comfortable size, or blow one pane up to show someone, while the rest stay as they are. With input broadcast, every pane it reaches changes together. Sizes are on screen only (the config's font size stays the base, and changing it keeps each pane's step), saved layouts remember them, and panes at the same size share one glyph atlas, freed when no pane uses that size.
  • Zoom a pane without losing track of the rest. Ctrl+Shift+Z lets a pane fill its tab, and pressing it again puts the others back exactly as they were. The hidden panes keep their size, so the programs in them are never resized. It's clear that more is there: the pane's header counts the hidden panes, the tab's title is marked ⤢, and a minimap in the corner draws the tab's layout. Click a pane on the map to jump to it.
  • Safe with what you paste and run. Bracketed pastes can't be broken out of, multi-line pastes into programs that don't bracket them ask first, programs may set the clipboard but not read it unless you allow it, and titles set by programs are never shown.
  • Comfortable to configure. One JSON file, with problems shown in place while the rest still loads. There is also a native Options dialog with a theme editor and live preview, and a shortcut editor that catches clashes.

Build and run

The easiest way to get Termite is the AppImage from a release (see AppImage below). To build it yourself, you need: Go 1.27+, Qt 6.12 or newer development files (Widgets, OpenGL, OpenGLWidgets, Svg), pkg-config, OpenGL 3.3 drivers and a C++17 compiler. Termite runs on Linux only.

make build                   # or: go build
./termite                    # your $SHELL
./termite -- htop            # run a command
./termite --layout work      # open a saved layout
./termite --write-config     # write the default config.json
make appimage                # Termite-<version>-x86_64.AppImage

On every start, Termite writes a desktop entry (~/.local/share/applications/termite.desktop) and its icon (~/.local/share/icons/hicolor/256x256/apps/termite.png). These point at the copy that is running, so it appears in the desktop's menus and can be pinned to a dock. Set TERMITE_NO_DESKTOP_ENTRY=1 to skip this. packaging/termite.desktop is a static entry for packagers. The icon is drawn from packaging/termite.svg (make icons) and embedded in the binary.

The first build compiles qute's C++ shims and takes a couple of minutes; later builds are cached. Go builds in its own cache, outside the project: make build leaves only ./termite (and test/termite-headless), and make appimage works in a temporary folder and leaves only the AppImage.

Profiling: --cpuprofile FILE, --memprofile FILE, or --pprof localhost:6060 for live net/http/pprof. TERMITE_DEBUG=startup,latency prints time-to-first-frame and keypress-to-frame latencies. TERMITE_DEBUG=frames prints, once a second while painting, how many frames were drawn, their average and worst time (including the GPU's work, through glFinish) and the instances each drew.

Configuration

~/.config/termite/config.json (or $XDG_CONFIG_HOME/termite). It is read at start-up. After editing it by hand, press Ctrl+Shift+R (reload_config) to apply the changes without a restart. termite --write-config writes every option with its default (to the --config path when one is given), and never overwrites an existing file (a dangling symlink is followed, creating the file it names). Settings saved from the Options dialog keep a symlinked config file a symlink, writing to the file it points at. Problems (misspelt keys, bad values, values of the wrong type, unknown key names, two actions on one shortcut, syntax errors with their line) are shown in red in every pane's header, from start-up, until the file is fixed; whatever is valid still applies (a file that isn't JSON at all falls back to the defaults, an empty one loads them with no complaint, and a shortcut given as something other than a string, null too, keeps its default; "none" unbinds it). Sizes outside the Options dialog's ranges are brought within them.

Most options can also be set in the Options dialog (right-click → Options…). Its General tab covers scrollback, copy on select, paste warning and OSC 52 clipboard access. Its User interface tab covers the window theme, the toolbar, font and size (any installed font, with a warning if it isn't monospaced), the pane headers' font and size, line height, padding, ligatures, bold-as-bright, the scrollbar, and cursor style and blinking. Its Colours tab lists the colour themes: pick the one to use, rename it (double-click it, press F2 or use Rename), edit its terminal and pane header colours (the search match shown is in its selection colours) and 16-colour palette with a live preview, add, duplicate or remove themes, and restore the built-in ones (Solarized Dark, Solarized Light, Ambience). Its Keyboard Shortcuts tab rebinds every action: click a field, press the keys, or clear it to unbind. Shortcuts used by more than one action are reported and not saved. OK or Apply saves to config.json and applies at once. The window size and maximized state are saved when a window closes and used for new windows.

Key Default Notes
font_family "Iosevka Term Curly" falls back to monospace where it isn't installed; fallback and colour emoji come from Qt/fontconfig
font_size 15.0 points, 5 to 72
header_font_family "Iosevka Term Curly" pane headers' font; empty uses font_family
header_font_size 12 pane headers' size in points, 5 to 72; 0 is 85% of font_size
line_height 1.0 multiplier, 0.8 to 2.5
theme "ubuntu-ambiance" id of the theme to use, a key of themes
window_theme "system" system, light, dark: colours of the menus, dialogs and tab bar
toolbar true show the toolbar (New Window, New Tab, Split Horizontally, Split Vertically, Zoom, Broadcast, Options, Exit) above the tabs; Exit (Ctrl+W) types exit into the current pane only
themes the built-in themes {"id": {"name": "…", "foreground": "#…", "background": "#…", "cursor": "#…", "cursor_text": …, "selection": …, "selection_text": …, "palette": [16 colours]}}; when present it replaces the built-in list, so themes can be removed. cursor_text, selection, selection_text and the pane header colours header_background, header_focused_background, header_text and header_focused_text are optional
scrollback 10000 lines, up to 1,000,000
cursor_style "block" block, beam, underline; programs may choose another shape (DECSCUSR) until they reset it
cursor_blink false allows blinking when an app requests it
copy_on_select true primary selection is always set
paste_warning "unbracketed" always, unbracketed, never
ligatures false needs a font with ligatures
shell $SHELL e.g. ["/bin/zsh", "-l"]
padding 0 logical pixels, up to 50
osc52 "write" off, write, read-write
bold_is_bright false
scrollbar true show a scrollbar beside each pane
word_chars "-_./~:@%+#=?&" extra word characters for double-click
window_width, window_height, window_maximized 900, 560, false saved automatically
keybindings see below {"copy": "ctrl+shift+x"}, or "none" to unbind. A shifted symbol is matched by the key it is on: ctrl+plus is Ctrl and the = key

Default keybindings

Action Keys Action Keys
copy Ctrl+Shift+C paste Ctrl+Shift+V
search Ctrl+Shift+F new_tab Ctrl+Shift+T
new_window Ctrl+N exit (types exit into the pane) Ctrl+W
close_pane Ctrl+Shift+Q split_vertical (Split Vertically: side by side) Ctrl+Shift+E
split_horizontal (Split Horizontally: stacked) Ctrl+Shift+O focus_up/down/left/right Alt+Arrows
next_tab / prev_tab Ctrl+PgDn / Ctrl+PgUp move_tab_left/right Ctrl+Shift+PgUp/PgDn
scroll_page_up/down Shift+PgUp/PgDn scroll_top/bottom Shift+Home/End
font_bigger/smaller/reset (this pane's text) Ctrl+= / Ctrl+- / Ctrl+0 reload_config Ctrl+Shift+R
broadcast_all (panes in tab) Ctrl+Shift+B broadcast_group unbound
group_toggle (pane in group) Ctrl+Shift+G save_layout / load_layout Ctrl+Shift+S / Ctrl+Shift+L
context_menu Menu key options Ctrl+,
zoom_pane (Zoom Pane) Ctrl+Shift+Z
clear_scrollback, reset_terminal, edit_config unbound

Right-click opens the context menu (Shift+right-click while an application uses the mouse). It covers copy and paste, opening or copying the link under the pointer, splitting, zooming, broadcast, layouts, find, clear scrollback, reset and Options…. With window_theme set to system the menus and dialogs use the desktop's own style; light and dark give them termite's own. The colour theme applies to the terminal, pane headers and search bar.

Moving focus with Alt+Arrows goes to the adjacent pane on that side that lines up with the text cursor, as in tmux and vim, never to a pane that only touches at a corner.

Every pane has a header showing its current directory, from the shell's OSC 7 report or the foreground process. Each tab is named after its focused pane's header, and the window title is the last part of the current tab's focused pane's directory (share for /usr/share). Titles set by programs are ignored. A new pane made by splitting takes the keyboard focus. Drag a pane's header onto another pane of the same tab to move it there: it splits that pane on the side nearest the pointer (shaded while you drag), keeps its shell, and takes the focus. Escape cancels the drag.

Zoom Pane (Ctrl+Shift+Z, the toolbar's Zoom or the context menu) hides the other panes of the tab so the pane fills it; pressing it again puts them back as they were. The hidden panes keep their size, so programs in them are not redrawn. While zoomed, the pane's header reads ⤢ Zoomed: 2 panes hidden, the tab's title starts with ⤢, and a minimap in the pane's top right corner draws the tab's layout with the zoomed pane filled in (and hidden panes that broadcast input reaches tinted). Click a pane on the map to zoom it instead, or the zoomed one to show them all. Alt+Arrows moves the zoom to the neighbouring pane that way, as the panes lay before the zoom (towards the window's edge it leaves the zoom alone). Splitting or the zoomed pane closing also shows them; a hidden pane closing keeps the zoom, and the zoomed pane's program sees no resize.

Larger text (Ctrl+=), Smaller text (Ctrl+-) and Reset text size (Ctrl+0) change the pane you are typing in alone, in steps of 10% (each the last times 1.1) from about 32% to 460% of the configured font size, or every pane input is broadcast to. A pane made by splitting, a new tab and a new window start at the configured size. The steps are never written to the config: changing font_size (in the file or Options) moves every pane, each keeping its own step. Saved layouts record each pane's step (font_step).

Mouse: drag to select (Alt for block selection), double/triple-click for word/line, middle-click pastes the primary selection, Ctrl+click opens URLs and OSC 8 links (Ctrl+hover underlines them). Shift bypasses application mouse reporting. Find opens a search bar at the bottom of the pane and shows one match at a time, the newest first: Enter goes to the next older match, Shift+Enter to the next newer one, and Esc closes the search bar.

Layouts are saved as JSON under ~/.config/termite/layouts/, recording the split tree, sizes, each pane's working directory, command and text size for every tab. Loading a layout replaces the window's tabs with its own. Layouts can be removed from the Layouts menu.

AppImage

Releases for Linux are an AppImage, Termite-*-x86_64.AppImage: one file with Qt inside it, which runs without installing anything. Make it executable and run it. On its first start it adds itself to the desktop's menus (see above), so it can be started and pinned like any installed application.

It is built by a GitHub workflow (.github/workflows/appimage.yml), which runs the tests and then packaging/appimage.sh on Ubuntu 22.04 with Qt's own build of Qt 6.12 (qute needs 6.12 or newer):

  • Pushing a tag starting with v builds it and attaches it to a release of that name: git tag v1.0.0 && git push origin v1.0.0.
  • It can also be run by hand from the Actions tab of the repository (AppImage > Run workflow), which leaves the AppImage as an artifact of the run to download.

It runs under both X11 and Wayland, and on GTK desktops takes its colours, light or dark, from the desktop through Qt's GTK theme plugin. OpenGL and the C library (glibc) are deliberately not put in it: they have to match the system's graphics drivers, so the system's own are used. It is built on an old distribution instead, and runs on any with glibc 2.35 or later: Ubuntu 22.04, Debian 12, Fedora 36 and anything newer, or rolling distributions such as CachyOS and Arch. Before an AppImage is made, the script checks that the X11, Wayland and GL plugins are in it and no GL library is; afterwards it starts it in a virtual X server with Mesa's software renderer, so a build that can't open a window and draw is never released.

Shells started from the AppImage see the system as it is: no library paths are added, and the variables the AppImage runtime sets for Termite itself (APPIMAGE, APPDIR, ARGV0, OWD) are not passed on, nor are the start-up notification tokens meant for Termite's own window (DESKTOP_STARTUP_ID, XDG_ACTIVATION_TOKEN).

make appimage runs the same script locally. It works in a temporary folder outside the project, removed afterwards, and leaves only the AppImage in the project folder. The packaging tools it downloads (linuxdeploy and its Qt plugin) are kept in ~/.cache/termite-appimage; delete that folder to fetch their latest build. An AppImage built on a newer system only runs on systems at least as new.

Architecture

main.go              Qt application entry point, flags, profiling
test/headless        runs a program through the emulator core and prints the screen (testing)
test/guibench        GUI benchmark workloads and runner (make guibench)
internal/term        emulator core: cells, scrollback ring, parser, xterm emulation (no GUI deps)
internal/pty         child process on a PTY; one reader+parser goroutine per pane
internal/input       key (xterm + kitty), mouse (SGR and X10) and paste encoding
internal/render      glyph atlas, procedural box drawing, OpenGL renderer
internal/qtgl        the terminal's QOpenGLWidget, a Go subclass of qute's
internal/ui          windows, toolbar, tabs, splits, panes, layouts, actions
internal/icons       toolbar and tab icons as embedded SVG (no Qt)
internal/config      JSON config, in-place setting writes, themes, key chords
internal/desktop     desktop entry and icon install
internal/appicon     embedded program icon
packaging            AppImage script and AppRun, desktop entry, icon SVG, screenshot scripts
.github/workflows    appimage.yml: builds the AppImage on v tags or by hand

Data flow per pane: the reader goroutine reads the PTY, locks the terminal, parses, unlocks and requests a redraw. Requests are coalesced and paced to the screen's refresh rate (the first output after a pause paints at once), so floods of output never render per chunk. On paint, the main thread locks briefly to copy only the damaged rows, then builds instances and draws without the lock. All Qt and GL calls happen on the main thread.

Key implementation points:

  • Cells are 16 bytes with no pointers: rune, packed fg/bg (kind<<24 | index-or-RGB), 16-bit flags, and a 16-bit index into an interned table for rare data (underline colour, OSC 8 link). Each terminal has its own table; when it fills, the entries no cell uses any more are reclaimed, so a long session making many links never runs out.
  • Grid and scrollback form one flat []Cell, allocated up front and used as a ring. Scrolling into scrollback moves an index; nothing is copied. Untouched pages never become resident.
  • Parser: a VT500-style state machine with fast paths for the bulk of real output. Runs of printable ASCII are written in one go, CSI parameters are scanned in a tight loop, and OSC/DCS payloads are copied whole. Cells are stored from the pen in one 16-byte write. Steady-state allocations are zero.
  • Reflow measures the result in a first pass, then writes only the lines that are kept straight into the new ring, so a resize allocates nothing but the new buffer.
  • Rendering: two instanced draw calls, backgrounds then glyphs. Each row builds into its own slot, rebuilt only when the row is damaged; every frame the instances actually in use are packed together, so the GPU never processes empty slots (a typical frame draws 300–4,000 instances rather than 34,000).
  • Glyphs are rasterized once with QPainter, which gives Qt's font fallback, colour emoji and shaping for ligatures. They live in an RGBA atlas per font size and screen scale, shared by every pane at that size, since all pane contexts share GL resources; a size no pane uses any more is freed.
  • Box drawing, block elements, braille, Powerline separators and DEC scan lines are drawn procedurally, so they join cleanly between cells.
  • Decorations (all underline styles, strike, overline, cursor shapes) are atlas sprites, so they need no extra draw calls.
  • Paste: with bracketed paste, any paste markers inside the text are removed (repeatedly, so removing one can't assemble another), so pasted text can never end the paste early and run as typed commands. Without it, control characters other than tab and newline are dropped.
  • Search highlights only the current match, so it costs one range check per cell however many matches there are.

Testing

make test                                             # all tests, with the race detector
make vet
go test ./...                                         # unit + golden-screen tests
DISPLAY=:99 go test ./internal/ui                     # GUI tests (splits, dragging panes, zooming, saved layouts, focus, title, toolbar, options, closing, failed starts), under Xvfb
make fuzz                                             # parser fuzzing for a minute
go test ./internal/term -bench . -run X               # parser and reflow throughput (make bench)
make guibench                                         # GUI throughput, frame costs, CPU profile (Xvfb)
CLEARMEM=1 go test ./internal/term -run ClearScrollbackMemory -v  # memory Clear Scrollback returns
STRESS=1 go test ./internal/term -run StressRandom    # random-sequence hang check
test/termite-headless -size 80x24 -script '1{enter}{wait 500}' -- vttest

Measured results

Measured on an i7-6700K under Xvfb with Mesa llvmpipe (software GL), so a real GPU should do as well or better. make bench gives the parser and reflow figures, make guibench the GUI ones:

Metric Target Measured
Keypress-to-screen latency < 10 ms 5–9 ms (includes PTY echo round trip and glFinish; measured before frame pacing, which never delays the first frame after a pause)
cat of a 100 MB file < 2 s 0.89 s in the GUI (default window); 1.1 s at 1600×1000
Frame time, 1600×1000 1.2 ms for a mostly empty screen, 3.4 ms while cat scrolls, 3.9 ms for a full screen of colour
Parser throughput 418 MB/s plain text, 167 MB/s SGR-heavy, 129 MB/s CJK/emoji, 135 MB/s cursor movement (one core)
Reflow, 200 columns × 10k lines 12.7 ms per resize
Idle CPU ~0% 0 ticks over 5 s
Memory per pane, 10k scrollback < 20 MB 15.4 MB of emulator heap (120 cols); see note
Clear Scrollback, 100k lines resident memory 191 MB → 8 MB, in 0.4 ms
Startup time < 200 ms 150–170 ms to first frame

Memory note: every pane is a QOpenGLWidget with its own GL context. Under llvmpipe each context adds ~25 MB of driver RSS on top of the emulator's 15 MB. With hardware drivers that overhead is much smaller, but I haven't measured it.

Deviations and known gaps

  • PTY reads: Linux returns at most about 4 KB per read on a PTY. The reader drains what is already buffered (poll with zero timeout) and parses in chunks of up to 128 KB, so the parser sees large chunks even though individual syscalls are kernel-limited.
  • Character widths follow glibc wcwidth, so shells and editors stay aligned. Combining marks and variation selectors attach to the previous cell, and regional-indicator pairs render as one flag. ZWJ emoji sequences and skin-tone modifiers are shown as separate cells, as in xterm.
  • Not verified here: IME composition (no input method available under Xvfb), tmux and htop (not installed), native Wayland (tested on X11/xcb only), real GPU drivers, vtebench (not installed).
  • Dropped per the spec: VT52, C1 controls, NRCS and legacy charsets other than DEC line drawing, DECDWL/DECDHL, DECCOLM, sixel/ReGIS/Tektronix, printer, answerback, blink attribute, non-UTF-8 encodings.

About

A terminal emulator written in Go.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages