# TUIOS

> TUIOS is a terminal window manager with vim-style keys, tiling, nine workspaces, and sessions that keep running when you detach.

TUIOS is written in Go and MIT licensed. Source: https://github.com/Gaurav-Gosain/tuios

## Docs

- [Introduction](https://tuios.gaurav.zip/docs.md): TUIOS is a terminal multiplexer and window manager with workspaces, tiling, persistent sessions and a vim-style modal interface.
- [Getting Started](https://tuios.gaurav.zip/docs/getting-started.md): Install TUIOS, open your first windows, and learn the keys you need on day one.
- [Keybindings](https://tuios.gaurav.zip/docs/keybindings.md): Every default key in TUIOS for window mode, terminal mode, prefix commands, copy mode and the mouse, grouped by the config section that owns it.
- [TUIOS vs Others](https://tuios.gaurav.zip/docs/comparison.md): How TUIOS compares with tmux, zellij, herdr, GNU screen and the splits in WezTerm, kitty and Ghostty, and when to pick one of them instead.

## Docs: Windows and Layout

- [Layout Modes](https://tuios.gaurav.zip/docs/layout-modes.md): Floating, BSP, master-stack, scrolling columns and zoom, and how to switch between them.
- [BSP Tiling](https://tuios.gaurav.zip/docs/bsp-tiling.md): Tile windows with binary space partitioning, and switch to the master-stack or scrolling layouts.
- [Session Rail](https://tuios.gaurav.zip/docs/session-rail.md): The sidebar that lists sessions, machines, panes, files, agents and git state.
- [Themes and Appearance](https://tuios.gaurav.zip/docs/themes.md): Colour themes, custom and imported themes, chrome colours, glyph sets, spacing, dimming and the spotlight.
- [Configuration](https://tuios.gaurav.zip/docs/configuration.md): Every table and option in the TUIOS config.toml, with defaults and how changes apply.

## Docs: Sessions and Machines

- [Sessions & Daemon Mode](https://tuios.gaurav.zip/docs/sessions.md): Persistent sessions that survive detaching, shared sessions, and what comes back after a restart.
- [Remote Hosts](https://tuios.gaurav.zip/docs/remote-hosts.md): Open sessions on other machines in your own client, run panes on another machine, and script across hosts.
- [Web Terminal](https://tuios.gaurav.zip/docs/web.md): Use TUIOS from a browser with tuios-web, a separate server binary.

## Docs: Agents

- [Agents](https://tuios.gaurav.zip/docs/agents.md): Track what coding agents in your panes are doing, get alerted when one needs you, and let agents drive TUIOS.
- [Agent Messaging](https://tuios.gaurav.zip/docs/agent-messaging.md): Let agents in different panes find each other, leave messages, ask questions and hand over files.
- [Worktrees](https://tuios.gaurav.zip/docs/worktrees.md): One session per git worktree, and one prompt fanned out to several agents at once.

## Docs: Scripting

- [Control Protocol](https://tuios.gaurav.zip/docs/control-protocol.md): Drive a TUIOS daemon from scripts and programs with line-delimited JSON on its socket.
- [Hooks](https://tuios.gaurav.zip/docs/hooks.md): Run shell commands when windows, workspaces, sessions and agents change.
- [Tape Scripting](https://tuios.gaurav.zip/docs/tape-scripting.md): Script TUIOS with .tape files, and build project layouts with .tuios.tape.
- [Project Tapes](https://tuios.gaurav.zip/docs/project-tapes.md): A .tuios.tape file that builds a project's session and layout when you cd into it, after you review and trust it.

## Docs: Recording

- [Tape Recording](https://tuios.gaurav.zip/docs/tape-recording.md): Record what you do in TUIOS into a tape you can edit and replay.
- [Screenshots](https://tuios.gaurav.zip/docs/screenshots.md): Capture a pane, a region or the whole screen as a styled PNG, SVG, HTML or text file.
- [Showkeys Overlay](https://tuios.gaurav.zip/docs/showkeys.md): Show the keys you press on screen, for demos, screencasts and teaching.

## Docs: Reference

- [CLI Reference](https://tuios.gaurav.zip/docs/cli-reference.md): Every tuios command and flag, with examples. Sessions, windows, input and output, agents, remote hosts, tapes, environment variables and exit codes.
- [Architecture](https://tuios.gaurav.zip/docs/architecture.md): How TUIOS is built, for contributors and the curious. The client and daemon split, the package map, rendering, graphics, the SSH server, tapes and tests.
- [Library Usage](https://tuios.gaurav.zip/docs/library.md): Embed TUIOS in your own Bubble Tea program with the pkg/tuios Go package, or serve it over SSH or in the browser.
- [Contributing](https://tuios.gaurav.zip/docs/contributing.md): Build TUIOS from source, run the tests, and send a pull request.

## Blog

- [A full scrollback cost 232MB per pane, twice: once in the daemon and once in each client](https://tuios.gaurav.zip/blog/48mb-per-pane-twice.md): A 112-byte cell made every scrollback line cost the full pane width. Packing cells, then storing lines as text, took a full ring from 232MB to 2.2MB.
- [Agents drive tuios through one-shot commands, so the event bus could not reach them](https://tuios.gaurav.zip/blog/a-bus-is-not-a-mailbox.md): A hub only reaches whoever is subscribed right now, and agents almost never are. How tuios got a mailbox, ask-agent and an inbox for the person.
- [The pane ran on another machine, and ctrl+D waited for the next keypress](https://tuios.gaurav.zip/blog/a-pane-on-another-machine.md): tuios daemons now talk to each other over one ssh link per machine. It shipped in stages, and each stage had a bug that taught me something.
- [A PTY has one size, and two clients had two opinions about it](https://tuios.gaurav.zip/blog/a-pty-has-one-size.md): Two clients on one session each laid the panes out around their own chrome and fought over the shared shells. The fix, and the harness that found the rest.
- [A session switch forgot my column widths](https://tuios.gaurav.zip/blog/a-session-switch-forgot-my-column-widths.md): Switching sessions and back reset a widened column in the scrolling layout and split stacked panes apart. The daemon's state carried where the strip was scrolled to and nothing about its columns, and the same gap had two clients on one session drawing different widths.
- [Most of a scroll was spent on blank cells](https://tuios.gaurav.zip/blog/most-of-a-scroll-was-blank-cells.md): A ten-character line scrolling off a 207-column screen walked the whole row twice, once to find the text and once to erase it. One int per row cut the short-line scroll from 1,120 ns to 240 ns. Here is how it was measured on a machine that would not sit still, and how I checked it was still right.
- [Nothing failed, so nothing was fixed](https://tuios.gaurav.zip/blog/nothing-failed-so-nothing-was-fixed.md): A whole-codebase audit of tuios found a flag nothing set, an interface with one implementation behind 140 call sites, and copies of code that had quietly drifted apart. Dead code survives because nothing fails when it is wrong.
- [Session state was saved every 30 seconds and never read back](https://tuios.gaurav.zip/blog/sessions-come-back.md): tuios wrote every session to disk from April and no daemon ever loaded it. Wiring up the read side, and then making reattached panes redraw correctly.
- [The one moment an agent needed you was the one moment tuios could not see](https://tuios.gaurav.zip/blog/the-moment-nothing-could-tell-them.md): A coding agent blocked on a permission prompt paints it once and goes silent. How tuios learned to tell that silence apart from a finished turn.
- [The underline depended on which code drew it](https://tuios.gaurav.zip/blog/the-underline-depended-on-which-code-drew-it.md): A focused pane dropped SGR underline, and a dimmed, scrolled back or copy mode pane dropped almost every attribute once it lost focus in window mode. tuios had five ways to draw a pane and only one kept everything. The difference only showed when a pane changed paths, usually as focus moved.
- [The screenshot cell was half measured and half guessed](https://tuios.gaurav.zip/blog/the-cell-was-half-measured.md): Pane screenshots came out stretched. Two rounds of font maths got the cell shape wrong. The fix asks the host terminal for its real cell size in pixels.
- [The renderer was drawing a backlog it had caused](https://tuios.gaurav.zip/blog/drawing-the-backlog.md): A flooded tuios pane kept painting 1.2 s after its source exited. The client's own renderer caused the backlog, and pacing by queued bytes halved the tail.
- [The fuzzer that found nothing, and the two questions that found everything](https://tuios.gaurav.zip/blog/the-fuzzer-that-found-nothing.md): 590,000 fuzz runs against the tuios terminal emulator found nothing. They checked the screen was well formed, not right. Two self-checks found real bugs.
- [A fifth of every frame went to changing nothing](https://tuios.gaurav.zip/blog/a-fifth-of-every-frame-went-to-changing-nothing.md): A profile put 19.8% of the tuios client in lipgloss.Wrap, rewrapping pane text already the right width. Skipping it was easy. Proving the skip safe was the work.
- [My differential tests passed and the screen was pink](https://tuios.gaurav.zip/blog/my-differential-tests-passed-and-the-screen-was-pink.md): A style cache keyed by recycled libghostty-vt style IDs painted ls output hot pink, and a differential test suite that compared once, at the end, missed it.
- [The daemon said yes to an option that did not exist](https://tuios.gaurav.zip/blog/the-daemon-said-yes-to-an-option-that-did-not-exist.md): Driving the tuios control socket like a machine found a command that lost its spaces, a dropped parameter, and 88 settings of which six applied live.
- [The bug I closed three times: a speckled sprite in a WebGL terminal](https://tuios.gaurav.zip/blog/the-bug-i-closed-three-times.md): A speckled sprite in the tuios browser terminal. Three wrong closures, a test suite blind by construction, and a browser that salted its own pixel readback.
- [I dragged one divider and five windows moved](https://tuios.gaurav.zip/blog/one-divider-five-windows.md): Dragging one divider in the tuios tiling layout moved five windows. It was three defects: neighbours found by geometry, a restarting ease, a truncated ratio.
- [The benchmark said 27x faster. It felt worse.](https://tuios.gaurav.zip/blog/measuring-before-optimising.md): Fixing pane resize lag in TUIOS with Go benchmarks and pprof. Two of four theories were wrong, and the benchmark measured the wrong thing for three rounds.
- [My fuzzer was optimising for my own bug](https://tuios.gaurav.zip/blog/fuzzing-a-terminal-test-harness.md): A flaky TUI fuzz suite came down to a PTY line discipline I never configured, and a shrinker that minimised straight toward the race.
- [My multiplexer lied about what it could do](https://tuios.gaurav.zip/blog/a-terminal-that-lied-about-what-it-could-do.md): kitty icat drew nothing when tuios ran in a browser client. The graphics passthrough said yes to file transmission without asking the host.
- [I ported a correct emoji width table and it fixed nothing](https://tuios.gaurav.zip/blog/the-width-table-that-changed-nothing.md): Emoji widths were wrong in the tuios browser client. I ported ghostty's per-codepoint width table and nothing changed, because width belongs to clusters.
- [I shipped three fixes for a bug I had not found](https://tuios.gaurav.zip/blog/three-fixes-for-a-bug-i-had-not-found.md): A tuios pane went blank on focus changes. I shipped three real fixes for other bugs before I reproduced it. The cause was a width read from the first line.
- [Three terminal bugs in one month turned out to be one bug](https://tuios.gaurav.zip/blog/nobody-was-listening.md): Terminals answer queries like OSC 11 and CPR. Three bugs in three codebases were one bug: the reply was dropped, sent to the wrong place, or echoed.

## Releases

- [Everything since v0.7.0](https://tuios.gaurav.zip/releases/since-v0-7-0.md): Unreleased work on main: session layouts that come back after a daemon restart, sessions and panes on other machines, agents you can watch and message, one layout for every client, an interface that answers the mouse, and a large cut in memory use.
- [v0.7.0](https://tuios.gaurav.zip/releases/v0-7-0.md): Video playback in a pane, the kitty keyboard protocol, a rebuilt copy mode with a real scrollbar, a command palette, and the hundred fixes it took to make graphics passthrough honest.
- [v0.6.0](https://tuios.gaurav.zip/releases/v0-6-0.md): Experimental Kitty graphics support, prefix-free window cycling in terminal mode, and a real terminal cursor with vi-mode shapes.
- [v0.5.0](https://tuios.gaurav.zip/releases/v0-5-0.md): Persistent sessions backed by a daemon, multi-client attach over SSH, a remote control CLI, and BSP tiling with manual splits.
- [v0.4.0](https://tuios.gaurav.zip/releases/v0-4-0.md): The web terminal moves out into the sip library, tape scripting gets a recorder and a manager UI, and a ShowKeys overlay draws your keypresses for recordings.
- [v0.3.0](https://tuios.gaurav.zip/releases/v0-3-0.md): Bubble Tea v2 with keyboard enhancements, configurable tiling layouts, theming turned opt-in, and a scrollback rewrite.
- [v0.2.0](https://tuios.gaurav.zip/releases/v0-2-0.md): 340 color themes that restyle the UI and the terminal palette together, a new PTY layer, and windows that can no longer leave the screen.
- [v0.1.0](https://tuios.gaurav.zip/releases/v0-1-0.md): The first tagged release. A floating and tiling terminal window manager with a vim-style copy mode, scrollback, a TOML config with rebindable keys, and packaging for most platforms.

## Optional

- [Full docs text](https://tuios.gaurav.zip/llms-full.txt): Every docs page as one file
- [Blog feed](https://tuios.gaurav.zip/blog/atom.xml): Every post with its full text, as Atom
- [Releases feed](https://tuios.gaurav.zip/releases/atom.xml): Every release note with its full text, as Atom