Architecture

TUIOS is a Go program built on Bubble Tea v2 and its Model-View-Update pattern. The code lives under internal/, with the binaries in cmd/ and the embeddable packages in pkg/. This page is a map for reading the code.

Tech stack

• Bubble Tea v2 (charm.land/bubbletea/v2): the event loop and program model
• Lipgloss v2 (charm.land/lipgloss/v2): styling and layer composition
• Ultraviolet: cell and screen types used by the emulator and the compositor
• Wish v2 (charm.land/wish/v2): the SSH server
• x/xpty: cross-platform PTYs (ConPTY on Windows)
• Cobra with fang: the CLI, its help and its errors
• bubbletint: the built-in theme palettes
• sip: the browser transport behind tuios-web
• libghostty-vt (go.mitchellh.com/libghostty): an optional emulator backend, built with -tags ghostty

Package map

Client and daemon

By default TUIOS runs as a daemon that owns sessions, plus one or more clients that attach to it over a Unix socket.

Where to look in internal/session:

• daemon.go, daemon_handlers.go: the accept loop and per-message handling. manager.go owns the session table.
• protocol.go, codec.go: length-prefixed frames with gob payloads, the binary protocol the client speaks.
• verb_protocol.go, verb_handlers.go, verb_subscribe.go and the other verb_*.go files: the JSON control protocol. The daemon tells a JSON client from a binary one by its first byte.
• daemon_stream.go: the output stream clients subscribe to, so a client draws without owning a PTY.
• state_merge.go: reconciles client and daemon state, which is how several clients on one session converge.
• tuiclient.go, client.go: the attach side.
• resurrection.go: saving session structure to disk and restoring it.

Because the daemon owns the PTYs and the emulators, detaching a client stops nothing. Sessions covers the user-facing behaviour.

Core components

Window manager (internal/app)

The OS struct in os.go is the model. It holds the windows, the nine workspaces, the focus, the input mode, the tiling state, overlays and mouse interaction state. Layout code is in os_layout.go, tiling.go, tiling_bsp.go, tiling_resize.go and tiling_swap.go.

Terminal emulation (internal/vt)

The emulator sits behind the vt.Terminal interface, and exactly one implementation is compiled into a binary:

• Pure Go (default). No cgo, so go install and cross-compilation just work.
• libghostty-vt (-tags ghostty). Ghostty's VT library through its Go bindings. It needs cgo, and scripts/install.sh builds the library with zig.

A differential test suite feeds the same bytes to both and compares screens, cursor, scrollback, modes and wire snapshots. tuios --version names the backend a binary was built with.

The emulator handles CSI, OSC, ESC and DCS sequences, the alternate screen, scrollback (10,000 lines by default, appearance.scrollback_lines), cursor shapes, the kitty keyboard protocol, synchronized output (mode 2026), unicode width (mode 2027), colour scheme reports (mode 2031), OSC 4, 10 to 12 and 52, OSC 133 shell integration zones, and cell size reports (CSI 14t, 16t, 18t).

Rendering (internal/app/os_render.go, render_*.go)

The view is a stack of layers: window contents and borders, then overlays (help, palette, settings, pickers, the scrollback browser), then the dock and the sidebar. Overlays are z-ordered and can be dragged; hit testing is in overlay_hit.go and overlay_mouse.go.

Input (internal/input)

Keys are routed by mode:

• Window management mode: arrange windows
• Terminal mode: keys go to the focused window's PTY
• Copy mode: vim-style navigation over scrollback (copymode_*.go)
• Prefix mode: the tmux-style leader key and its sub-menus (prefix_routing.go, prefix_actions.go)

Every binding goes through the keybinding registry in internal/config, so every key can be rebound.

Configuration (internal/config)

The TOML config file, its defaults, an option registry that the settings page, list-options and set-option all read, platform defaults (the macOS Option key), validation, migration of old keys, and live reload when the file changes.

Graphics

TUIOS passes images from programs in its windows through to the host terminal. It supports the Kitty graphics protocol and sixel.

Kitty graphics (internal/app/kitty_*.go):

• Image data is forwarded without re-encoding.
• Image IDs are reused across frames, so video does not flicker. mpv --vo=kitty and youterm work.
• Shared memory (t=s) and file path (t=f) transmission are forwarded when the host terminal supports them.
• Placements follow the window as it moves and scrolls, and are cropped to the part another window does not cover.
• Unicode placeholders are drawn when the host terminal is known to support them.
• Animation frames (a=f, a=a, a=c) are forwarded, and animated programs are sent as changed rectangles rather than whole images.
• Output is wrapped in synchronized output (mode 2026).

Sixel (internal/app/sixel_passthrough.go) is passed through as is. An image that does not fit inside its window is hidden, because pixel-level clipping is not implemented.

TUIOS asks the host terminal what it supports at startup instead of guessing, and waits up to 300 ms for the answer. It then gives programs the real answer: a program that asks whether it may send a file path is told no when the host cannot read files, and falls back to sending bytes. If no answer arrives in time (for example when TUIOS runs inside another multiplexer that swallows the query), graphics forwarding is turned off and programs are told so.

Host terminals known to work include Kitty, Ghostty, WezTerm, Foot, Contour and iTerm2 (partly). Support is detected, not looked up, so an unlisted terminal works if it answers the probe. The browser client supports a smaller set; see Web Terminal.

These environment variables override detection. Set each to 1 or 0:

Performance

Rendering is event-driven. PTY output wakes the model through a PTYDataMsg; there is no fixed-rate loop for terminal content. A separate maintenance tick drives animations, the which-key panel, dock stats and tape playback, and it stops doing work when nothing needs it. An idle session costs close to no CPU.

• appearance.max_fps caps the frame rate. It defaults to 60 and is clamped to 10 to 120, the ceiling Bubble Tea itself enforces. The settings page offers 30, 60, 90, 120 and unlimited, which means 120.
• Each window paces its redraws by what a frame actually costs, at most one every 8 ms. A window more than 4 MiB behind on output drops to a catch-up rate, so a flooding window cannot starve input.
• Windows that are off screen or minimized are not rendered.
• internal/app/stylecache.go caches cell styles and their ANSI escapes, keyed by a hash of colours and attributes. It holds 512 entries and drops about half when full. Ctrl+B D c shows its hit rate.
• internal/pool reuses byte buffers and highlight grids on the render path.

The benchmarks are in internal/app/*_bench_test.go. The repository's docs/perf.md records measured baselines.

SSH server

tuios ssh (internal/server/ssh.go) serves TUIOS over SSH with Wish.

• Sessions. By default each connection attaches to a daemon session, so sessions persist and several people can share one. With --ephemeral, each connection gets its own standalone session.
• Authentication. Public keys from ~/.config/tuios/authorized_keys, or ~/.ssh/authorized_keys if that is absent. With no keys configured, the server accepts every connection on localhost and refuses to start on any other address unless you pass --no-auth.
• Host key. Generated on first run, or given with --key-path.

tuios ssh --host 0.0.0.0 --port 2222
ssh -p 2222 work@server   # the user name picks the session

Tape scripting

internal/tape turns a tape file into actions: lexer.go tokenizes it (keywords are case-insensitive), parser.go builds commands, executor.go dispatches them and player.go plays them with timing. recorder.go records live actions back into a tape. See Tape Scripting.

Themes

342 themes are built in, from bubbletint. tuios import-theme converts a kitty, ghostty, alacritty or wezterm colour scheme into a TUIOS theme, and the themes directory is re-read every time themes are listed, so an imported theme is usable without a restart.

A theme sets the 16 ANSI colours and the default foreground and cursor. The 256-colour indices above 15 and truecolor pass through unchanged, and the default background stays transparent so programs keep their own backgrounds.

Development patterns

Model-View-Update

• Model: app.OS holds all state.
• View: os_render.go and the render_*.go files produce the frame.
• Update: update.go handles messages: tea.KeyPressMsg, the mouse messages (tea.MouseClickMsg, tea.MouseMotionMsg and others), tea.WindowSizeMsg, PTYDataMsg, and messages from the daemon such as clients joining or leaving.

Message flow

Window lifecycle

1. Create: internal/ptyspawn starts the shell on a new PTY, with the environment from internal/guestenv.
2. Read: a goroutine reads the PTY and feeds the emulator.
3. Render: new output marks the window dirty and a frame is drawn.
4. Close: when the process exits or the window is closed, the PTY is closed, resources are freed and hooks fire.

Testing

go test ./...                 # everything
go test -race ./...           # with the race detector
go test ./internal/vt/        # the emulator's conformance corpus and fuzz seeds
cd e2e/tui && go test ./...   # the end-to-end TUI suite, a separate module

The tests cover config validation and migration, tape parsing and execution, emulator conformance, the daemon protocol, state merging, resurrection and the verbs, and full TUI runs in a real PTY using the fake shell in internal/testutil. The repository's AGENTS.md describes the differential tests against tmux and the ghostty backend.

Building from source

git clone https://github.com/Gaurav-Gosain/tuios.git
cd tuios
go build -o tuios ./cmd/tuios
./tuios

You need Go 1.26 or newer. The default build needs no C compiler. A Nerd Font is needed for icons, or run with --ascii-only.

Platform-specific code

Contributing

See Contributing.

Related