garterm

Overview

garterm is a GPU-accelerated terminal emulator designed for the gardesk ecosystem. It provides modern features like tabs, BSP-tree splits, Lua scripting, and IPC control while maintaining high performance through wgpu-based rendering with glyph atlas caching.

The terminal uses the VTE crate for ANSI/CSI escape sequence parsing, supporting full xterm-256color compatibility including mouse modes, alternate screen buffer, OSC sequences (title, hyperlinks, clipboard), and bracketed paste.

Architecture

garterm consists of several interconnected components working together to provide a responsive terminal experience.

Application Layer

The main event loop integrates window management (X11 via gartk), event polling (keyboard, mouse, X11 events), IPC server for remote control, and the Lua runtime for scripting. Events flow through keybind lookup to actions that modify terminal state.

X11 Event → App.run()
    ↓
Keyboard/Mouse Handler → Keybind Lookup → Action
    ↓
Terminal State Update → Dirty Flag → Render
    ↓
GPU Render (grid → glyphs → framebuffer)
    ↓
X11 Present

GPU Rendering

garterm uses wgpu for cross-platform GPU abstraction, preferring Vulkan for higher texture limits (avoiding GL's 2048 texture limit) with OpenGL fallback. X11 integration uses Xlib handles for surface creation.

Rendering pipeline:

1. Font rasterization via fontdue → glyph bitmaps
2. Atlas management packs glyphs into GPU texture
3. Vertex submission builds quads (position, UV, color)
4. WGPU render pass submits to GPU
5. X11 surface presents to display

Rendering modes: VSync mode only redraws on changes (low CPU). Continuous 60fps timer mode (default) redraws every frame, required on Asahi Linux where VSync may not work correctly.

VTE Parser

The terminal uses the vte crate for escape sequence parsing, supporting:

• CSI sequences (cursor movement, colors, modes)
• OSC sequences (title, hyperlinks, clipboard via OSC 52, working directory)
• SGR (Select Graphic Rendition) for text attributes
• Alternate screen buffer for fullscreen applications
• Mouse mode reporting (normal, button, motion)
• Application cursor/keypad modes
• Bracketed paste mode

Font Rendering

Font rendering uses the fontdue library for glyph rasterization. garterm loads system fonts with fallback chain: specified family → JetBrains Mono → DejaVu Sans Mono.

Separate font variants (Regular, Bold, Italic, BoldItalic) can be configured. Cell metrics are calculated per font to ensure proper grid alignment. Fallback fonts handle symbols, box drawing characters, and Nerd Font glyphs.

Tabs

Each tab contains an independent split tree layout. Tabs maintain their own state including working directory, terminal mode, and scroll position.

• Alt+T - Create new tab
• Alt+W - Close current tab/pane
• Alt+] / Alt+[ - Next/previous tab
• Alt+1-9 - Jump to tab by number

Split Panes

Panes use a BSP (Binary Space Partition) tree structure allowing arbitrary layouts. Each pane has its own PTY terminal with independent state.

• Alt+H - Split horizontally (side-by-side)
• Alt+V - Split vertically (stacked)
• Alt+Up/Down/Left/Right - Focus pane direction
• Ctrl+Shift+Alt+Arrow - Resize pane (5px per press)

Tab Bar

The tab bar shows all open tabs with configurable position (top/bottom), height, and colors. Tabs show the current working directory with optional path shortening (~/P/r/src instead of full path).

Tab width is flexible up to max_tab_width, shrinking proportionally when many tabs are open. The tab bar can be hidden when only one tab is open.

Scrollback

garterm maintains a scrollback buffer (default 10,000 lines) for terminal history.

• Shift+PageUp/PageDown - Scroll by page
• Ctrl+Shift+Home - Jump to top
• Ctrl+Shift+End - Jump to bottom
• Ctrl+Shift+K - Clear scrollback
• Mouse wheel scrolls by scroll_lines (default 3)

Clipboard

garterm supports both PRIMARY (selection) and CLIPBOARD (Ctrl+C/V) X11 clipboards.

• Ctrl+Shift+C - Copy selection to CLIPBOARD
• Ctrl+Shift+V - Paste from CLIPBOARD
• copy_on_select - Auto-copy selection to PRIMARY
• middle_click_paste - Paste PRIMARY on middle click
• OSC 52 support allows programs to write clipboard (clipboard_write: true)

URL Detection

When url_detection is enabled (default), garterm detects http(s)://, ftp://, and file:// URLs in terminal output. URLs become clickable with the configured modifier key (default: Ctrl).

Clicking opens the URL with xdg-open.

Search

Press Ctrl+Shift+F to enter search mode. Type to search scrollback history.

• N - Next match
• Shift+N - Previous match
• Ctrl+I - Toggle case sensitivity
• Escape - Exit search

Bell

The terminal bell can be configured for visual flash (visual: true), audio command (audio_command), or both. Visual bell briefly inverts colors for the configured duration.

Lua Scripting

garterm integrates with gar's Lua configuration system, allowing advanced customization including function keybinds and named sessions.

Lua Configuration

Configure garterm in ~/.config/gar/init.lua:

gar.terminal = {
    shell = "/bin/zsh",
    vsync = false,

    font = {
        family = "JetBrains Mono",
        size = 12.0,
        bold_is_bright = false,
    },

    window = {
        title = "garterm",
        padding = { 0, 0 },
        opacity = 0.95,
    },

    colors = {
        preset = "catppuccin-mocha",
    },

    mouse = {
        copy_on_select = true,
        url_detection = true,
        url_modifier = "ctrl",
    },

    tab_bar = {
        height = 28,
        position = "top",
        show_single_tab = false,
    },
}

Sessions

Define named sessions with predefined tab layouts, commands, and working directories:

gar.terminal.sessions = {
    webdev = {
        tabs = {
            {
                title = "Frontend",
                cwd = "~/Projects/frontend",
                cmd = "npm run dev",
                splits = {
                    { direction = "horizontal", cmd = "npm test" },
                }
            },
            {
                title = "Backend",
                cwd = "~/Projects/backend",
                cmd = "python -m flask run"
            },
            {
                title = "Editor",
                cwd = "~/Projects",
                cmd = "nvim ."
            },
        }
    }
}

Load sessions with gartermctl load-session webdev or bind to a key: "alt+w" = "load_session:webdev"

Terminal API

Lua keybinds can call terminal API functions for advanced automation:

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

    ["ctrl+alt+n"] = { action = "new_tab" },

    ["alt+s"] = { action = "load_session", session = "webdev" },
}

-- Available API functions:
-- gar.terminal.new_tab({ cwd, cmd, title })
-- gar.terminal.split({ direction, cwd, cmd })
-- gar.terminal.send_text(pane_id, text)
-- gar.terminal.close_tab(tab_id)
-- gar.terminal.close_pane(pane_id)
-- gar.terminal.focus_tab(index)
-- gar.terminal.focus_direction(dir)
-- gar.terminal.next_tab()
-- gar.terminal.prev_tab()
-- gar.terminal.load_session(name)

Color Schemes

garterm includes several built-in color presets:

Custom Colors

Override individual colors on top of any preset:

[colors]
preset = "tokyo-night"

# Override specific colors (hex format)
foreground = "#c0caf5"
background = "#1a1b26"
cursor = "#c0caf5"
selection = "#33467c"

# ANSI 0-7 (normal)
black = "#15161e"
red = "#f7768e"
green = "#9ece6a"
yellow = "#e0af68"
blue = "#7aa2f7"
magenta = "#bb9af7"
cyan = "#7dcfff"
white = "#a9b1d6"

# ANSI 8-15 (bright)
bright_black = "#414868"
bright_red = "#f7768e"
# ... etc