Beta

garterm

GPU-Accelerated Terminal Emulator

A fast terminal emulator with GPU-accelerated rendering via wgpu. Features tabbed interface with split panes, VT100-compatible terminal emulation, 7 built-in color themes, and deep integration with gar's Lua configuration. Control running instances via gartermctl for scripting and automation.

View on GitHub Install

Features

GPU-accelerated rendering with wgpu
Tabbed interface with horizontal/vertical splits
VT100/xterm-compatible terminal emulation
7 built-in color themes (Tokyo Night, Catppuccin, etc.)
Lua + TOML configuration
Deep integration with gar window manager
IPC control via gartermctl
Declarative session management
Text selection (normal, line, block modes)
Incremental search with highlighting
10,000 line scrollback buffer
Mouse support (X10, SGR, urxvt encodings)
OSC 52 clipboard operations
Shell integration (OSC 133)
Font fallbacks with Nerd Font support
Configurable tab bar with path shortening

Quick Start Guide

Get garterm running standalone or integrated with the gar window manager.

1. Installation

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=garterm # Install via script

$ cd ~/.local/src/gardesk/garterm && cargo build --release # Or build from source

2. Running garterm

terminal

$ garterm # Start with default config

$ garterm -e /bin/zsh # Start with specific shell

$ garterm --font-size 14 # Custom font size

$ garterm --print-config # Print loaded config and exit

3. Configuration

Create a configuration file or integrate with gar:

terminal

$ mkdir -p ~/.config/garterm # Create config directory

$ $EDITOR ~/.config/garterm/config.toml # Edit TOML config (standalone)

$ $EDITOR ~/.config/gar/init.lua # Or configure via gar.terminal table

4. Control with gartermctl

terminal

$ gartermctl new-tab # Open new tab

$ gartermctl split --horizontal # Split pane horizontally

$ gartermctl next-tab # Switch to next tab

$ gartermctl send "ls -la\n" # Send text to terminal

$ gartermctl load-session webdev # Load named session

$ gartermctl --all reload # Reload config on all instances

5. Basic Navigation

Action	Keybind
New tab	Ctrl+Shift+T
Close tab	Ctrl+Shift+W
Next/prev tab	Alt+] / Alt+[
Split vertical	Ctrl+Shift+Enter
Split horizontal	Ctrl+Shift+\
Focus direction	Alt+Arrow
Search	Ctrl+Shift+F

Configuration Reference

garterm can be configured via TOML at ~/.config/garterm/config.toml or via Lua in gar's ~/.config/gar/init.lua.

Full Configuration Example

~/.config/garterm/config.toml

[general]
shell = "/bin/zsh"
shell_args = ["-l"]
working_directory = "~"
vsync = false             # true = dirty-flag rendering, false = 60fps timer
log_level = "info"

[font]
family = "JetBrains Mono"
size = 14.0
bold_family = "JetBrains Mono Bold"
italic_family = "JetBrains Mono Italic"
bold_is_bright = false
ligatures = false         # Font ligature support
letter_spacing = 0
line_spacing = 0

[window]
title = "garterm"
class = "garterm"
padding = [8, 8]
columns = 120
rows = 36
opacity = 1.0
fullscreen = false

[terminal]
scrollback_lines = 10000
scroll_lines = 3
bracketed_paste = true
clipboard_write = true
clipboard_read = false    # Security: disabled by default
close_on_exit = true
hold_on_exit = false      # Keep pane open showing exit code
term = "xterm-256color"

[colors]
preset = "tokyo-night"
# Override individual colors:
# foreground = "#c0caf5"
# background = "#1a1b26"
# cursor = "#c0caf5"

[mouse]
copy_on_select = true
middle_click_paste = true
right_click = "paste"
word_chars = "-_"
url_detection = true      # Click-to-open URLs
url_modifier = "ctrl"     # Modifier required for URL clicks

[bell]
visual = true
visual_duration_ms = 100
audio = false
# audio_command = "paplay /usr/share/sounds/bell.ogg"

[tab_bar]
height = 24
position = "top"
show_single_tab = false
max_tab_width = 200
tab_padding = 16          # Horizontal padding inside each tab
shorten_paths = true
# Tab bar colors ([r, g, b, a] floats 0.0-1.0):
# active_bg = [0.15, 0.15, 0.20, 1.0]
# inactive_bg = [0.10, 0.10, 0.14, 1.0]
# active_fg = [1.0, 1.0, 1.0, 1.0]
# inactive_fg = [0.7, 0.7, 0.7, 1.0]

Lua Configuration (with gar)

~/.config/gar/init.lua

gar.terminal = {
    shell = "/bin/zsh",
    font = {
        family = "JetBrains Mono",
        size = 14.0,
    },
    colors = {
        preset = "tokyo-night",
    },
    tab_bar = {
        height = 28,
        position = "top",
        show_single_tab = false,
        shorten_paths = true,
    },
    -- Named sessions for quick workspace setup
    sessions = {
        webdev = {
            tabs = {
                { title = "Frontend", cwd = "~/app", cmd = "npm run dev" },
                { title = "Backend", cmd = "python manage.py runserver" },
                { title = "Shell" },
            }
        },
    },
}

Configuration Priority

CLI arguments (highest priority)
Lua config (gar.terminal table)
TOML config (~/.config/garterm/config.toml)
Built-in defaults (lowest priority)

Overview

garterm is a GPU-accelerated terminal emulator designed for the gardesk X11 desktop environment. It features modern rendering with wgpu, a tabbed interface with split panes, and deep integration with gar's Lua configuration system.

Key Components

Binary	Purpose
garterm	Main terminal emulator daemon
gartermctl	Control client for IPC commands

Dependencies

wgpu - GPU-accelerated rendering
fontdue - Font rasterization
vte - VT100 terminal parsing
gartk - X11 window integration
mlua - Lua configuration support

Workspace Structure

garterm/
├── garterm/           # Main terminal emulator
│   └── src/
│       ├── app.rs         # Application logic, event loop
│       ├── config/        # Config loading (TOML + Lua)
│       ├── terminal/      # VTE parsing, grid, cursor
│       ├── render/        # GPU rendering pipeline
│       ├── ui/            # Tabs, panes, splits
│       ├── input/         # Keyboard, mouse, clipboard
│       ├── pty/           # PTY management
│       └── ipc.rs         # IPC server
├── garterm-ipc/       # Shared IPC protocol types
└── gartermctl/        # Control CLI client

Event Loop

The main loop runs at ~60fps (16ms intervals):

Poll signals and X11 file descriptors
Handle signals (SIGHUP for config reload)
Process X11 events (keyboard, mouse, resize)
Read PTY data from all panes (non-blocking)
Render dirty panes to GPU

Escape Sequences

Supported Terminal Modes

Mode	Code	Description
DECCKM	1	Application cursor keys
DECAWM	7	Auto-wrap mode
DECTCEM	25	Cursor visibility
Alt Screen	1049	Alternate screen buffer
Bracketed Paste	2004	Wrap pasted text in escape sequences

OSC Sequences

OSC	Purpose
OSC 0/2	Set window/tab title
OSC 7	Set current working directory
OSC 8	Hyperlinks
OSC 52	Clipboard operations (base64)
OSC 133	Shell integration (prompt markers)

Color Support

16 ANSI colors (normal + bright)
256-color indexed palette
24-bit true color (RGB)
SGR attributes: bold, dim, italic, underline, blink, inverse, strikethrough

Mouse Support

Mouse Modes

Mode	Code	Behavior
X10	1000	Button press only
VT200	1002	Button press/release
ButtonEvent	1002	Motion while button pressed
AnyEvent	1003	All motion events

Encoding Formats

X10 - Limited to 223 columns/rows
UTF-8 (1005) - Extended range via UTF-8
SGR (1006) - Modern format, no position limits
urxvt (1015) - Similar to UTF-8

Clipboard

garterm supports both X11 selections and OSC 52 clipboard operations.

X11 Selections

PRIMARY - Auto-populated on text selection release
CLIPBOARD - Explicit copy (Ctrl+Shift+C)

Configuration

[terminal]
clipboard_write = true   # Allow terminal to set clipboard (default)
clipboard_read = false   # Allow terminal to read clipboard (security risk)

Security: clipboard_read is disabled by default. Enabling it allows programs in the terminal to read your clipboard contents, which could expose sensitive data to malicious scripts.

Tab Management

Tab Operations

Action	Keybind	gartermctl
New tab	Ctrl+Shift+T	new-tab
Close tab	Ctrl+Shift+W	close-tab
Next tab	Alt+]	next-tab
Previous tab	Alt+[	prev-tab
Go to tab N	Alt+1-9	tab N

Tab Bar Configuration

[tab_bar]
height = 24              # Height in pixels
position = "top"         # "top" or "bottom"
show_single_tab = false  # Hide bar with only 1 tab
max_tab_width = 200      # Max tab width in pixels
shorten_paths = true     # Abbreviate long paths

Pane Splits

Each tab can contain multiple panes arranged in a binary split tree.

Split Operations

Action	Keybind	gartermctl
Split vertical	Ctrl+Shift+Enter	split
Split horizontal	Ctrl+Shift+\	split --horizontal
Close pane	Ctrl+Shift+X	close-pane
Focus direction	Alt+Arrow	focus {dir}
Resize pane	Ctrl+Shift+Alt+Arrow	resize {dir}

Text Selection

Selection Modes

Mode	Trigger	Behavior
Normal	Click + drag	Character-by-character, respects wrapping
Word	Double-click	Select word (configurable word_chars)
Line	Triple-click	Select entire line
Block	Ctrl+Click	Rectangular selection

Copy/Paste

Release selection - Copies to PRIMARY
Ctrl+Shift+C - Copy to CLIPBOARD
Ctrl+Shift+V - Paste from CLIPBOARD
Middle-click - Paste from PRIMARY

Search

Search Controls

Action	Keybind
Start search	Ctrl+Shift+F
Next match	Ctrl+N or Enter
Previous match	Shift+N
Toggle case sensitivity	Ctrl+I
Cancel search	Escape

Search results are highlighted with match count displayed (e.g., "3/15"). Searches include both visible content and scrollback buffer.

Scrollback

Scrollback Controls

Action	Keybind
Scroll up	Shift+PageUp or Mouse wheel
Scroll down	Shift+PageDown or Mouse wheel
Scroll to top	Shift+Home
Scroll to bottom	Shift+End

Configuration

[terminal]
scrollback_lines = 10000  # Max history (default: 10,000)
scroll_lines = 3          # Lines per wheel tick (default: 3)

Color Themes

garterm includes 7 built-in color themes. Set via colors.preset:

tokyo_night (default)

catppuccin

gruvbox

dracula

nord

solarized

one_dark

Custom Color Overrides

[colors]
preset = "tokyo-night"
# Override specific colors:
foreground = "#ffffff"
background = "#000000"
cursor = "#ff0000"
red = "#ff6666"

gar Integration

garterm integrates deeply with the gar window manager via shared Lua configuration.

Spawning from gar

~/.config/gar/init.lua

-- Set garterm as default terminal
gar.set("spawns", {
    terminal = "garterm"
})

-- Keybind to spawn terminal
gar.bind("Super+Return", function()
    gar.spawn("terminal")
end)

Shared Configuration

When garterm starts, it reads the gar.terminal table from gar's init.lua:

gar.terminal = {
    shell = "/bin/zsh",
    font = { family = "JetBrains Mono", size = 14 },
    colors = { preset = "tokyo-night" },
    window = { padding = {12, 12} },
    tab_bar = { position = "bottom" },
}

Lua Callbacks

Define keybinds that call Lua functions:

gar.terminal.keybinds = {
    ["alt+e"] = function()
        gar.terminal.split({ direction = "vertical" })
        gar.terminal.send_text(nil, "nvim .\n")
    end,
}

Sessions

Define named sessions for quick workspace setup.

Defining Sessions

~/.config/gar/init.lua

gar.terminal.sessions = {
    webdev = {
        tabs = {
            { title = "Frontend", cwd = "~/app/frontend", cmd = "npm run dev" },
            { title = "Backend", cwd = "~/app/backend", cmd = "cargo watch -x run" },
            { title = "Database", cmd = "docker compose up db" },
            { title = "Shell" },
        }
    },
    dotfiles = {
        tabs = {
            { title = "Config", cwd = "~/.config", cmd = "nvim ." },
        }
    },
}

Loading Sessions

terminal

$ gartermctl load-session webdev # Load webdev session

Sessions use OSC 133 shell integration to detect when the shell is ready before sending startup commands. This ensures commands run after shell initialization is complete.

Keybindings Reference

Tab Management

Keybind	Action
Ctrl+Shift+T	New tab
Ctrl+Shift+W	Close tab
Alt+]	Next tab
Alt+[	Previous tab
Alt+1-9	Switch to tab N

Pane Management

Keybind	Action
Ctrl+Shift+Enter	Split vertical (top/bottom)
Ctrl+Shift+\	Split horizontal (left/right)
Ctrl+Shift+X	Close pane
Alt+Up/Down/Left/Right	Focus pane in direction
Ctrl+Shift+Alt+Arrow	Resize pane in direction

Clipboard & Selection

Keybind	Action
Ctrl+Shift+C	Copy selection to CLIPBOARD
Ctrl+Shift+V	Paste from CLIPBOARD
Shift+Insert	Paste from CLIPBOARD
Middle-click	Paste from PRIMARY

Search & Scrollback

Keybind	Action
Ctrl+Shift+F	Start search
Shift+PageUp	Scroll page up
Shift+PageDown	Scroll page down
Shift+Home	Scroll to top
Shift+End	Scroll to bottom

Other

Keybind	Action
Ctrl+Shift+Plus	Increase font size
Ctrl+Minus	Decrease font size
Ctrl+0	Reset font size
F11	Toggle fullscreen

IPC Protocol

garterm exposes a Unix socket for IPC. Control running instances with gartermctl.

Socket Location

Each garterm window creates its own socket:

$XDG_RUNTIME_DIR/garterm/garterm-{PID}.sock
Focus tracking: $XDG_RUNTIME_DIR/garterm/focused

gartermctl Commands

Command	Description
list	Show all running instances
new-tab [--cwd dir] [--exec cmd]	Create new tab
close-tab	Close current tab
next-tab / prev-tab	Navigate tabs
tab N	Switch to tab N (1-indexed)
split [--horizontal]	Split current pane
close-pane	Close current pane
focus {up\|down\|left\|right}	Move focus to adjacent pane
send "text"	Send text to focused pane
load-session name	Load named session
info	Get tab count and dimensions
reload	Reload configuration
quit	Exit garterm

Targeting Options

terminal

$ gartermctl new-tab # Target last focused window (default)

$ gartermctl -w 12345 new-tab # Target specific PID

$ gartermctl -a send "hello" # Broadcast to all instances

JSON Protocol

Commands are JSON objects sent over the socket:

// Request
{"NewTab": {"cwd": "~", "startup_cmd": "nvim", "title": "Editor"}}

// Response
{"success": true, "message": null, "data": {"tab_id": 3}}

Troubleshooting

GPU rendering issues

If garterm crashes or shows rendering artifacts:

terminal

$ WGPU_BACKEND=vulkan garterm # Force Vulkan backend

$ WGPU_BACKEND=gl garterm # Force OpenGL backend

On Asahi Linux, set vsync = false in config.

Font not found

Check available fonts and font paths:

terminal

$ fc-list | grep -i "jetbrains" # Check if font is installed

$ fc-match monospace # Check default monospace

gartermctl can't connect

Check socket files:

terminal

$ ls $XDG_RUNTIME_DIR/garterm/ # List garterm sockets

$ cat $XDG_RUNTIME_DIR/garterm/focused # Check focused PID

$ gartermctl list # List running instances

Sessions not working

Startup commands may fail if shell doesn't support OSC 133. Add to your shell config:

~/.zshrc or ~/.bashrc

# OSC 133 shell integration
precmd() { printf '\e]133;A\a'; }
preexec() { printf '\e]133;B\a'; }

Debug logging

Enable verbose logging:

terminal

$ RUST_LOG=debug garterm # Debug logging

$ RUST_LOG=garterm=trace garterm # Trace-level logging

$ tail -f /tmp/garterm.log # View log file

Config not loading

Check config locations and syntax:

terminal

$ cat ~/.config/garterm/config.toml # Check TOML config

$ lua -e "dofile(os.getenv('HOME')..'/.config/gar/init.lua')" # Validate Lua syntax

Back to home

garterm

Features

Quick Start Guide

1. Installation

2. Running garterm

3. Configuration

4. Control with gartermctl

5. Basic Navigation

Configuration Reference

Full Configuration Example

Lua Configuration (with gar)

Configuration Priority

Overview

Key Components

Dependencies

Architecture

Workspace Structure

Event Loop

GPU Rendering

Rendering Pipeline

Font Handling

VSync Mode

Terminal Emulation

Escape Sequences

Supported Terminal Modes

OSC Sequences

Color Support

Mouse Support

Mouse Modes

Encoding Formats

Clipboard

X11 Selections

Configuration

UI Features

Tab Management

Tab Operations

Tab Bar Configuration

Pane Splits

Split Operations

Text Selection

Selection Modes

Copy/Paste

Search

Search Controls

Scrollback

Scrollback Controls

Configuration

Color Themes

Custom Color Overrides

gar Integration

Spawning from gar

Shared Configuration

Lua Callbacks

Sessions

Defining Sessions

Loading Sessions

Keybindings Reference

Tab Management

Pane Management

Clipboard & Selection

Search & Scrollback

Other

IPC Protocol

Socket Location

gartermctl Commands

Targeting Options

JSON Protocol

Troubleshooting

GPU rendering issues

Font not found

gartermctl can't connect

Sessions not working

Debug logging

Config not loading