The page is grouped by what you notice, most important first. If you already run tuios, read Before you upgrade first.

In short

• Before you upgrade: wire protocol 3, new defaults, SSH key checks, hooks in the daemon.
• Layouts come back after a daemon restart, with new shells in the old directories.
• Other machines: remote sessions, remote panes, global sessions.
• Agents: agent state in the rail, mail, worktree fan-out.
• One layout for every client.
• The mouse (including clickable links), the rail, and tiling and zoom.
• Keys: keybind manager, launcher, prefix repeat.
• Look and feel: themes, glyphs, spotlight, screen saver.
• Graphics and screenshots and the web client.
• Scripting and control: 62 verbs, 156 options.
• Project tapes and startup.
• The terminal emulator: a second backend and a conformance suite.
• Faster and smaller, and other fixes.

Before you upgrade

Most of these need nothing from you.

• Restart the daemon. The wire protocol is version 3, and version 2 is refused with a message that says which side is newer. (A message type added after v0.7.0 shifted every type number without a version change, so mixed builds misread each other.) Run tuios kill-server and start tuios again. This ends every program running in your panes. The layout, window names and working directories come back, each pane with a new shell; scrollback does not. The JSON verb protocol stays at version 1.
• New defaults on a fresh install. A bare tuios starts or joins the daemon (startup.daemon = true), starts tiled (startup.tiled = true), and draws window controls as dots on the left of the title bar. An existing config file keeps what it says: the [startup] booleans are only read from the file, so a machine that ran standalone and floating still does. The two window-button options are strings and do reach a config that never set them. tuios --standalone or TUIOS_NO_DAEMON=1 runs without the daemon. If the daemon will not start, a bare tuios runs standalone for that run and says so.
• The SSH server checks keys. tuios ssh used to give a shell to every connection. It now admits the public keys in ~/.config/tuios/authorized_keys, or in ~/.ssh/authorized_keys when the first file is absent. --authorized-keys names another file. With no keys, a loopback bind still runs unauthenticated and prints a warning, and any other address is refused. --no-auth opens it on a network you trust. A keys file that cannot be read, does not parse, or holds no key stops startup.
• Unnamed SSH connections. A connection that names no session, and whose username maps to none, now gets a session called ssh-session when several exist. It used to get whichever session was listed first. With exactly one session, it still gets that one.
• Hooks run in the daemon. after-new-window, after-close-window, after-focus-change, after-workspace-switch and after-agent-state now run in the daemon, with the daemon's environment. They fire with nobody attached, and once rather than once per client. after-attach, after-detach, after-resize and after-layout-change stay in the client, and after-detach now also fires when an SSH connection or a browser tab goes away.
• Window-mode keys. Digits 1 to 4 select windows. They used to snap a window to a corner, which is now ctrl+b L then 1 to 4. A config still carrying the default corner-snap bindings is migrated on load. Bindings you changed are left alone. With tiling on, h and l now focus the pane on that side instead of doing nothing. In the layout picker, delete moved from d to ctrl+d, so typing a filter no longer deletes a layout.
• Right-click. In window-management mode, a right-click on a pane opens the pane menu and a right-drag resizes. It used to only resize. In terminal mode the right button belongs to the pane: ctrl or shift with right-click opens the menu, and appearance.right_click_opens_menu = true makes a plain right-click open it too. A program that asked for the mouse always keeps the plain right button.
• Frame rate. appearance.max_fps now tops out at 120, the renderer's own ceiling. Values up to 240 were accepted before and changed nothing on screen.
• Selection colours. The selection, search matches and copy-mode cursor are now settings under [appearance.selection], with new defaults: a neutral grey selection, amber search matches, and a cyan copy-mode cursor. Selected text is no longer bold. appearance.selection.bold = true brings that back.
• Sidebar settings moved from flat appearance.sidebar_* keys into an [appearance.sidebar] table. The old keys are still read, the table wins where both are set, and the file is not rewritten in the old spelling.
• Removed. appearance.separator_style, which parsed and did nothing. The colorshift screen saver effect: a config that names it reads as random.

Layouts come back after a restart

The daemon saves each session's structure under $XDG_STATE_HOME/tuios/sessions and restores it when it starts. This is on by default. A detach loses nothing, because the daemon keeps the shells running. A daemon restart or a reboot ends them: what comes back is the layout, not the programs.

• Each window comes back with its workspace, its place in the layout, its name and its working directory. The session keeps its display name and accent.
• Each shell is new, started in the old directory. Scrollback and running programs are not saved.
• Restored shells get TUIOS_RESTORED=1, and tuios ls marks the session as restored until you first attach.
• A window whose shell will not start is dropped rather than restored empty.
• A state file tuios cannot read is moved aside for two weeks instead of stopping the daemon.
• Working directories now come back on macOS too. The daemon used to read them from /proc, which macOS does not have.

tuios daemon --no-restore turns restore off. tuios resurrect lists what is saved, or brings one session back by name.

The daemon is also easier to reach. A bare tuios uses it by default (see above). tuios attach starts the daemon instead of refusing. tuios ls with no daemon running lists the sessions saved on disk, marked as saved, and exits 3, so a script can tell a stopped daemon from a running one that holds nothing.

Daemon panes now honour two settings they used to ignore: appearance.scrollback_lines (the daemon kept 10,000 lines per pane whatever the file said) and appearance.preferred_shell.

Other machines

tuios can now work across machines. Every link is one ssh process per host, run with BatchMode=yes, so you need to be able to ssh to the machine without typing anything. See Sessions for the full model.

Adding a machine

tuios hosts add build gaurav@buildbox   # writes [hosts.build] in config.toml
tuios hosts test build                  # dials it now and says what it found
tuios hosts remove build
tuios hosts                             # every link and its state

• The daemon follows the config file, so none of these needs a restart. The settings page has a Hosts section that does the same.
• An address is anything ssh understands. Your ~/.ssh/config aliases are offered in shell completion and on the settings page.
• tuios hosts tailnet lists the machines on your tailnet and which ones it would offer. tuios hosts add NAME --tailnet takes the address from the machine of that name. It asks the tailscaled already running, with no root and no auth key.
• The link finds tuios on the far machine by itself: on the PATH, in the usual install paths, then through the login shell. tuios hosts test prints where it looked when it cannot find it.
• A link that drops is dialled again with a backoff. tuios hosts shows each link as up, connecting, reconnecting, unreachable, no_daemon, no_tuios or incompatible, with how many times it dropped and why.

Sessions on another machine

tuios attach --host build api   # attach the session api on build
tuios new --host build          # create a session on build and attach it

The session is drawn by this client, with this machine's theme, config and prefix key. Nothing is nested. If the link drops, the pane stays on screen, the dock says it is reconnecting, and the client tries again for three minutes before it returns to the session it left on this machine. --ssh runs the tuios on the host inside this one instead, for a host whose tuios is too old.

In the rail, sessions are grouped under their machine. Enter on a session under a host attaches it, and enter on the + beside a host creates one there. A machine's header shows how many of its sessions want a person, and each row shows what its agents are doing. A machine that is not answering is muted and its rows cannot be clicked, because they are a cached listing.

A pane on another machine

tuios new-window deploy --host build

The window belongs to this session and is laid out here. Only its process runs on build. The title bar says build:deploy, and the rail row names the machine, because the same typed line does different things on different machines. The rail's file section and agent detection work for these panes. The pane ends when the link does.

Global sessions

Once a second machine is reachable, the rail shows a global group above the machines. A session in it holds panes from several machines, and every way of making a window there asks which machine to run it on. Anywhere else, a new window opens on the session's machine without asking.

tuios new deploy --global

appearance.global_session = false hides the group. Making a new session (N in window mode, the new + at the start of the dock's session strip, or the command palette) asks which machine when more than one is reachable.

Addressing another machine from the CLI

Verbs take a host-qualified target: -s build:api for a session, -w build:api:0 for a window. local: addresses a local session whose name contains a colon. list-windows, capture-pane, send-keys, send-text, wait-for, focus-window, kill-session, session-info, get-agent-state, the agent mail verbs and the stash all take it. Every pane gets TUIOS_HOST, the hostname of the machine it runs on.

Agents

The rail shows what your agents are doing

The rail has an agents section. Every pane running a recognised coding agent is listed with its state, ordered by who needs you: errored, then waiting for input, then finished but not yet seen, then working. A finished agent you have looked at moves down the list. Rows show the harness and the last thing the agent said it was doing. The section header counts blocked and finished panes, and clicking the count filters the list. In the command palette, @n finds panes that need input and @w finds working ones, across every session.

When a state changes, tuios can tell you: a dock message, an OSC 9 notification (which reaches you over SSH), and an optional sound. The [notifications.agent] table has per-state switches, a settle window so a flapping state does not spam, and quiet hours. A blocked agent's alert now includes the question it asked. The after-agent-state hook receives the transition in environment variables, never in argv, so an agent's text cannot become shell arguments.

Detection

• 22 agent CLIs are described by TOML manifests. tuios explain-agent-detect shows why a pane was or was not recognised.
• A process is identified by what it calls itself: its name, argv[0], its executable, or the script an interpreter runs. A directory called claude or codex is no longer an agent. An agent started through sh -c, timeout, npx, uvx, mise or nix is found.
• State comes from six ranked sources: the agent's own report, its transcript, escape codes (including window-title rules, such as Codex's "Action Required"), screen rules, the foreground process, and last of all an output stall. A lower source never overwrites a higher one that is still fresh.
• The transcript reader reads only the last 128KB, so a 151MB transcript costs 652 microseconds.
• A state clears when the agent exits back to its shell. Agents in panes on other machines are detected too.
• get-agent-state and list-agents report a confidence and whether the pane needs you.

Agents can message each other, and you

tuios list-agents                      # every agent pane and its state
tuios send-agent-message -w build 'rebased onto main, please retest'
tuios read-agent-messages              # your own inbox
tuios ask-agent -w review 'which test is flaky?'   # ask and wait

• A message is at most 8KB, with a subject of up to 120 characters and up to eight attachments, sent as paths, never as bytes. A session's mailbox holds 256 messages or 512KB. A sender gets a burst of ten, then thirty messages a minute. Mail lives in memory and ends with the daemon.
• --reply-to <id> answers a message and joins its thread. read-agent-messages --thread and wait-for agent-message --thread filter by thread.
• ask-agent refuses a question that would close a loop of agents waiting on each other, not only a question to yourself. Loop detection needs --from "$TUIOS_PANE_ID".
• The person at the keyboard has an inbox called human. An agent writes to it with send-agent-message -w human. The mail overlay opens on ctrl+b M, from the palette, or with i on a rail row, and you can reply from it. list-agents reports human_unread.
• tuios stash put <file> copies a file into a store owned by the session and prints its path, ready for --attach. The file stays until the session ends, even if the sender deletes the original. The limits are 16MB per file and 256MB per session. stash get copies a file back out, also across a link.
• Mail from another machine is marked as such, and a session holds at most 32 unread messages and 32 notices from links.

One prompt, several worktrees

tuios worktree new fix/retry          # a git worktree and a session in it
tuios fan 3 --agent claude 'Add a retry with backoff to the HTTP client.'
tuios fan keep api-fan-add-a-retry-with-2

tuios worktree new creates a worktree under the tuios data directory and a session in it named <repo>-<branch>. worktree ls, worktree diff and worktree rm manage them. rm refuses a worktree with uncommitted changes unless you pass --stash or --force, and it never deletes a branch. tuios fan creates several worktrees, starts the agent in each, and types the prompt once each agent is ready. fan keep removes the others. The rail groups worktree sessions under their repository.

One layout for every client

Two clients on one session used to disagree about pane sizes, because each subtracted its own rail and dock and retiled. Now each client reports how much space it reserves on each edge, and the daemon takes the largest reserve per edge and hands every client one geometry. A client with less chrome draws a blank band instead of moving the panes.

The same rule now covers the rest of the layout:

• A zoom belongs to the session, so every client draws it.
• The master-stack ratio is kept per workspace and shared.
• Where the scrolling layout's strip is scrolled to is shared, so a client that scrolls takes the others with it, and a client that joins lands where the session is looking.
• A workspace you arranged by hand stays arranged when another client visits it for the first time.
• A BSP tree built on one client is adopted by the others.
• Session display names and accent colours are kept by the daemon, so a rename reaches every client and survives a reattach.
• The rail's width is yours: switching to another session no longer changes it.

Fixes found along the way: broadcasts now reach a client in the order they were made, two clients resizing one pane can no longer leave its emulator at a size nobody draws, and opening or closing a pane no longer leaves a neighbour at its old size on another client. Reattaching to a full-screen program such as top no longer draws its rows one blank line apart (#123).

The mouse

• Every overlay row highlights under the pointer and acts on a click: settings, the command palette, the launcher, the theme, glyph and effect pickers, the session and workspace lists, the layout menu, and dialogs. The keybind manager's rows select but do not run, and the help panel only scrolls.
• Right-click opens a menu for what is under the pointer: a pane, a dock segment, a workspace pill, the dock, the desktop, a session row, or a machine heading in the rail. Every row is an action from the keybind registry, and the key it shows comes from the registry too.
• Alt and the left button move a pane from anywhere in its content. Alt and the right button resize it.
• The left button selects text: double-click for a word, triple-click for a line.
• Dragging a tiled pane by its title bar moves it with the pointer in all three layouts, and it swaps on release.
• A click that only focuses a pane no longer resizes it, and a drag that puts a pane back where it was resizes nothing, so your shell no longer reprints its prompt.
• Sideways trackpad drift during a vertical scroll no longer jumps lists or walks the scrolling layout. appearance.niri_scroll_cells (default 8) sets how far one scroll event moves the strip.
• Links in a pane can be clicked. appearance.links sets which: off, marked for OSC 8 links only, or all (the default), which adds bare URLs, including one wrapped across rows. The link under the pointer is underlined, the pointer turns into a hand, and a label shows the target. A click opens it. A file:// link opens in a new pane running $EDITOR, on the machine the panes run on, and a directory opens in the rail's file view. An http link opens a browser only for a local client. Under tuios ssh or tuios-web it copies the URL to your clipboard instead.
• A shake of the mouse can toggle the spotlight, with spotlight.shake = true.

The dock is now a status line without powerline caps. Its contents are a [dock] table: left, center and right are ordered lists of component names, [dock.clock] sets the time format, and a [dock.custom.NAME] entry runs a shell command and shows what it prints. A command that hangs is killed with its whole process tree at its timeout. Workspace pills can be dragged into a display order, which does not renumber the workspaces.

The rail

The rail was rebuilt from a collapsible tree into flat sections. Which sections it draws, in what order, and how tall each is, is one string, appearance.sidebar.sections, with an editor in the settings panel. spacer may repeat. Drag the line above a pinned section to move the split.

• Sessions. Each session has its own colour, derived from its name, so it is stable across clients and restarts. A session with a generated name is labelled by its directory, and any session shows its git branch when there is room. Sessions and workspaces can be renamed from one dialog, and session rows can be dragged into an order. appearance.session_border = true tints every pane border with the session's colour.
• Files. The working directory of the focused pane, following the pane as focus moves, with nerd font icons coloured by file type. appearance.sidebar.folder_click decides whether clicking a folder navigates the listing, sends a cd to the pane, or both. Six file actions: create, rename, delete, copy, cut and paste. Only delete asks first. Delete moves the file to the freedesktop trash in $XDG_DATA_HOME/Trash, and appearance.sidebar.file_delete = "permanent" skips it. A file on another filesystem is refused, and on Windows a delete is permanent and says so. Paste never overwrites: a name that exists gains a number.
• Git. Add git to the sections string to see the focused pane's repository, branch, how far it is ahead of and behind its upstream, and, with appearance.git_dirty (on by default), how many files are changed.
• Agents, described above.

A program in a pane can print an OSC 7 escape claiming any directory. When the kernel says the pane's shell is somewhere else, the file actions are switched off and the rail says "read only: wrong folder", so a pane cannot aim a delete at a folder it is not in. This now also works for daemon panes and on macOS.

The rail answers the mouse throughout: rows highlight on hover, a truncated row scrolls so you can read it, the collapsed strip pops a label beside the row under the pointer, and the rail's edge can be dragged to change its width.

Tiling and zoom

There are three tilers: BSP, master-stack, and a scrolling layout in the style of niri, which puts columns on an endless horizontal strip. All three honour appearance.gap. A pane can be floated out of a tiled layout on its own, or pinned so it follows you across workspaces. "All windows" in the command palette searches every window in every workspace and jumps to the one you pick.

Windows created in a daemon session now tile. Before, only windows the attached client made itself were placed, so daemon-created windows stacked on each other or floated over the tiles. BSP and master-stack tiles no longer overlap when panes shrink.

An interactive figure goes here. Open the page to use it.

• Zoom slides into place instead of cutting (appearance.zoom_animation). appearance.zoom_size below 100 zooms like a camera: the layout stays on screen around the zoomed pane, with its neighbours running off the edges. Moving focus hands the zoom to the pane you land on (appearance.zoom_follows_focus). A tiled pane's title bar has a zoom button (appearance.window_button_zoom).
• Scrolling layout. appearance.scroll_column_max (20 to 100, default 90) lets a column fill the screen. Clicking, hovering with focus-follows-mouse, or moving focus with the keyboard brings the whole column on screen (appearance.niri_click_reveals, appearance.niri_hover_reveals). Column widths and stacks survive a session switch (the post), and the strip keeps its scroll position across a workspace switch and a retile.
• Percentage resize. ctrl+b L then 5 to 9 sets the focused pane's width to 50 to 90 percent of its region, and shift with 5 to 9 sets its height.
• New windows open where you are. A new window starts in the focused pane's directory. appearance.new_window_inherit_cwd = false turns this off.
• Popups. tuios popup -- fzf runs a command in a floating pane centred over the layout, and closes it when the command exits. --width and --height take cells or percentages (default 80% and 60%). Esc in window mode closes the focused popup. This is how fzf, gum and other pickers become tuios overlays.
• Turning tiling on after floating brings back the arrangement you had. Floating windows are no longer drawn over the clock, the log viewer or other overlays, and raising one floating window no longer reshuffles the others.

Resize was rebuilt (the post): dragging a shared border moves only the two panes that share it, an untouched split no longer drifts, and a drag no longer eases toward a target that has moved.

Keys

• One registry. Every key tuios answers to is in the keybind registry, including the palette on ctrl+p and the launcher on alt+space, which sit in a [keybindings.global] section consulted in every mode. Any action can now be bound there.
• Keybind manager on ctrl+b k: what is bound, where tuios conflicts with itself, where it conflicts with the pane's program, and a Record tab that captures the next key you press. The same analysis runs as tuios keybinds doctor and tuios keybinds explain <key>. Each finding says how it knows: certain from tuios routing, observed from a live pane, or reference from a list of program defaults.
• Giving a key back. ctrl+x on a row, or tuios keybinds free <key>, removes that key from every action in every scope so the program in the pane receives it. tuios keybinds unbind removes one action from one key.
• Launcher on alt+space or ctrl+b a: anything on $PATH, fuzzy-matched and ranked by frecency, with names and icons from desktop entries where the platform has them. Enter runs the selection in a new pane. Tab types it into the focused shell so you can add arguments. All four search boxes in tuios now share one fuzzy matcher.
• Prefix repeat. After a command worth repeating, the prefix stays armed for half a second, so ctrl+b then left left left walks three panes. appearance.prefix_repeat_time sets the window, and 0 turns it off. New prefix bindings: the arrows walk panes, ( and ) switch sessions, and a opens the launcher. These work on macOS with no terminal settings.
• New window-mode keys. N makes a new session, and b toggles the spotlight.
• Entering terminal mode on focus. appearance.auto_enter_terminal_on_focus can be off (the default), targeted (focus by selection and arrows) or all (including Tab).
• macOS. An opt+ binding on a key that composes no character, such as opt+esc, never fired. It does now, so Option+Escape leaves terminal mode as documented. When Option+Left or Option+Right arrives as the readline word motions, tuios says so and names the terminal setting to change. The default config no longer warns about its own bindings.
• Keys typed within 150ms of entering terminal mode are no longer dropped.

Look and feel

• Themes. tuios import-theme converts a kitty, ghostty, alacritty or wezterm colour scheme, detecting the format from the file. tuios list-themes lists the 342 built-in themes plus your themes directory, and an imported theme works without a restart. Switching theme recolours every open pane in place. A theme can describe itself: each colour is measured against the background, and colours under the contrast floor are named.
• Chrome colours. A theme file may carry a chrome object with accent, accent_bright, success, warning, error and info, so the interface can use an amber accent without turning every blue in every pane amber. chrome.surface sets the colour dialogs are drawn on, and the rest of the chrome is derived from it at readable contrast.
• Glyph sets. appearance.glyphs picks the shapes: borders, window controls, rail marks, folders. Four ship (default, unicode, heavy, ascii), each glyph with its own ASCII fallback, and a custom set is a file that can inherit from a built-in. tuios list-glyphs lists them, and the settings panel has a picker with a preview.
• Colour picker. Colour settings open a picker with a hue strip, a shades grid, HSL and RGB sliders, a hex field, a harmony wheel, and the theme's own colours as slots that follow the theme. Settings rows show a swatch of the colour in force. Numeric settings open an editor with a slider and a typed value.
• Zen mode. appearance.zen_mode hides unfocused borders always, or only while the mouse is still. Content never shifts.
• Window controls can sit on the left, and a dots style draws them as traffic lights. The scrollbar has two styles: a single stroke in the pane's own ink, or a track with a half-cell thumb.
• Copy flash. A copy sweeps a band of light over the copied text. appearance.selection.flash turns it off, and flash_ms, flash_color and flash_style (diagonal, diagonal-reverse, horizontal, vertical) tune it. Only the background changes, so the text stays readable.
• Spotlight. b in window mode dims everything outside a circle around the mouse. The [spotlight] table sets the radius, how dark the rest goes (dim, default 75), and whether it follows the mouse or the cursor.
• Screen saver. Off until you set screensaver.enabled. It starts after screensaver.idle_minutes idle, with 36 effects ported from terminaltexteffects (screensaver.effect, or random). The picker previews each effect over your real screen. Effects now run at the right speed at any frame rate, and on an unthemed session the saver asks the terminal for its palette instead of guessing xterm's.
• Keycast. tuios can draw your keypresses in the bottom right as you type, with repeats coalesced, for screen recordings. It toggles from the command palette and the setting persists.

An interactive figure goes here. Open the page to use it.

Graphics and screenshots

tuios screenshot writes a pane to a file as png, svg, ansi, html or txt. It runs in the daemon and reads the emulator's cell grid, so it works on a detached session from a script: tuios screenshot -w build. On macOS it now finds your fonts without fontconfig, including fonts inside .ttc collections, so Nerd Font icons draw instead of boxes.

• Kitty graphics over SSH. Passthrough used to be decided by asking the server's terminal, and a server has none, so graphics were off for every SSH client. The client's capabilities now come from the SSH connection: TERM, the forwarded environment, and the pixel size it reports.
• Animation. The kitty animation protocol, dropped in v0.7.0, is implemented. Animated images send only the changed regions, which took one measured page from 330MB forwarded in 21.6 seconds at 17fps to 22MB at 73fps. A flood of graphics is paced so it cannot starve the keyboard.
• Unicode placeholders. Images drawn with placeholder cells, such as those in glow's pager, now show inside a pane and scroll and clip with the text. They need a host that supports placeholders (kitty, Ghostty, WezTerm), so not tuios-web. appearance.kitty_placeholders forces the choice.
• Covered images are cropped. A window over part of an image now cuts that part away instead of hiding the whole image. An image no longer draws over the rail or the dock, and an image in a pane's last rows no longer scrolls the whole screen up.
• Bounded memory. An animated gif under chafa grew tuios to 5.3GB in two minutes. The same run now stays at 189MB.

The web client

• Text shaping. The web client can use sip's WebGL renderer with HarfBuzz shaping (opt-in). Arabic letters join, ligatures form, and combining marks land where they belong. Grapheme widths now match a reference terminal, and a freeze where synchronized output was left on is fixed.
• TLS and phones. tuios-web can serve a LAN address over TLS, and --auto-tls creates and keeps a certificate for the hostname and every interface address. tuios-web cert inspects or replaces it. On a phone, a row of tuios commands sits near your thumb, built from the keybind registry, a long press opens the pane menu, and pane dividers are big enough to grab.
• Your theme. A browser now shows the theme you picked, and the tab shows tuios instead of "Sip".
• Settings changed from a browser session apply to that session only, instead of writing the server's config file.
• tuios-web takes every interface flag tuios takes.
• The Docker image now includes tuios-web.

An interactive figure goes here. Open the page to use it.

Scripting and control

The daemon speaks 62 verbs over a line-delimited JSON socket, one JSON object per line each way. tuios list-verbs lists them with every error code a verb can return. See the control protocol.

• Strict parameters. A parameter a verb does not take is refused with the closest spelling and the accepted list, instead of being dropped.
• Options. One registry holds all 156 settable options. It backs set-option, get-option and list-options, and the settings panel is built from it. set-option refuses a path that does not exist, with suggestions, and validates colour values. It also fixed a bug where a dozen settings, from border style to the leader key, were saved and then read back as defaults on every reload, and a boolean turned off could not be saved.
• Config reload. Editing config.toml reaches the running client, even with editors like vim that save by renaming. A file with an error is reported on screen and the running config stays.
• new-session creates a session and its first window from a program, with no client attached.
• run-command refuses a command name it does not know, instead of reporting success. tuios run-command --list lists the names.
• Hooks say what happened. tuios list-hooks shows each hook command's run count, last exit code, last run and last error. A failing hook logs its exit code and the tail of its stderr.
• Daemon logs. The daemon writes errors and basic events to $XDG_STATE_HOME/tuios/daemon.log, so a crash leaves a record. tuios set-config daemon.log_level messages raises the detail without a restart. tuios daemon --pprof serves profiling data.
• Crash report. A panic in the interface now shows a full-screen report with the build, terminal, layout and last actions. c copies it, and g opens a prefilled issue. It never includes pane contents, titles, paths or session names.
• tuios update replaces the binary in place, but only when it installed it. It recognises a release download, the install script, go install, Nix, Homebrew and system packages, and for the others it names the installer that owns the binary.
• Agent skill. tuios --skill prints the recipes for driving tuios from a pane. A test parses every command in it against the real command tree.
• tuios send-keys no longer pulls a pane you scrolled back to the bottom.
• tuios stash put and stash get print only the path on stdout, so path=$(tuios stash put FILE) works.

Most of this hardening came from driving the socket the way a program would, which got its own post.

Project tapes and startup

A .tuios.tape in a project directory describes the session for that project: which windows to open, what to run in them, and how to lay them out. When the focused shell changes into a directory that has one, tuios notices, like direnv for terminal layouts.

A tape runs commands, so nothing happens until you have read it. The review dialog shows the whole file, and you choose Run once, Trust and run, or Never. Trust is tied to the file's content hash, so any edit makes it ask again. By default a dock badge and a notification tell you a tape is there. auto_review opens the review dialog on detection. autorun = "auto" runs a tape without asking, but only one you trusted and have not edited since. Running a tape builds a session named after the project and switches to it.

An interactive figure goes here. Open the page to use it.

Three startup settings remove the steps every session used to start with: startup.open_default_window, startup.tiled and startup.start_in_terminal_mode. Only tiled is on by default, and only for a fresh install (see Before you upgrade). With all three on, tuios opens tiled with one terminal and your next key goes to the shell. Startup also asks the terminal everything in one round trip, which took the time to the first frame from 566ms to 68ms.

An interactive figure goes here. Open the page to use it.

The settings menu now covers everything the config file does, with an inline editor for text values, and changes persist.

The terminal emulator

Behind a ghostty build tag, panes can run on libghostty-vt, the emulation core of the Ghostty terminal, instead of the pure Go emulator. Both backends implement one interface. A differential suite feeds both the same bytes and compares screens, cursors, scrollback, modes and the output a host would receive, after every chunk. The first version of that suite passed while the ghostty backend painted ls on hot pink, which is its own post. Releases ship ghostty builds beside the default ones.

A conformance corpus checks byte strings on a 6x4 screen against literal text dumps, citing esctest and vttest, and can compare against a real tmux. A grammar-based fuzzer feeds the emulator sequences that have broken terminals before. Two more checks need no expected output: an emitted frame must redraw the screen the emulator holds, and the same bytes must draw the same screen however the reads are split. Bugs they found, any of which a program in a pane could hit:

• The cursor position report had line and column swapped.
• Under TERM=screen, linux or vt100, box drawing came out as lqk, because SO and SI were unreachable.
• OSC 8 hyperlinks had their fields swapped and never worked.
• DECSTBM accepted a scroll region taller than the screen, and the next scroll crashed the daemon and every session in it.
• A mode map read without its lock, and two captures of one busy pane, could each crash the daemon.
• NEL, DECALN, DECSTR and DECRQSS were missing, and insert mode was recorded but ignored.
• ED 3 cleared the visible screen, REP repeated the wrong character, and a wide character cut at a margin left half of itself behind.
• A window title containing a character from the Dingbats block, which Claude Code puts in its title, ended early and printed the rest into the pane, because a byte inside the character was read as an eight-bit string terminator. Invalid bytes in titles are now dropped.
• A single shift (SS2, SS3) before a multi-byte character leaked into the next character.
• Underline and other attributes were dropped on the focused pane's render path.

Where the two backends still disagree, the difference is pinned as a known divergence rather than left to pass quietly.

Faster and smaller

Every number here comes from the commit that made the change.

Speed

• Idle: with idle shells and the rail open, tuios schedules no timer-driven renders. The render ticker now runs at max_fps, which at the default of 60 took an idle client from 1.0% to 0.6% of a core.
• Typing a letter into a shell: 18.9us and 177 allocations down to 1.06us and 14. A keystroke over the socket: 4,009ns and four writes down to 967ns and one.
• Keypress to echo: the median went from 9.75ms to 1.78ms. Typing into one pane while another floods went from an 18 to 28ms median round trip to 1 to 5ms, against tmux's 1.
• A pane that falls more than 4MiB behind drops to catch-up rate until it recovers, and a busy pane can no longer starve the renderer.
• Workspace switch: the client asks only for rows it does not have. At four panes that is 11.5MB of encoding down to 0.6MB, and a caught-up switch went from 47.6ms to 2.4ms per pane.
• Drawing a pane's frame: 6.53ms to 1.58ms when dirty, 3.51ms to 62.7us when cached. The pane renderer stopped re-wrapping content that was already the right width, which was a fifth of every frame.
• The rail's rows: 82,000ns and 178 allocations per frame down to 288ns and none.
• Moving the pointer over plain text no longer composes a frame per cell.
• A truecolor repaint: allocations down from 757,200 to 189,600 per run of the benchmark. Scrolling short lines: 65 to 79 percent less CPU.

Memory

• Scrollback is stored as text with styles marked where they change. A 175-character line went from 4,864 bytes to 216, and a full 10,000-line history from 48MB to 4.2MB per pane, in the daemon and again in each client.
• An empty 207x55 pane held 1.7MB before printing anything, 1.3MB of it the screen grid. A row is now allocated only when something is printed on it, and an empty pane's grid holds 28KB. The alternate screen is built on first use.
• Eight empty panes: heap from 47.5MiB to 14.9MiB.
• On the ghostty backend, scrollback_lines now holds. The library pruned by bytes first, so a pane asked for 10,000 lines kept about 400 at 207 columns.

Other fixes

• The last output of a pane, often its prompt, sometimes stayed invisible until the next key. It is now drawn at once.
• A pane scrolled back stays on the line you stopped at while new output arrives.
• Ctrl+P opens the palette even when the terminal reports Num Lock in the key event.
• Quitting a session says "Killed", not "detached", and names the session you were in.
• A grapheme cluster split across two writes renders as one.
• Programs in tuios are told graphics forwarding is available, so image tools stop falling back to blocks.
• Clipboard copy and paste work on GNOME Terminal and other VTE terminals, and over a loopback SSH connection, using the native clipboard tool.
• Ctrl+D in a pane on another machine closes it at once instead of on the next key.
• The log viewer's copy keys (E for errors, A for all) now work.
• Help opened from the leader starts at the top. In help, q closes it outside a search and can be typed inside one.
• Mouse scroll speed and window title format are configurable, in the file and in the menu.

• Video plays in a pane.
• fish 4.x's kitty keyboard handshake works.
• Copy mode has a scrollbar you can grab.
• A command palette lists every action.

Most of the fixes are the cost of passing another terminal's protocol through a multiplexer: clipping, positioning, flicker, and the gap between what a spec says and what mpv sends.

Changed behaviour

• The mouse wheel now enters copy mode. The separate scrollback mode, which could scroll but not select, is gone.
• The dock's clock, CPU and RAM meters are off by default, and are only polled when shown.
• A new --confirm-quit flag and confirm_quit option always ask before quitting.

Video playback

mpv --vo=kitty plays video in a tuios pane, and so does youterm. Shared memory and base64 modes both work. Use --vo-kitty-use-shm=yes: it sends a file reference per frame instead of streaming megabytes of pixels through the terminal.

Video is the hardest case for graphics passthrough, and most of the fixes were here:

• mpv marks every frame "more data coming" and never sends the final-chunk marker the protocol says to wait for, so passthrough that worked for static images waited forever.
• Each frame used to get a new image ID, forcing a delete and replace with a visible flash. Frames now reuse the host's image ID, so the terminal swaps the data in place.
• File-based frames are forwarded as a path instead of being read, base64 encoded and chunked, which saves about 4MB of allocation per frame at 30fps.
• All graphics output is wrapped in synchronized updates and flushed with the render cycle. Text and graphics arriving as two unsynchronized streams caused the tearing.

Static images got the same care: icat and yazi previews clip at the viewport, hide when their window leaves the screen, and follow the window during a drag.

The keyboard protocol shells expect

The VT emulator implements the kitty keyboard protocol: the full push, pop and query stack, with keys sent in CSI u encoding when a program has the protocol on. fish 4.x turns it on at startup, and before this release capital letters arrived as escape sequences fish ignored. As the spec says, shifted printable keys now send their text, and CSI u is kept for real modifier combinations.

The same work added:

• OSC 4 palette queries and OSC 52 clipboard.
• Modes 2026 (synchronized output) and 2027 (unicode core).
• Sixel in the DA1 reply.
• OSC 66 text sizing, as an experimental passthrough (see Known limitations).

Copy mode

• The mouse wheel drops you into copy mode, so scrolling up and selecting are one gesture. It has full vim navigation, visual and visual-line selection, search and yank.
• The border is a scrollbar, drawn in the theme's border colours and sized to the content. Click it to jump and drag it to scroll.
• Dragging a selection past the edge of the pane keeps scrolling on a timer, so the selection keeps growing while the mouse is still.

A new scrollback browser splits your history into command blocks using OSC 133 markers, with a regex fallback for shells that do not emit them. Each block is a command and its output, navigable with vim keys, and you can yank JSON fragments and file paths out of the output. fish and a configured starship both emit OSC 133.

An interactive figure goes here. Open the page to use it.

Command palette, sessions and layouts

• Command palette on Ctrl+P: every tuios action, fuzzy-searched, with its key shown beside it. A match on the name ranks above a match on the category. It floats at the top of the screen and works in both modes.
• Session switcher on prefix+S lists daemon sessions the same way.
• Layout templates save the BSP tree, each window's working directory (read from /proc), startup commands, and the tiling scheme. Positions scale when you load a template on a different screen size. Loading moves existing windows into place instead of killing them, and minimizes extras. The CLI is tuios layout list, delete, dir and export, and export turns a template into a tape script. The layout submenu is on Ctrl+B L.
• Zoom on z fills the screen with the focused pane. Press it again to restore. The dock shows a Z while zoomed.
• Shared borders. With --shared-borders, tiled windows are drawn without borders and a single line with proper junctions separates them, which saves two columns and two rows per split. It is opt-in because it took several attempts: the feature was reverted and reimplemented three times before the separator overlay stuck.
• Smart split picks the split direction from the focused pane's shape. It is opt-in because as a default it made narrow slices, so spiral stays the default.

An interactive figure goes here. Open the page to use it.

Faster underneath

• Rendering is driven by PTY output instead of a tick. The tick remains only for animations and tape playback, and slows to an idle rate when nothing moves. With the dock meters off by default, idle CPU is near zero.
• Unfocused windows without a selection take a fast path that skips per-cell styling. Windows on other workspaces skip render work, and tuios-web and SSH clients do not even receive their output until you switch to them.
• Base64 image data passes through without a decode and re-encode, which saves about 8MB of memory traffic per 4MB image. /dev/tty is opened once instead of per frame, and only placements that moved are placed again.
• tuios moved to the stable Charm v2 releases: bubbletea, lipgloss, wish and log.

Fixed

Most graphics fixes are described above. The rest, grouped:

Daemon mode

• The daemon's emulator dropped kitty graphics capability queries, so icat and chafa fell back to blocks. The daemon now answers them.
• PTY sizes sync on reattach instead of keeping the previous client's size.
• The client sends its pixel size and graphics capabilities to the daemon at hello.
• The subscriber buffer is 16 times larger, so video frames survive the socket from daemon to client.

Input and mouse

• Mouse motion is only sent to programs that asked for it. kakoune got hundreds of unrequested motion events a second (#78).
• Phantom keypresses from split mouse sequences are suppressed.
• Visual line mode highlights at once instead of on the next cursor move.

Colours and light themes

• Unstyled cells use the terminal's real default foreground instead of white, and SGR 39 and 49 reset to transparent instead of a fixed default. This fixes light themes (#41, #72, #74).

Responsiveness

• Closing a window with exit or ctrl+d no longer waits out a 500ms timeout (now 10ms), and a race that lost the close notification about half the time is gone.
• Background windows no longer show stale content until you touch them.

Other

• Tape scripts send CRLF on Windows, contributed by @dodorz.
• Many smaller fixes to scrollback, tiling toggles and overlay positioning are listed in the full changelog.

Known limitations

• OSC 66 text sizing breaks with scrollback and when a window moves.
• Sixel passthrough exists but is disabled until pixel-level clipping is implemented, so sixel images cannot be cropped to a window. Use kitty graphics.
• The kitty animation protocol (a=f, a=a, a=c) was tried and dropped. It needs image IDs to match between guest and host, and tuios remaps them. Run programs that use it outside tuios for now.
• Video without shared memory can flicker, depending on frame rate.

• Window cycling in terminal mode without the prefix key.
• A real terminal cursor, so vi-mode cursor shapes work.
• Compatibility fixes, several of them contributed.

Images, experimentally

tuios redraws each window's content into its own grid, so an image cannot pass through as is: its graphics commands carry positions that mean nothing to the host terminal. tuios now translates them.

• The VT emulator reads the graphics commands, tuios tracks each placement against its window, and forwards it to the host at the right cell.
• A placement is moved when its window moves, resizes or scrolls, and hidden when it is covered, dragged, or scrolled out of view.
• Shared memory, file and direct transmission all work, with chunking for large images.
• Cell pixel sizes are reported to the PTY, so programs size images correctly.

yazi and kitty icat show real images in tuios windows on a host terminal that supports them: Kitty, WezTerm, Ghostty, iTerm2, Foot or Contour.

Five fixes followed the feature in this cycle: clipping at window borders, placements drifting against scrollback, image ID collisions between windows, images left behind when a program leaves the alternate screen, and virtual placements that assumed a placeholder grid tuios did not have. More edges were found later.

Known limits

• TUIOS_KITTY_GRAPHICS=0 turns graphics off.
• Images wider than the viewport are hidden rather than clipped.
• Sixel is parsed but disabled until raster clipping exists.

Graphics detection by asking

tuios used to guess graphics support from the terminal's name. Now it asks.

• A DA1 query detects sixel, and the kitty graphics query detects the kitty protocol.
• Reads poll with a timeout, so a terminal that never answers cannot hang startup.
• TUIOS_DEBUG_CAPS=1 logs what detection found. TUIOS_KITTY_GRAPHICS and TUIOS_SIXEL_GRAPHICS override it either way.

Cycling without the prefix

Window management used to be three keys away in terminal mode. Now it is one:

• macOS: Opt+Tab and Opt+Shift+Tab cycle windows.
• Linux and Windows: Alt+N and Alt+P, because Alt+Tab belongs to the OS window switcher.
• Opt+Esc or Alt+Esc leaves terminal mode.

The bindings live in a new [keybindings.terminal_mode] section and show in the help menu. This part of the release was contributed.

A real cursor

tuios used to paint its own cursor, a cyan block drawn into the grid. It now moves and styles the real terminal cursor, so cursor shape sequences from programs pass through. A shell in vi mode shows a block in normal mode and a bar in insert mode, blinking included.

Fixed

• Paste works in daemon mode. Pasted text was written into the internal pipe whose responses are discarded, so it vanished.
• Arrow keys work in cmus and other ncurses programs. Programs that turn on application cursor keys mode now get SS3 sequences instead of CSI.
• Fast scrollback no longer crashes in colour comparison. Claude Code's output was fast enough to trigger it. Contributed.
• tuios builds on FreeBSD and OpenBSD.
• macOS terminal handling is split from Linux, because the shared ioctl constants were Linux-only.
• --hide-clock and --window-title-position survive opening new windows instead of being overwritten by the config loader. These two shipped as v0.5.1.
• Animation bookkeeping is skipped when nothing is animating.

Graphics stayed experimental well past this release, with horizontal clipping and sixel still open. TUIOS_KITTY_GRAPHICS=0 restores the old behaviour.

• A daemon keeps sessions alive when the client disconnects.
• More than one client can attach to one session.
• New CLI commands drive a running session from outside.
• BSP tiling, with manual splits.

Underneath, the code moved to the charm.land packages for Bubble Tea v2.

Breaking changes

• Import paths. If you build on tuios as a library, the Charm packages moved from github.com/charmbracelet to charm.land.
• Session state. State from before v0.5.0 does not carry over to the new daemon format.
• CLI. tuios new and tuios attach take the session name as a positional argument. The flags that did the same are gone.

Sessions that survive a disconnect

tuios new work      # create a session backed by a daemon
tuios ls            # list sessions
tuios attach work   # attach again

Detach, close the terminal, or lose the SSH connection, and the session keeps running. Attaching again brings back windows, layouts, BSP trees, screen contents and scrollback. A session lasts as long as the daemon process. The daemon is started in-process.

This works on Windows too. The daemon uses Unix sockets and ConPTY, which Windows has had since Windows 10 build 17063.

In daemon mode there are two VT emulators, the daemon's and the client's, and both answered terminal queries. The extra answers printed as text, such as ^[[?62;1;6;9;15;18;22c on reattach. The first fix dropped every reply, which made fish wait two seconds at startup for a Device Attributes reply that never came. What shipped: the daemon's emulator answers queries, and the client's drops its copies, so programs get their replies and nothing prints twice.

An interactive figure goes here. Open the page to use it.

More than one client

• Several clients can attach to one session and see the same thing. Focus, mode changes, workspace switches and window lifecycle sync in real time.
• The session renders at the smallest attached client's size, so nobody gets a cropped frame.
• The SSH server maps the username to a session, so ssh -p 2222 work@host attaches to work. Connecting without a name shows a session picker.

A typical use is pair debugging: one person creates the session and the other attaches from another machine.

Most of the fixes in this release made this stable. Client teardown, daemon goroutines and window callbacks had races that only show with two clients on one state. They got sync.Once on close, WaitGroup tracking, an atomic flag, a five-second shutdown timeout, and tests under the race detector.

A CLI for a running session

• tuios send-keys sends keys to tuios for window management, or with --literal --raw straight to the focused PTY, one character at a time.
• tuios run-command runs any tape command by name.
• tuios set-config changes configuration at runtime.
• tuios tape exec runs a tape file against the session.
• tuios list-windows, tuios get-window and tuios session-info read daemon state with no TUI attached, with --json for scripts.
• tuios logs tails the daemon.

All of them have shell completion.

BSP tiling

A binary space partitioning layout. New windows follow a spiral, alternating vertical and horizontal splits. When the spiral guesses wrong:

• Ctrl+B - and Ctrl+B | split explicitly.
• Ctrl+B R rotates the split at the focused window.
• Preselection chooses where the next window lands, and the dock shows the direction of the next split.
• An equalize command resets every ratio to 50/50.

Trees are kept per workspace and saved in daemon state, so a layout survives a detach and reattach.

Snapping, appearance and animations

• Dragging a window to a screen edge snaps it: top centre for fullscreen, the left or right edge for a half, corners for quarters. A window has a minimum size, so it cannot be dragged into nothing.
• window_title_position puts titles at the bottom, the top, or nowhere.
• hide_clock removes the clock overlay.
• Titles show the window's custom name or the terminal's own title instead of a default ID.
• Animations can be turned off with --no-animations or with a keybind. Off means off: snap, minimize and restore apply at once instead of playing a zero-length tween that flashes.
• Recorded tapes start with DisableAnimations, so playback looks the same on any machine.

tuios as a library

A first cut: pkg/tuios exposes the app as a Go package, with functional options for theme, shell and animations, and the recommended tea.Program settings for embedding it.

Under the hood

• The module moved to charm.land: Bubble Tea v2.0.0-rc.2, Lipgloss v2, Wish v2, and sip v0.1.11 to match.
• The CLI was split into one module per command.
• The VT emulator synced with upstream: about forty deprecated mode constants renamed, a nil colour panic fix ported, and grapheme width calculation simplified enough to drop two dependencies.
• The layout, pool and theme packages got tests, and staticcheck and go vet run clean.

Fixed

• Swapping windows in tiling mode updates the BSP tree, so a swap no longer snaps back on the next layout pass.
• Shift+Tab reaches the PTY as backtab even when the terminal reports extra modifier bits.
• On macOS, some opt+ bindings were registered as alt+.
• Reattaching to a tiled daemon session sized windows from the stale 80x24 handshake. Tiling now waits for the real size.
• Remote commands send maps and slices correctly, and the inspection commands work with no TUI attached.
• tuios-web got a --no-animations flag, theme setup, and a curl install script. An AUR conflict between tuios and tuios-bin was fixed.

Documentation

Five new guides: BSP tiling, tape recording, the ShowKeys overlay, multi-client sessions, and the library API.

A correction: the GitHub notes for v0.5.0 list tape recording and ShowKeys as new features. Both shipped in v0.4.0. This release added their documentation.

• A web terminal, as the separate tuios-web binary built on the sip library.
• Tape scripting, with a recorder and a manager UI.
• ShowKeys, an overlay that draws your keypresses for screen recordings.

The patch releases fixed resizing in floating mode and made the quit dialog ask only when something is running.

The web terminal

tuios-web serves tuios in a browser. It is a separate binary, so the main tuios binary carries no server code, and people who never use a browser never install one. It is a thin wrapper that hands tuios instances to sip's Handler interface. sip serves any Bubble Tea app in a browser.

It went through three designs before the release. It started as a tuios web subcommand: WebTransport with a WebSocket fallback, xterm.js with WebGL on the client, and a bundled Nerd Font. That embedded about 10MB of web assets in the repository and put an HTTP server in the window manager. The command then became its own binary, and the server moved into sip, taking the 10MB with it.

tuios web was added and removed within this cycle, so no tagged release ever shipped it and there is nothing to migrate.

The rebuilds fixed two defects:

• Web sessions used to start the tuios binary as a subprocess. They now run tuios in-process over pipes, like the SSH server.
• The first frame was drawn at a fixed 80x24 before the browser reported its size, which left artifacts. The session is now created after the browser's first resize, so the first frame has the right size.

Tape scripting

A .tape script drives tuios from a file: open terminals, type into them, manage windows, switch workspaces and modes, and pause between steps.

• tuios tape validate checks a script.
• tuios tape play runs it live with a progress indicator.
• Playback goes through the same Bubble Tea update loop as live input, so a tape and a person at the keyboard run the same code.
• The recorder captures your starting state, window actions, mode switches and workspace switches. Consecutive characters become one Type command, so a recorded tape reads like one written by hand.
• The tape manager on Ctrl+B T m browses, records and manages tapes without leaving the session.

A headless tape run mode existed during development. It never worked properly and was removed rather than shipped.

ShowKeys

tuios can draw your keypresses in the bottom right as you type, inspired by nvzone/showkeys. Turn it on with --show-keys or toggle it with Ctrl+B D k.

• Keys are drawn as pills styled like the window title, with modifiers spelled out.
• Repeats collapse into a count (j ×3).
• Keys stay for three seconds. The first version used one, which was too short to read.

The leader key is now configurable as well. It was fixed at Ctrl+B, and now comes from leader_key in the [keybindings] section. The help menu and every chord follow it, and ShowKeys highlights it so a viewer can spot it in a recording.

An interactive figure goes here. Open the page to use it.

Changed: the patch releases

v0.3.1 to v0.3.4 shipped in the first week of November. Most of it fixed resizing in floating mode.

• During a drag, the window geometry updates at once and the PTY resize waits until release, so the shell no longer gets a stream of resize signals.
• The emulator's size stays in sync with the window's, so content no longer sticks at the old size while the border moves.
• A "Resizing... WxH" indicator shows in the window during a drag. In tiling mode, neighbours pulled along by the drag show it too.
• After a drag, PTY buffers are flushed and polling waits for the shell to redraw its prompt at the new width, which fixed half-drawn prompts.
• If the cursor ends up below the view after a height reduction, the view scrolls to keep the prompt visible.
• Dragging right after a resize no longer freezes the window.

Other changes in the patches:

• Quitting with open terminals shows a confirmation. It asks only when a terminal's foreground process is running something, so quitting idle shells just quits.
• The welcome screen shows on any workspace with no visible windows, not only when the whole session is empty.
• The shell is configurable. This mattered most on Windows, where tuios always started PowerShell.

Fixed

• Decimal durations in tapes parse correctly, so 1.5s no longer rounds.
• The render cache is cleared when leaving resize mode, so the resize indicator disappears at once.
• ShowKeys compares modifiers, so Ctrl+L followed by L shows two keys instead of one pill.

Project

• A contributing guide.
• Package doc comments across all internal packages, a golangci-lint cleanup, and a modernization pass (any over interface{}, slices.Delete, built-in min and max).
• README keybindings use kbd tags.
• tuios.exe is gitignored.

The .tape format introduced here is the one project tapes were later built on.

Breaking changes

• Themes are off by default. v0.2.0 turned them on, and an opaque themed background fights any program that wants to set its own. The terminal background is now transparent and the default theme is none, so you get your terminal's own colours. To get the v0.2.0 look back, add theme = "tokyonight" (or any theme) to your config.

Keys that mean what you typed

tuios moved to Bubble Tea v2.0.0-rc.1 and handles its keyboard enhancement messages. On a terminal that supports the kitty keyboard protocol, tuios detects it and turns it on, with nothing to configure.

A classic terminal cannot tell Shift+Enter from Enter, and cannot report Super+Space at all. With the protocol on, these arrive as separate keys, complex modifier combinations work, international layouts report correctly, and the keys reach the program in the pane unchanged.

In terminal mode, tuios used to catch the tiling resize keys, so you could not type <, >, { or } into a shell. Now only the Ctrl+B prefix is caught in terminal mode, and every other key goes to the PTY.

Tiling you can shape

• The master window ratio is configurable from 30% to 70%.
• Eight new resize operations, with directional variants.
• Each workspace remembers its layout and restores it.

Appearance

These live in a new [appearance] config section, with matching flags.

• The dock can sit at the bottom, at the top, or be hidden. Contributed by Cjreek.
• Nine border styles: rounded, normal, thick, double, hidden, block, ascii, and two half-block variants.
• The window control buttons can be hidden.
• Windows follow the cursor visibility a program asks for, so cmatrix hides the cursor and nvim shows it.

Scrollback

Scrollback moved from a growing slice to a fixed-size ring buffer. The common operations went from O(n) to O(1), which is 10 to 20 times faster once the buffer is full. The size is configurable from 100 to 1,000,000 lines, with a default of 10,000.

Fixed

• Switching workspace during an animation left windows where the animation had reached, sometimes one fullscreen with the rest piled on top. Animations now finish on a switch: the old workspace snaps to its tiled layout at once, and the new one tiles with its usual animation.
• Grid layouts with five or more windows no longer leave dead space at the bottom.
• With the dock at the top, mouse resizing no longer uses boundaries two lines off.
• The parent TERM variable is kept, with xterm-256color as a fallback.
• tuios answers XTWINOPS queries (CSI 14, 16 and 18 t), so programs that ask for the window size in pixels or cells get an answer.
• PTY setup is split into platform-specific files, which fixes the Windows build after Unix-only process attributes broke it.
• Viewport clipping mis-parsed ANSI escapes because of a logical AND that should have been OR.

Project

• Contributor plumbing, mostly from cr2007: issue forms for bugs and feature requests, an auto-labeler, a PR template, a security policy, and README keybindings shown with kbd tags.
• The README notes kitty protocol support, from ShalokShalom.

v0.3.0 was tagged on 5 November 2025. Everything after it builds on the Bubble Tea v2 migration.

Themes

tuios ships over 340 colour themes from bubbletint. Pick one with --theme (the default is tokyonight).

• A theme recolours the programs in your windows too, not only the chrome. A custom SGR handler maps the 16 ANSI colours to the theme's palette, so ls, vim and htop follow it.
• 256-colour and RGB sequences pass through unchanged, so a program that asks for an exact colour still gets it.
• Borders show state: an unfocused window uses the theme's red, a focused window in window mode is bright cyan, and in terminal mode it is bright green.
• --list-themes prints every theme, and --preview-theme shows a theme's 16 ANSI colours with their hex values.

A new PTY layer

Every window runs on a pseudo-terminal, and this release swaps the library that provides it: go-pty out, charmbracelet's xpty in, for a cleaner API and better Windows ConPTY support.

The switch first broke shell startup. Processes no longer got the PTY as their controlling terminal, which shells such as fish need, so windows opened and died at once with exit status 1. The fix, in the same release, sets up the process session and controlling terminal explicitly, as the old library did implicitly.

Changed and fixed

• Windows can no longer be dragged or resized off screen. They stay inside the viewport and out of the dock, which also fixes drawing artifacts at the edges.
• tuios exits cleanly. It handles SIGINT and SIGTERM, and on the way out it turns off mouse tracking, restores the cursor, and leaves the alternate screen, so your shell prompt is intact.
• The README gave two background refresh rates. It now says 30Hz, not 20Hz. Caught by ShalokShalom.
• The Nix packaging workflow now runs on tag pushes, not only on release events, so it runs for every version.

v0.2.0 was tagged on 2 November 2025. Two patch releases followed within days. Their changes are on the v0.3.0 page.

Breaking changes

• The CLI moved from flat flags to subcommands. --ssh became tuios ssh, and the other flags moved the same way.

Scrollback and copy mode

Before this release, text that scrolled off screen was gone, and text on screen could not be copied. Both are fixed.

• Scrollback. Each window keeps 10,000 lines. Enter it with Ctrl+B [ or by scrolling the mouse wheel up, and move with the arrows or vim keys. The upstream VT library had no scrollback, so tuios runs on a fork, and the change was sent upstream as a pull request to charmbracelet/x.
• Copy mode. Vim-style motions: hjkl, word motions, gg and G, count prefixes (10j, 100G), f, F, t and T character search that handles wide characters, / and ? search with highlighted matches, % for bracket matching, and v or V visual selection yanked to the clipboard with y.
• Mouse selection. Click and drag, double-click for a word, triple-click for a line.

Copy mode started as one 2,137-line file and was split into six modules before the tag.

Configuration and the CLI

• A config file. ~/.config/tuios/config.toml is created on first run with comments that document it, and follows XDG. Every keybinding in every mode can be rebound.
• Actions, not code. A key maps to an action name and an action name maps to a handler, so rebinding needs no code change. The help overlay is built from the config, so it shows the keys you actually have.
• Platform defaults. macOS gets opt where Linux gets alt.
• Subcommands. The CLI moved to Cobra, with Fang for help output: tuios runs it, tuios ssh runs the SSH server, and tuios config and tuios keybinds manage the two above. Shell completions and man pages are generated.

The prefix key

Everything hangs off a tmux-style Ctrl+B prefix, which now has submenus:

• w: workspaces (switch to one, or move a window to one)
• m: minimize and restore
• t: window commands
• [: scrollback
• q: quit

A which-key overlay appears after half a second and shows what each submenu offers.

On macOS, Option plus a number types a character such as ¡ or ™ instead of sending a modifier. tuios recognises those characters as workspace switches, and the help text says "Opt" on a Mac and "Alt" elsewhere.

Rendering is 30 times faster

The prototype rendered every cell of every window through a new lipgloss style on every frame. A 13.45-second CPU profile spent 4.85 seconds in renderTerminal. Two changes fixed it:

• A style cache keyed on cell attributes. A hit costs about 99 nanoseconds and no allocations.
• Terminal content is written as ANSI escape codes directly, skipping a style pipeline built for UI boxes. Neighbouring cells with the same style are batched, which cut style renders per frame from about 2,000 to about 50.

After both, renderTerminal took 0.16 seconds in the same profile, and total CPU use fell from 53% to 24%. The input path also stopped clearing the render cache on every keystroke.

An interactive figure goes here. Open the page to use it.

Terminal behaviour

• Mouse events reach programs on the alternate screen, so drag-to-select works in vim, scrolling in less, and clicking in htop.
• Paste works through OSC 52 and bracketed paste, including Cmd+V.
• The alternate screen is detected through VT callbacks instead of guessed.
• nushell no longer clears its own output. The VT library answered cursor position queries with stale coordinates, so tuios now corrects those replies.
• The PTY layer changed twice and ended on charmbracelet/x/xpty, for Windows ConPTY support. The forked VT package is vendored, so plain go install works.
• In tiling mode, swapping, minimizing and retiling only touch windows in the current workspace.

Installing

• GoReleaser builds for Linux, macOS, Windows, FreeBSD and OpenBSD.
• Releases publish to a Homebrew tap and the AUR (tuios-bin), and there is a one-line curl installer.
• The Nix package and devshell were the project's first outside contribution.
• The binary is statically linked, so there is no glibc version to match.
• --ascii-only draws without Nerd Font icons, for machines that do not have one. It was added four days before the tag.

Fixed

• Notifications stayed up for about 17 days instead of 1.5 seconds. A duration already in milliseconds was multiplied by time.Millisecond.
• Comparing cell colours could panic on a nil pointer: a non-nil color.Color interface can hold a nil value. This was the last fix before the tag.
• Typing over SSH did nothing after the restructure, because the input handler was registered for local mode only.
• On macOS, exit did not close the window when the exit message was missed. The tick loop now checks the process directly.
• Visual selection highlighted the empty cells past the end of each line. It now stops at the text.
• Mouse selection in copy mode was off by one row.
• Dragging a window a few pixels no longer corrupts the tiled layout.
• The Windows build compiles again, after resize signalling was split into platform-specific files. Nobody had reported running it there.