tergo

README

TERGO - Terminal UI Operating System

tergo is a fork of tuios by Gaurav Gosain, used under the MIT License. It is an independent project and is not affiliated with or endorsed by upstream. See NOTICE for attribution details.

TERGO is a modern terminal multiplexer and window manager built with Go. It provides a vim-like modal interface with multiple terminal panes, workspaces, BSP tiling, kitty graphics protocol support, and a command palette - all running inside your existing terminal.

Built on the Charm stack (Bubble Tea v2, Lipgloss v2), TERGO features event-driven rendering for near-zero idle CPU usage, flicker-free kitty image passthrough, and comprehensive keyboard/mouse interaction.

Documentation

Full documentation is in the docs/ folder.

Quick Links

• Getting Started - Keybindings and quick reference
• BSP Tiling - Tiling with preselection and split control
• Layout Modes - BSP, master-stack and scrolling layouts, aggregate view, multifocus
• Configuration - Customize keybindings, themes, and behavior
• Hooks - Run shell commands on window and session events
• Themes - Built-in themes and custom theme JSON
• CLI Reference - All command-line options
• Tape Scripting - Automate workflows
• Sessions - Daemon mode, attach/detach, and what survives
• Multi-Client - Several clients on one session
• Control Protocol - JSON verb protocol for driving the daemon
• Architecture - Technical design

Table of Contents

• Installation
• Features
• Quick Start
• What's New in v0.7.0
• Architecture
• Performance
• Development
• License

Installation

Package Managers

Homebrew (macOS/Linux):

brew install tergo

Arch Linux (AUR):

yay -S tergo-bin

Nix:

nix run github:SidahmedSeg/tergo#tergo

Other Methods

# Quick install script (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/SidahmedSeg/tergo/main/install.sh | bash

# Go install
go install github.com/SidahmedSeg/tergo/cmd/tergo@latest

# Docker
docker run -it --rm ghcr.io/sidahmedseg/tergo:latest

GitHub Releases - Pre-built binaries for all platforms.

Requirements: A terminal with true color support. Kitty graphics and sixel support recommended (Ghostty, Kitty, WezTerm).

Features

Core

• Multiple Terminal Panes - Create, resize, drag, and organize terminal sessions
• 9 Workspaces - Independent workspace isolation with instant switching
• Modal Interface - Vim-inspired Window Management and Terminal modes
• Command Palette - Fuzzy-searchable action launcher (Ctrl+P)
• Pane Zoom - Fullscreen any pane with z (WM mode) or Prefix+z. Shared borders hidden when zoomed, dockbar shows Z indicator.

Tiling

• BSP Tiling - Binary Space Partitioning with spiral layout
• Scrolling Layout - niri-style columns on an infinite horizontal strip (docs)
• Master-Stack Layout - One master pane with the rest stacked beside it
• Smart Auto-Split - Aspect-ratio-aware splitting (opt-in)
• Shared Borders - tmux-style separator lines between panes (--shared-borders)
• Preselection - Control where the next pane spawns
• Equalize Splits - Reset all splits to balanced ratios

Scrollback & Copy Mode

• Vim-Style Copy Mode - Navigate 10,000-line scrollback with hjkl, search with /, yank with y
• Mouse Wheel Scrollback - Scroll wheel enters copy mode directly (no alt-screen)
• Interactive Scrollbar - Click or drag the right border to jump to scroll position
• Selection Auto-Scroll - Drag selection above/below pane to scroll
• Scrollback Browser - OSC 133-aware command/output block navigation
• Scroll Position Indicator - Shows offset/total on the bottom border

Graphics & Protocols

• Kitty Graphics Protocol - Full image rendering with flicker-free video playback. mpv --vo=kitty works (both shm and base64), and youterm works.
• Sixel Graphics - Sixel image passthrough (experimental, no pixel-level clipping yet)
• Kitty Keyboard Protocol - Progressive enhancement (CSI u) with push/pop/query support. Fish 4.x compatible; Shift+printable bypasses the protocol and sends text directly.
• Synchronized Output - Mode 2026 prevents screen tearing
• Shared Memory Support - t=s passthrough for mpv --vo-kitty-use-shm
• Terminal Queries - OSC 4 palette, OSC 10-12 colors, CSI 14/16/18t sizing, DA1/DA2
• Experimental - Kitty text sizing protocol (OSC 66) - basic passthrough works but has known issues with scrollback and window repositioning
• Not Yet Supported - Kitty animation protocol (a=f, a=a, a=c)

Session Management

• Daemon Mode - Persistent sessions with detach/reattach (like tmux)
• Session Resurrection - Sessions come back after a daemon restart or reboot with their structure and working directories (docs)
• Session Switcher - In-app session list (Prefix+S)
• Layout Templates - Save/load window arrangements with working directories and startup commands
• Layout CLI - tergo layout list, tergo layout delete, tergo layout export

Automation

• Tape Scripting - DSL for recording and replaying terminal workflows
• Tape Recording - Record live sessions (Prefix+T r)
• Headless Execution - Run scripts in CI/CD with tergo tape run
• Layout Export - Convert layouts to tape scripts for sharing

Discovery & Navigation

• Which-Key Popup - Hold the prefix key to see the chords available (docs)
• Aggregate View - Searchable list of every window across every workspace, with previews (docs)
• Multifocus - Broadcast typing to several panes at once, Ctrl+click to select (docs)

More

• Showkeys Overlay - Display pressed keys for presentations
• Customizable Keybindings - TOML configuration with Kitty protocol support
• Hooks - Run shell commands on window create, close and focus events (docs)
• Mouse Support - Wheel scrollback, drag-to-select with copy on release, double-click word and triple-click line, window drag, resize, scrollbar
• SSH Server Mode - Remote terminal multiplexing
• Web Terminal Mode - Browser-based access (separate tergo-web binary)
• Themes - Bundled themes plus custom themes from JSON (docs)

Quick Start

tergo                    # Launch TERGO
tergo --show-keys        # Launch with key overlay for learning

Essential Keys

Key	Action
Ctrl+P	Command palette - search and run any action
n	New pane (Window Management mode)
i / Enter	Enter Terminal mode
Prefix+Esc or Alt+Esc	Back to Window Management mode (a bare Esc goes to the shell)
Prefix+d	Detach in a daemon session, otherwise back to Window Management mode
z (WM) or Prefix+z	Toggle pane zoom (fullscreen)
Prefix+Space	Toggle BSP tiling
Prefix+[	Enter copy mode (vim scrollback)
Prefix+S	Session switcher
Prefix+L then l/s	Load/Save layout template
Prefix+?	Help overlay
Prefix+q	Quit

The prefix key is Ctrl+B by default (configurable).

Daemon Mode

tergo new mysession          # Create persistent session
tergo attach mysession       # Reattach
tergo ls                     # List sessions
tergo kill-session mysession # Kill session

Layout Templates

# In-app: Ctrl+B, L, l to load / Ctrl+B, L, s to save
# Or via command palette: Ctrl+P → "Save Layout" / "Load Layout"

# CLI:
tergo layout list            # List saved layouts
tergo layout delete mysetup  # Delete a layout
tergo layout export mysetup  # Export as tape script

Configuration

tergo config edit            # Edit config in $EDITOR
tergo keybinds list          # View all keybindings

See Configuration Guide for all options including show_clock, show_cpu, show_ram, shared_borders, custom themes, and keybinding customization.

What's New in v0.7.0

Architecture Overhaul

• Event-driven rendering - PTY output signals trigger renders instead of fixed-rate ticking. Near-zero CPU at idle.
• Graphics batched with render cycle - Kitty commands flush after text content, preventing tearing.

Performance

• Kitty graphics flicker elimination - Reuses image IDs so frames replace in-place without delete+re-place.
• Raw passthrough - File-based kitty transmissions forward the path directly (no read+encode+chunk).
• Fast render path - Unfocused panes use the emulator's built-in Render() bypassing cell-by-cell iteration.
• Hot path cleanup - Removed defer/recover from style comparison (~20k calls/frame), fixed string builder leak.
• Visibility gating - Minimized/off-workspace panes skip rendering entirely.
• Synchronized output - Mode 2026 wrapping for all graphics output.

New Features

• Command palette (Ctrl+P) - Fuzzy search across 30+ actions with ranked results.
• Pane zoom (z in WM mode or Prefix+z) - Fullscreen toggle for the focused pane. Shared borders hidden when zoomed, dockbar shows Z indicator.
• Session switcher (Prefix+S) - Browse and switch daemon sessions in-app.
• Layout templates - Save/load window arrangements with CWD, startup commands, BSP tree, proportional scaling.
• Shared borders (--shared-borders) - tmux-style thin separator lines between tiled panes.
• Smart auto-split - Aspect-ratio-aware BSP splitting (opt-in via command palette).
• Interactive scrollbar - Click/drag the right border to scroll, theme-aware colors.
• Mouse wheel scrollback - The wheel scrolls, with no mode entered and nothing announced. Typing or reaching the bottom returns to live output.
• Selection auto-scroll - Drag selection above/below pane to scroll during visual mode.
• Dock stats opt-in - Clock, CPU, RAM hidden by default (--show-clock, --show-cpu, --show-ram).

Terminal Protocol Support

• Kitty keyboard protocol - Full CSI u support: push (CSI > u), pop (CSI < u), query (CSI ? u), set (CSI = u). Keys encoded in CSI u format when the protocol is active.
• Mode 2026 (synchronized output) and mode 2027 (unicode core) tracked in the VT emulator.
• OSC 4 palette color query/set, OSC 52 clipboard operations.
• DA1 now advertises sixel capability (attribute 4).
• Sixel passthrough re-enabled with raw data passthrough and active area clearing on hide (experimental).

Bug Fixes

• Images follow windows during drag and reposition on resize.
• ctrl+d window close no longer requires double-press (race condition fix).
• Visual line mode (Shift+V) highlights immediately.
• Off-screen windows don't corrupt ANSI rendering.
• Background windows stay fresh (no stale content on focus switch).
• Tiling toggle immediately shows/hides borders.
• Sixel images hidden during overlays and copy mode scrollback.

Dependencies

• Bubble Tea v2.0.2, Lipgloss v2.0.2, Wish v2.0.0, Log v2.0.0 (all stable releases).

Architecture

TERGO follows the Model-View-Update pattern on Bubble Tea v2. For details, see Architecture Guide.

Key design decisions:

• Event-driven rendering - PTY reader goroutines signal bubbletea via a buffered channel. No fixed-rate ticking for terminal content.
• Kitty graphics passthrough - Image IDs are reused across frames for flicker-free video. Output is batched with the render cycle and wrapped in mode 2026 sync.
• BSP tiling - Binary space partitioning tree with configurable schemes (spiral, smart split). Shared borders mode overlaps window rects and draws separator lines as a separate layer.
• Copy mode - Full vim navigation over scrollback. Wheel scrolling and mouse selection borrow the same machinery through an implicit session that presents as nothing at all, plus scrollbar interaction and selection auto-scroll (timer-based continuous drag scrolling).

Core Components:

• Window Manager (internal/app/os.go) - Central state, workspaces, overlays
• Terminal Emulation (internal/vt/) - ANSI parser with scrollback, kitty/sixel graphics, kitty keyboard protocol, OSC 133
• Rendering (internal/app/render.go) - Layer composition, viewport culling, graphics batching
• Input (internal/input/) - Modal routing, 100+ configurable keybindings, mouse handling
• Kitty Passthrough (internal/app/kitty_passthrough.go) - Flicker-free image forwarding with ID reuse and sync output

Performance

• Event-driven rendering - Zero CPU at idle. Renders only when PTY data arrives or interaction occurs.
• Kitty graphics - Flicker-free via image ID reuse. Tearing-free via mode 2026 sync + render cycle batching.
• Fast unfocused render - Unfocused panes use emulator's built-in Render() instead of cell-by-cell.
• Style caching - LRU cache with sequence-based change detection (40-60% allocation reduction).
• Viewport culling - Off-screen and minimized panes skip rendering.
• Memory pooling - Pooled strings, buffers, and styles.

Development

git clone https://github.com/SidahmedSeg/tergo.git
cd tergo
go build -o tergo ./cmd/tergo
./tergo

go test ./...              # Run tests
go vet ./...               # Lint
staticcheck ./...          # Static analysis

Support:

Star History

License

MIT License - see LICENSE for details.

Acknowledgments

• The Charm team for Bubble Tea, Lipgloss, and the Go terminal ecosystem
• The vim, tmux, and i3 communities for interface design inspiration
• Ghostty, Kitty, and WezTerm for excellent terminal emulators with graphics support