TUIOS：懂 Agent 状态的新一代现代终端窗口管理器与多路复用器

TUIOS 是一款使用 Go 语言构建的现代化终端多路复用器（Terminal Multiplexer）与窗口管理器。它在用户现有的终端内运行，提供类 Vim 的模态界面，支持多终端窗格、独立工作区、BSP 二叉树平铺、Kitty 图像协议支持以及命令面板。其后台守护进程不仅可保持会话长久在线、连接其他远程机器上的会话，还能让分布在各窗格中的编码 Agent（Coding Agents）主动汇报自身运行状态并相互发送消息。

TUIOS 基于 Charm 生态技术栈（Bubble Tea v2、Lipgloss v2）打造，采用事件驱动渲染实现几乎为零的空闲 CPU 占用率，提供无闪烁的 Kitty 图像直通传输，并具备完善的键盘与鼠标交互支持。

完整文档可在 tuios.dev（在线版）查阅，或查看本地 docs/ 目录。如需在不安装的前提下体验 TUIOS，可访问 tuios.dev/learn 查看交互式指引：该环境为编译至 WebAssembly 的真实应用，且每个窗格均内置可供实操的 Shell 环境。

v0.8.5 版本的详细更新内容请见发布说明（Release Notes）。

• 入门指引：安装指南与创建首个会话
• 快捷键绑定：默认快捷键与自定义绑定方法
• BSP 平铺布局：支持预选位置与分屏微调的平铺模式
• 布局模式：BSP、主从堆叠（Master-Stack）、滚动布局、聚合视图与多焦点控制
• 配置选项：自定义快捷键、主题与交互行为
• Hooks 钩子机制：针对窗口、会话与 Agent 事件触发自定义 Shell 命令
• 主题定制：内置主题以及基于 JSON 的自定义主题
• 字形集（Glyph sets）：用于绘制界面边框装饰的字符集
• CLI 命令行参考：所有命令行参数与指令详解
• Tape 脚本自动化：工作流录制与自动化方案
• 会话管理：守护进程模式、连接/分离、跨机器协同以及状态恢复
• Agent 协作系统：在 TUIOS 中运行编码 Agent：状态追踪、收件箱、审批流、Agent 集群、跨机器管理、权限授权与 MCP 服务
• tmux 兼容垫片（Shim）：运行依赖 tmux 的外部工具，例如 Claude Code 多 Agent 协作团队
• 控制协议：驱动后台守护进程的 JSON 动词交互协议
• 架构设计：技术架构与底层实现原理

目录

Homebrew (macOS/Linux):

Homebrew，ghostty 构建版（仅限 Linux）： 采用 libghostty-vt 终端模拟器内核 构建的 tuios，替代原 tuios cask。

brew install gaurav-gosain/tap/tuios-ghostty

Arch Linux (AUR):

Nix:

nix run github:Gaurav-Gosain/tuios/v0.8.5#tuios   # 指定正式版本
nix run github:Gaurav-Gosain/tuios#tuios          # main 分支最新版
nix run nixpkgs#tuios                             # nixpkgs 官方源

在代码仓库名称后添加发布标签即可构建对应版本。若不带标签，Nix 将直接构建 main 分支的最新提交。

# 快速安装脚本 (Linux/macOS)
curl -fsSL https://raw.githubusercontent.com/Gaurav-Gosain/tuios/main/install.sh | bash

# Go 安装方式
go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest

# Docker 容器镜像
docker run -it --rm ghcr.io/gaurav-gosain/tuios:latest

GitHub Releases：提供针对 Linux、macOS、Windows、FreeBSD 与 OpenBSD 平台的预编译二进制程序，并附带 checksums.txt 校验文件。其中 tuios-ghostty_* 压缩包为基于 libghostty-vt 模拟器 构建的特定版本，支持 Linux、macOS 与 Windows 的 amd64/arm64 架构。

源码构建环境要求：Go 1.26.6 或更新版本。

更新机制：若使用快速安装脚本或 Release 二进制程序安装，运行 tuios update 会自动拉取最新版本并就地更新（tuios update --check 仅用于检查版本）。若是通过其他系统包管理器安装，程序将交由包管理器负责更新；tuios update 会自动识别并输出适用的包管理器更新命令，避免直接覆盖二进制文件。

运行需求：支持 True Color（真彩色）的终端。推荐使用支持 Kitty 图像协议与 Sixel 协议的终端（如 Ghostty、Kitty、WezTerm）。

• 多终端窗格：自由创建、缩放、拖拽和组织各类终端会话
• 9 个独立工作区：完全隔离的工作区设计，支持毫秒级瞬时切换
• 模态交互界面：汲取 Vim 灵感设计的窗口管理模式（WM mode）与终端输入模式
• 命令面板（Command Palette）：支持模糊搜索的全局操作启动器（Ctrl+P）
• 应用启动器（Launcher）：通过模糊搜索检索环境变量 $PATH 上的全部可执行程序及已安装的桌面端应用（Alt+Space），按用户实际运行频次（Frecency）智能排序。按 Enter 直接启动；按 Tab 打开终端并预填入命令但不执行，方便用户追加自定义参数。在支持 Kitty 图像协议的终端中还可直接渲染应用图标。
• 窗格缩放（Pane Zoom）：在 WM 模式下按 z 或使用组合键 Prefix+z 即可快速放大任意窗格。默认占用 95% 的屏幕面积；设置 appearance.zoom_size = 100 可切换为全屏放大。全屏放大时将隐藏共享边框，底部的停靠栏（Dockbar）会显示 Z 状态指示符。
• 会话导航轨（Session Rail）：侧边栏整合展示所有会话、终端、文件列表、Git 状态与 Agent 运行情况，默认固定在界面右侧开启（appearance.sidebar.enabled）
• 应用设置面板：在软件内通过 Prefix+, 快捷键直接调整配置项
• 弹出窗口（Popups）：通过 tuios popup -- fzf 即可在浮动窗口中执行指定命令，进程退出时弹窗自动关闭

完整开发与使用指引详见 docs/AGENT_STATE.md。

• Agent 状态感知：运行编码 Agent 的窗格会在标题栏显示几何图标，并在侧边轨中展示独立行，直观呈现其正在工作、等待用户输入、已完成或报错等状态。通过 tuios integration install 可一键接入 19 种主流执行框架（如 Claude Code、Codex、Gemini CLI、opencode 等）的状态上报；此外 TUIOS 还能够通过进程树与屏幕特征自适应识别 24 种 Agent CLI 命令行工具

• 统一收件箱（Inbox）：按下 Prefix+i 集中列出跨全部会话与跨远程机器等待人工处理的全部事项：操作审批、提问交互、邮件、异常错误与已完成轮次。按 Prefix+o 直接定位至最久未处理的事项。无需跳转切入窗格即可就地回复 Prompt；结合 [agents.approvals] 配置，还可一键审批来自 Claude Code、opencode、Kilo 以及 Qwen Code 的权限申请

• 提问与消息通信：tuios ask-human 可向用户的统一收件箱发送带固定候选选项的选择题。Agent 之间可通过 tuios send-agent-message 互相收发邮件，或使用 tuios ask-agent 发起同步咨询并等待回复。该机制绝不会误输入到正在等待 Prompt 输入的活动窗格中，来自人类用户的答复会自动标记为已验证状态

• Agent 任务分发（Fleets）：tuios fan 可将同一条 Prompt 同时扇出给多个 Agent 并行处理，支持混合搭配不同底层框架，且每个 Agent 均运行在独立的 Git Worktree 中。tuios start-agent 可在当前窗格旁拉起一个辅助 Agent，支持以内置 TUI 模式或通过 ACP / Codex 应用服务器以无头（Headless）模式运行。可使用如 group:fan/retry needs:you 等选择器批量筛选并调度整个 Agent 组群

• 断点接续（Resume）：后台守护进程重启后，统一收件箱会主动提示是否恢复中断前正在执行的各个 Agent 对话任务

• 窗格细粒度授权（Pane Grants）：明确界定某个 Agent 所在窗格可调用的 TUIOS 功能权限（read、write、fan、respond、admin），并可通过 --grants 为辅助 Agent 分配最小特权

• MCP 服务端：tuios mcp 将同等操作面板暴露为标准 MCP 工具，在未明确额外放权的情况下，默认严格保持只读权限并限制仅可访问 Agent 自身所属的会话

• tmux 兼容垫片：tuios tmux-shim 支持运行原本驱动 tmux 的外部自动化工具（例如 Claude Code agent teams 多 Agent 团队模式），并将对应的窗口窗格无缝桥接并在 TUIOS 窗格中打开

• 会话暂存区（Session Stash）：通过 tuios stash put 可在当前会话中暂存持久化文件，供其他 Agent 随时调取查阅

• Agent Skills 指南：tuios --skill 可输出一份精炼的操作手册，供窗格内的 Agent 快速学习如何驱动 TUIOS；tuios --skill TOPIC 则可按需查询特定主题的高阶技巧与实战用法

• 远程主机管理：tuios hosts add 可通过 SSH 别名添加远程主机。tuios hosts tailnet 可列出当前 Tailscale 虚拟局域网内的全部设备

• 远程会话挂载：tuios attach --host build api 可在本地客户端中直接渲染并在操作远端机器上的会话，通过 -s HOST:SESSION 能够直接向指定远程主机会话分发指令

• 远端承载窗格（Hosted Panes）：tuios new-window NAME --host build 允许将单个窗格的计算进程托管至远端机器执行，同时将其统一编排在本地当前会话中

• 全局会话（Global Sessions）：tuios new NAME --global 可创建跨越多台物理/虚拟主机的聚合窗格会话（详见官方文档）

• 跨机器调度 Agent：通过 tuios fan --host build 以及 tuios start-agent -s build:api 可以在远程主机上跑 Agent，其收件箱事件会直接汇聚至本地呈现，执行 tuios worktree pull 即可同步回传远端代码成果。每台机器均可通过 [hosts] 配置策略精细管控其他机器的访问权限

• BSP 平铺：采用二叉空间分割（Binary Space Partitioning）机制，支持螺旋式排布布局

• 滚动式布局：类似于 niri 风格的无限横向画卷式多列流转布局（详见官方文档）

• 主从堆叠布局（Master-Stack）：单主窗格占据核心显示区，辅助窗格在侧边自动堆叠展示

• 智能自动分屏：基于屏幕长宽比智能判定切分方向（默认需主动启用）

• 共享边框：支持类似 tmux 的窗格间极简单线分割边框（--shared-borders）

• 分屏预选（Preselection）：允许预先圈定下一个新创建窗格的具体生成朝向与位置

• 分屏重置居中：一键重置当前所有平铺切分比例，恢复均匀对齐状态

• Vim 风格复制模式：支持通过 hjkl 自由浏览多达 10,000 行的回滚历史缓存，支持 / 向下搜索、? 向上搜索，使用 y 复制选中内容

• 多窗格并发复制模式：可同时在处于多焦点（Multifocus）状态的多个窗格中同步进入复制模式。只需输入一次搜索条件，即可分别使用 v/V 在各窗格进行选区，并将全部选中内容一并复制为纯文本、Markdown 或 JSON 格式，直接存入系统剪贴板或指定文件（详见官方文档）

• 鼠标滚轮即时回滚：滑动鼠标滚轮即可直接查看历史回滚内容，无需显式切换模态；恢复键盘输入或滚动至底部即可立即回归实时输出流

• 交互式滚动条：支持直接点击或拖动右侧窗格边框快速跳至对应滚动进度

• 拖拽自动滚屏：当文本选中范围拖曳超出窗格上/下边界时，触发视口自动滚动

• 回滚历史结构化浏览：支持基于 OSC 133 协议特征识别命令行与命令输出块并精准跳转定位

• 滚动坐标指示器：在窗格底部边框直观提示当前的行偏移量及总历史行数

• Kitty Graphics 图像协议：支持完整的图像渲染与无闪烁的流畅视频播放。已验证支持 mpv --vo=kitty（含 shm 共享内存与 base64 模式）以及 youterm

• Sixel 图形协议：实验性支持 Sixel 格式图像直通（暂未提供像素级精确裁剪）

• Kitty Keyboard 键盘协议：支持渐进增强协议规范（CSI u），含 push/pop/query 栈操作能力。完全兼容 Fish 4.x；Shift+可打印字符将直接绕过该协议作为常规文本发送

• 同步输出机制（Synchronized Output）：原生支持 Mode 2026 同步输出协议，彻底消除高频刷新时的终端画面撕裂

• 共享内存加速支持：为 mpv --vo-kitty-use-shm 等命令提供极速直通传输的 t=s 共享内存通道

• 动画增量帧转发：终端内部子程序的 a=f 动画单帧改动将被直接转交宿主终端渲染，实现应用程序就地修补图像局部矩阵，开销远低于传输整张位图。TUIOS 还会为仅支持全量重传的子程序自动计算并传输增量 Patch。窗格会通过环境变量 TUIOS_KITTY_ANIMATION 感知宿主是否支持帧编辑，避免由于宿主应答未下发导致子程序无法自主决策的问题

• 终端属性查询协议：完整支持 OSC 4 色板、OSC 10-12 前后景色、CSI 14/16/18t 尺寸查询以及 DA1/DA2 设备属性回显

• 实验性特性：Kitty 文本尺寸协议（OSC 66）。基础直通功能已可用，但已知在历史回滚与窗口重排场景下仍存边界问题

• Kitty 动画协议全支持：包含图像帧传输、合成以及控制时序（a=f、a=a、a=c），并提供面向动态渲染子程序的损坏补丁流（Damage-Patch Streaming）

• 守护进程服务：如同 tmux 一样支持随时断开连接（Detach）与重连（Reattach）的长生命周期会话机制

• 会话复活恢复：守护进程重启或整机重启后，所有会话可自动复原原有的窗口组织拓扑与对应工作目录（详见官方文档）

• 会话快捷切换器：在应用内按 Prefix+S 调出全局会话导航抽屉

• 布局模板归档：支持将窗格排列方式、初始工作目录及自启动脚本保存为模板并随时加载

• 布局管理 CLI：提供 tuios layout list、tuios layout delete 与 tuios layout export 维护指令

• Tape 录制自动化脚本：提供专门用于录制与回放终端交互工作流的专用 DSL

• 会话实时录制：通过 Prefix+T r 即可原地录制当前会话的交互操作过程

• 无头模式自动化执行：tuios tape exec 允许向后台运行中的守护进程直接派发并执行 Tape 自动化脚本

• 布局导出转脚本：支持一键将当前界面窗口拓扑转换为 Tape 脚本，方便团队间分发共享

• Which-Key 辅助快捷键浮窗：按住前缀键（Prefix）即可实时弹出浮窗列出当前可用的全部后续快捷键组合（由 appearance.whichkey_enabled 控制，详见官方文档）

• 全局应用启动器：通过 Alt+Space 模糊检索环境变量 $PATH 中的命令，基于 Frecency 综合排序，完整解析桌面 Desktop Entry 名称与图标

• 快捷键映射诊断器：在应用内按 Prefix+k，或在系统 Shell 中执行 tuios keybinds doctor 与 tuios keybinds explain <key> 快速排查按键冲突

• 全景聚合视图（Aggregate View）：以可检索的列表一览跨所有工作区的全部窗口实体，并附带动态实时缩略预览（详见官方文档）

• 多焦点并发广播（Multifocus）：支持将键盘输入同时广播分发至多个窗格，通过 Ctrl+Shift+鼠标点击即可直接圈选目标窗格集合（详见官方文档）

• 按键回显浮层（Showkeys Overlay）：在屏幕上同步渲染实时按键键位，专为会议演示与教学场景打造

• 聚光灯功能（Spotlight）：高亮聚焦屏幕核心操作区域并压暗其他背景窗格，适合视频录屏与演示讲解（通过 [spotlight] 配置表调整）

• 窗格截图工具：通过 tuios screenshot 命令可直接将指定窗格导出保存为 PNG、SVG、ANSI 转义码、HTML 网页或纯文本内容

• 自定义停靠栏组件（Dock Components）：支持在界面 Dock 栏嵌入用户自定义命令输出，可通过系统事件、持续运行进程或定时轮询方式实时刷新渲染（详见组件示例）

• 高度自定义的快捷键体系：通过 TOML 格式配置文件自由映射快捷键与行为

TUIOS is a modern terminal multiplexer and window manager built with Go. It provides a vim-like modal interface with multiple terminal panes, workspaces, BSP tiling, kitty graphics protocol support, and a command palette, all running inside your existing terminal. A daemon keeps sessions alive, reaches sessions on your other machines, and lets the coding agents in your panes report their state and message each other.

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

Full documentation is available at tuios.dev (hosted) or in the docs/ folder. To try tuios without installing it, take the guided tour at tuios.dev/learn : the real app, compiled to WebAssembly, with a practice shell in every pane.

What changed in v0.8.5 is in the release notes.

• Getting Started : Install and first session
• Keybindings : Default keys and how to rebind them
• BSP Tiling : Tiling with preselection and split control
• Layout Modes : BSP, master-stack and scrolling layouts, aggregate view, multifocus
• Configuration : Customize keybindings, themes, and behavior
• Hooks : Run shell commands on window, session and agent events
• Themes : Built-in themes and custom theme JSON
• Glyph sets : The characters the chrome is drawn with
• CLI Reference : All command-line options
• Tape Scripting : Automate workflows
• Sessions : Daemon mode, attach/detach, other machines, and what survives
• Agents : Running coding agents in tuios: state, the Inbox, approvals, fleets, other machines, grants and MCP
• tmux Shim : Run tools that drive tmux, such as Claude Code agent teams
• Control Protocol : JSON verb protocol for driving the daemon
• Architecture : Technical design

Table of Contents

Homebrew (macOS/Linux):

Homebrew, ghostty build (Linux only): tuios built with the libghostty-vt emulator. It replaces the tuios cask.

brew install gaurav-gosain/tap/tuios-ghostty

Arch Linux (AUR):

Nix:

nix run github:Gaurav-Gosain/tuios/v0.8.5#tuios   # a release
nix run github:Gaurav-Gosain/tuios#tuios          # the latest main
nix run nixpkgs#tuios                             # the nixpkgs package

Put a release tag after the repo name to build that release. Without a tag, Nix builds the newest commit on main.

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

# Go install
go install github.com/Gaurav-Gosain/tuios/cmd/tuios@latest

# Docker
docker run -it --rm ghcr.io/gaurav-gosain/tuios:latest

GitHub Releases : Pre-built binaries for Linux, macOS, Windows, FreeBSD and OpenBSD, with a checksums.txt. The tuios-ghostty_* archives are tuios built on the libghostty-vt emulator, for Linux, macOS and Windows on amd64 and arm64.

Building from source needs Go 1.26.6 or newer.

Updating. If you installed with the quick install script or a release binary, tuios update fetches the newest release and puts it in place (tuios update --check just reports). Everything else has a package manager that owns the binary, so use that instead; tuios update detects which you have and prints the right command rather than overwriting it.

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

• Multiple Terminal Panes : Create, resize, drag, and organize terminal sessions
• 9 Workspaces : Independent workspace isolation with instant switching
• Modal Interface : Vim-inspired Window Management and Terminal modes
• Command Palette : Fuzzy-searchable action launcher (Ctrl+P)
• Launcher : Fuzzy search everything on $PATH plus your installed desktop apps (Alt+Space), ranked by what you actually run. Enter starts it; Tab opens a shell with the command typed but not entered, so you can add arguments. App icons are drawn where the terminal supports kitty graphics.
• Pane Zoom : Zoom any pane with z (WM mode) or Prefix+z. It takes 95% of the screen by default; set appearance.zoom_size = 100 for fullscreen. A fullscreen zoom hides the shared borders, and the dockbar shows a Z indicator.
• Session Rail : A sidebar with sessions, terminals, files, git state and agents, on by default on the right (appearance.sidebar.enabled)
• Settings Page : Change options in the app with Prefix+,
• Popups : tuios popup -- fzf runs a command in a floating pane that closes when it exits

The guide is docs/AGENT_STATE.md.

• Agent State : Panes running a coding agent show whether it is working, waiting for you, done or errored, as a shape in the title and a row on the rail. tuios integration install wires 19 harnesses (Claude Code, Codex, Gemini CLI, opencode and more) to report it, and tuios detects 24 agent CLIs by their process and screen

• Inbox : Prefix+i lists everything waiting for you in every session and on every machine: approvals, questions, mail, errors, finished turns. Prefix+o jumps to the oldest. Answer a prompt from there without going to the pane, and with [agents.approvals] answer Claude Code, opencode, Kilo and Qwen Code permission requests with one key

• Questions and Messages : tuios ask-human puts a question with fixed answers in your Inbox. Agents mail each other with tuios send-agent-message, and tuios ask-agent asks one and waits for its answer. It never types into a pane waiting on a prompt, and replies from you are marked verified

• Fleets : tuios fan starts one prompt in several agents, mixed harnesses allowed, each in its own git worktree. tuios start-agent starts one helper beside you, in its TUI or headless over ACP or the Codex app-server. Selectors such as group:fan/retry needs:you address a whole group

• Resume : After a daemon restart, the Inbox offers to resume each agent conversation that was running

• Pane Grants : Say what an agent's pane may do through tuios (read, write, fan, respond, admin), and give a helper less with --grants

• MCP Server : tuios mcp serves the same surface as MCP tools, read-only and held to the agent's own session unless you say otherwise

• tmux Shim : tuios tmux-shim runs tools that drive tmux, such as Claude Code agent teams, with their panes opened as tuios panes

• Session Stash : tuios stash put keeps a file for the session, so another agent can still open it

• Agent Skill : tuios --skill prints the short guide an agent in a pane reads to drive tuios, and tuios --skill TOPIC the rest, recipes included

• Hosts : tuios hosts add names another machine, reached over ssh. tuios hosts tailnet lists the machines on a Tailscale tailnet

• Remote Sessions : tuios attach --host build api draws a session on another machine in this client, and -s HOST:SESSION sends any command there

• Hosted Panes : tuios new-window NAME --host build runs one pane's process on another machine, in a session here

• Global Sessions : tuios new NAME --global holds panes from several machines (docs)

• Agents on Other Machines : tuios fan --host build and tuios start-agent -s build:api run agents there, their Inbox items show here, and tuios worktree pull brings their work back. Each machine's [hosts] policy says what the others may do

• BSP Tiling : Binary Space Partitioning with spiral layout

• Scrolling Layout : niri-style columns on an infinite horizontal strip (docs)

• Master-Stack Layout : One master pane with the rest stacked beside it

• Smart Auto-Split : Aspect-ratio-aware splitting (opt-in)

• Shared Borders : tmux-style separator lines between panes (--shared-borders)

• Preselection : Control where the next pane spawns

• Equalize Splits : Reset all splits to balanced ratios

• Vim-Style Copy Mode : Navigate 10,000-line scrollback with hjkl, search down with / and up with ?, yank with y

• Multi Copy Mode : Copy mode on every pane of the multifocus set at once. Search once, select with v/V in each pane, and yank all selections as plain text, markdown or JSON, to the clipboard or a file (docs)

• Mouse Wheel Scrollback : The wheel scrolls history with no mode entered; typing or reaching the bottom returns to live output

• Interactive Scrollbar : Click or drag the right border to jump to scroll position

• Selection Auto-Scroll : Drag selection above/below pane to scroll

• Scrollback Browser : OSC 133-aware command/output block navigation

• Scroll Position Indicator : Shows offset/total on the bottom border

• Kitty Graphics Protocol : Full image rendering with flicker-free video playback. mpv --vo=kitty works (both shm and base64), and youterm works.

• Sixel Graphics : Sixel image passthrough (experimental, no pixel-level clipping yet)

• Kitty Keyboard Protocol : Progressive enhancement (CSI u) with push/pop/query support. Fish 4.x compatible; Shift+printable bypasses the protocol and sends text directly.

• Synchronized Output : Mode 2026 prevents screen tearing

• Shared Memory Support : t=s passthrough for mpv --vo-kitty-use-shm

• Animation Frames : A guest's a=f frame edits are forwarded to the host, so a program that patches its own image costs a rectangle instead of a whole bitmap. TUIOS also patches guests that only retransmit. Panes are told whether the host carries frame edits through TUIOS_KITTY_ANIMATION, because the host's reply is not relayed back into the pane and a guest cannot find out for itself.

• Terminal Queries : OSC 4 palette, OSC 10-12 colors, CSI 14/16/18t sizing, DA1/DA2

• Experimental : Kitty text sizing protocol (OSC 66). Basic passthrough works but has known issues with scrollback and window repositioning

• Kitty Animation Protocol : Frame transmission, composition, and control (a=f, a=a, a=c), with damage-patch streaming for animated guests

• Daemon Mode : Persistent sessions with detach/reattach (like tmux)

• Session Resurrection : Sessions come back after a daemon restart or reboot with their structure and working directories (docs)

• Session Switcher : In-app session list (Prefix+S)

• Layout Templates : Save/load window arrangements with working directories and startup commands

• Layout CLI : tuios layout list, tuios layout delete, tuios layout export

• Tape Scripting : DSL for recording and replaying terminal workflows

• Tape Recording : Record live sessions (Prefix+T r)

• Headless Execution : tuios tape exec runs a tape against a running daemon session

• Layout Export : Convert layouts to tape scripts for sharing

• Which-Key Popup : Hold the prefix key to see the chords available (appearance.whichkey_enabled, docs)

• App Launcher : Alt+Space runs anything on $PATH, frecency-ranked, with desktop-entry names and icons

• Keybind Manager : Prefix+k in-app, or tuios keybinds doctor and tuios keybinds explain <key> from the shell

• Aggregate View : Searchable list of every window across every workspace, with previews (docs)

• Multifocus : Broadcast typing to several panes at once, Ctrl+Shift+click to select (docs)

• Showkeys Overlay : Display pressed keys for presentations

• Spotlight : Light one area of the screen and dim the rest, for demos and recordings ([spotlight] config table)

• Screenshots : tuios screenshot renders a pane to PNG, SVG, ANSI, HTML or text

• Dock Components : Your own commands drawn in the dock, updated on events, from a running command, or by polling (examples)

• Customizable Keybindings : TOML configuration with Kitty protocol support

• Hooks : Run shell commands on ten events, including window, workspace, attach and agent state changes (docs)

• Mouse Support : Wheel scrollback, drag-to-select with copy on release, double-click word and triple-click line, window drag, resize, scrollbar

• SSH Server Mode : Remote terminal multiplexing

• Web Terminal Mode : Browser-based access (separate tuios-web binary)

• Themes : Bundled themes plus custom themes from JSON, with chrome designed for truecolor, 256 and 16 colours and for light themes (docs)

• Host Colours : tuios asks your terminal for its colours, passes them to programs that ask, and follows its light and dark switch

• Backgrounds : appearance.background paints empty cells with the theme's background or a colour of your own, per surface if you like

• Motion : appearance.motion is none, basic or full (fades, the working shimmer, confetti)

• Glyph Sets : Choose the characters the chrome is drawn with (docs)

  tuios # Launch TUIOS tuios --show-keys # Launch with key overlay for learning tuios --standalone # Launch without the daemon, for this run only

tuios attaches to a daemon-backed session, so the session outlives the terminal window it started in. New panes are tiled. See SESSIONS.md to turn either off.

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

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


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

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


tuios config edit            # Edit config in $EDITOR
tuios keybinds list          # View the common keybindings

See the configuration reference (or run tuios list-options) for all options including show_clock, show_cpu, show_ram, shared_borders, window_button_style, window_button_position, custom themes, and keybinding customization.

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

Key design decisions:

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

Core Components:

• Event-driven rendering : Zero CPU at idle. Renders only when PTY data arrives or interaction occurs.

• Kitty graphics : Flicker-free via image ID reuse. Tearing-free via mode 2026 sync + render cycle batching.

• Fast unfocused render : Unfocused panes use emulator's built-in Render() instead of cell-by-cell, unless appearance.dim_unfocused needs each cell.

• Style caching : LRU cache with sequence-based change detection (40-60% allocation reduction).

• Viewport culling : Off-screen and minimized panes skip rendering.

• Memory pooling : Pooled strings, buffers, and styles.

  git clone https://github.com/gaurav-gosain/tuios.git cd tuios go build -o tuios ./cmd/tuios ./tuios

To install a local build on your PATH instead, ./scripts/install.sh builds and installs into ~/.local/bin. It builds the pure Go emulator. ./scripts/install.sh ghostty builds the ghostty emulator backend instead, and tuios --version says which is installed.

go test ./...              # Run tests
go vet ./...               # Vet
golangci-lint run          # Lint with the checks CI runs (.golangci.yml)
govulncheck ./...          # Known vulnerabilities in what the build reaches

Support:

MIT License. See LICENSE for details.

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