TUIOS: A terminal window manager for persistent sessions shared with coding agents
TUIOS manages panes and coding agents for terminal developers, with daemon sessions and an Agent Inbox spanning machines.
GitHub Gaurav-Gosain/tuios Updated 2026-10-06 Branch main Stars 4.8K Forks 213
Go Terminal Multiplexing BSP Tiling Bubble Tea v2 Coding Agents SSH/Tailscale

🧭 Decision Guide

Why trending now: 无法从材料判断

Try it if you

  • You need BSP Tiling, workspaces, and vim-like modal operations to manage multiple terminal panes.
    The README's Features and Quick Links list BSP Tiling, workspaces, Keybindings, and Layout Modes.
  • You run coding agents and want to centralize state through the Agents Inbox, approvals, or Fleets.
    The README's Agents link explicitly lists state, Inbox, approvals, fleets, grants, and MCP.
  • You need Sessions to survive terminal-window closure or want to access sessions on other machines through SSH.
    Quick Start says daemon-backed sessions outlive the terminal window; the Machines section provides tuios attach --host.
  • You want to try the real TUIOS interface and practice shell without installing it.
    The Documentation section says tuios.dev/learn provides the real app compiled to WebAssembly with a practice shell in every pane.

Skip it if you

  • Your terminal lacks true-color support, while the project's Requirements explicitly require true color.
    The README's Requirements says: A terminal with true color support.
  • Your build environment is older than Go 1.26.6 and you plan to build from source.
    The README Installation section says Building from source needs Go 1.26.6 or newer.
  • You only need a one-off terminal run without a daemon but still expect the default persistent Session behavior.
    Quick Start says the default connects to a daemon; only tuios --standalone is defined as running without the daemon.
  • Your workflow must directly support tools that drive tmux, and you do not want to use TUIOS's tmux Shim.
    The README lists tmux Shim as a compatibility layer for tools that drive tmux, such as Claude Code agent teams.

Requirements

  • The terminal must support true color.
  • Kitty graphics and sixel support are recommended, with Ghostty, Kitty, or WezTerm named in the README.
  • Building from source requires Go 1.26.6 or newer.
  • GitHub Releases provide pre-built binaries for Linux, macOS, Windows, FreeBSD, and OpenBSD.
  • For remote-host features, the README uses SSH to reach other machines; Tailscale tailnet machines can be listed with tuios hosts tailnet.

First step (verbatim from README)

tuios --show-keys

Watch out

  • The installation method affects updates: tuios update replaces installations from the quick install script or release binaries, while package-manager installations remain package-manager-owned.
    The README Installation section, Updating, states the supported scope of tuios update.
  • On Linux, the Ghostty build uses the libghostty-vt emulator and requires tuios-ghostty or ./scripts/install.sh ghostty.
    The README Installation and Development sections describe the Homebrew Ghostty build and ./scripts/install.sh ghostty.
  • The default daemon keeps a Session alive after its original terminal window closes; use --standalone for a single run without the daemon.
    Quick Start says the session outlives the terminal window and lists tuios --standalone.
  • Graphics display depends on terminal protocols: Kitty graphics and sixel are recommended, and Kitty passthrough uses mode 2026 synchronization.
    The README Requirements and Architecture sections on Kitty graphics passthrough.

Alternatives

  • tmux：tmux is more direct when existing tools explicitly drive tmux and you do not need TUIOS Agents Inbox, BSP Tiling, or daemon-backed session UI.
    README section: tmux Shim

Not stated in the README

  • The README does not state which agent products or versions are supported.
  • The README does not describe authentication, encryption, or failure recovery for daemon connections across machines.
  • The README provides no measured CPU, memory, or startup-latency numbers; Performance only describes zero CPU at idle, style caching, and viewport culling.
  • The README does not describe feature differences or terminal requirements on Windows, FreeBSD, and OpenBSD.
  • The README does not state the release cadence, maintainer response time, or support commitment associated with 10 contributors and 5 releases.
  • The README does not provide complete configuration examples for Tailscale tailnets, SSH host policies, or Agent grants.

💡 Deep Analysis

6
Yes I build tools with Go and Bubble Tea v2, want to modify TUIOS window management, input routing, or rendering, and need JSON control protocols and Hooks for automation. Is this project a suitable extension base?
For: An open-source maintainer familiar with Go and Bubble Tea v2 who wants to extend a terminal window manager with automation interfaces

Yes, because the implementation language, UI framework, component boundaries, and automation entry points directly match this extension goal. The concrete evidence is:
- The Architecture section says TUIOS uses Bubble Tea v2 with the Model-View-Update pattern and separates window management, terminal emulation, rendering, and input.
- The project is primarily Go, and the README provides commands for build, tests, vet, lint, and govulncheck.
- The Control Protocol provides a JSON verb protocol, Hooks can react to window, session, and agent events, and Tape Scripting supports workflow automation.
- The README does not promise stable internal package APIs or describe protocol-versioning policy. A direct first step is:
git clone https://github.com/gaurav-gosain/tuios.git

  • Architecture: TUIOS follows the Model-View-Update pattern on Bubble Tea v2
  • Architecture: Core Components include Window Manager, Terminal Emulation, Rendering, and Input
  • Control Protocol: JSON verb protocol for driving the daemon
  • Hooks: Run shell commands on window, session and agent events
  • Development: go build -o tuios ./cmd/tuios; go test ./...
git clone https://github.com/gaurav-gosain/tuios.git
Not stated in the README：The README does not say whether internal packages are intended for external dependencies.；It does not define version-compatibility policy or error semantics for the JSON control protocol.；It does not provide a complete guide for adding new layouts or agent adapters.
Yes I run multiple Claude Code agent teams in parallel, need visibility into each agent’s state, messages, and approvals, and must keep tools that drive tmux working. Is TUIOS suitable as a replacement for my current terminal window management?
For: An individual developer running parallel Claude Code agent teams who must retain compatibility with tmux-driven tools

Yes, because TUIOS combines agent observability with tmux compatibility instead of offering only ordinary terminal tiling. The relevant facts are:
- The Agents documentation lists state, Inbox, approvals, fleets, grants, and MCP, which directly match centralized monitoring of several agents.
- The tmux Shim documentation explicitly supports tools that drive tmux and specifically mentions Claude Code agent teams.
- The README connects daemon-backed sessions, agent messaging, and pane-level workflows, so agents can continue after the terminal window is closed.
- However, the README does not define compatibility limits for every Claude Code version, every agent-team operation, or every approval protocol. A practical first command is:
tuios --show-keys

  • Agents: state, the Inbox, approvals, fleets, other machines, grants and MCP
  • tmux Shim: Run tools that drive tmux, such as Claude Code agent teams
  • Quick Start: tuios attaches to a daemon-backed session, so the session outlives the terminal window it started in
  • Project data: topics include claude-code, codex, coding-agents, and tmux-alternative
tuios --show-keys
Not stated in the README：The README does not provide a compatibility matrix for Claude Code versions and agent-team features.；The README does not specify the complete protocol requirements for third-party agent state, approvals, and MCP integration.
Yes I manage multiple repositories, service processes, and test tasks at the same time, already use Vim-like modal interaction, and want to switch among BSP, master-stack, and scrolling layouts. Is TUIOS more suitable for me than ordinary terminal tabs?
For: A CLI user managing multiple repositories, service processes, and test tasks daily, relying on Vim-like keys and BSP, master-stack, and scrolling layouts

Yes, because your workflow directly matches TUIOS’s spatial organization and keyboard interaction model. Specifically:
- Features include BSP tiling, scrolling layout, master-stack layout, preselection, and equalize splits, allowing panes to be arranged around task relationships.
- The README describes a vim-like modal interface and provides a command palette, keybindings, and mouse interaction.
- The Input component contains 100+ configurable keybindings; users already familiar with Vim should face less migration friction than ordinary terminal users.
- A daemon-backed session keeps running after the terminal window closes, which fits long-lived services and tests. However, the README also shows that standalone mode does not provide the full daemon session lifecycle. Start with:
tuios --show-keys

  • Features: BSP Tiling, Scrolling Layout, Master-Stack Layout, Preselection, and Equalize Splits
  • README quote: It provides a vim-like modal interface with multiple terminal panes, workspaces, BSP tiling
  • Architecture: Input with 100+ configurable keybindings
  • Quick Start: the session outlives the terminal window it started in
  • Project insight, common_pitfalls: standalone is suitable for temporary runs but lacks the full daemon session lifecycle
tuios --show-keys
Not stated in the README：The README does not state the maximum number of panes or tasks a workspace can reliably handle.；It does not quantify the readability or memory impact of output from many concurrent services.；It does not provide an automatic converter for existing tmux or terminal-tab layouts.
It depends I frequently inspect CLI output containing images and require kitty graphics or sixel, scrollback, mouse selection, and Vim-like copy mode together. Can TUIOS replace a conventional terminal multiplexer?
For: An advanced terminal user who depends on kitty graphics, sixel, scrollback, and Vim-like copy mode

It depends: TUIOS explicitly implements these terminal capabilities, but the final result depends on the outer terminal emulator and its protocol support, so the feature list alone cannot guarantee compatibility. The facts are:
- The terminal-emulation component supports ANSI, scrollback, kitty/sixel graphics, the kitty keyboard protocol, and OSC 133.
- Copy mode provides full Vim-style navigation over scrollback, while mouse scrolling and selection reuse the same machinery.
- The Performance section describes kitty image ID reuse, mode 2026 synchronization, and batched rendering to reduce flicker and tearing.
- The project insight notes that kitty graphics and sixel coverage varies between terminals; the README does not provide a terminal compatibility matrix. Start with:
tuios --show-keys

  • Architecture: Terminal Emulation supports an ANSI parser with scrollback, kitty/sixel graphics, the kitty keyboard protocol, and OSC 133
  • Architecture: Copy mode provides full Vim navigation over scrollback
  • Performance: Flicker-free via image ID reuse; tearing-free via mode 2026 sync
  • Project insight, common_pitfalls: the terminal needs good true-color support, and kitty graphics and sixel depend on terminal capabilities
tuios --show-keys
Not stated in the README：The README does not list a compatibility matrix for specific outer terminals, terminal backends, and kitty/sixel features.；It does not describe bandwidth, latency, or failure behavior for image forwarding over SSH.；It does not specify resource limits for very large scrollback buffers or video-like output.
It depends I access other machines through SSH and need builds and coding agents to keep running on remote hosts after my local terminal closes or the SSH connection drops. Can TUIOS satisfy this requirement?
For: An engineer running long-lived builds and coding-agent tasks across multiple machines accessed through SSH, requiring recovery after disconnection

It depends: TUIOS’s persistent-session and remote-session model matches the requirement, but reliable remote execution still depends on SSH, the target environment, and agent integration. The evidence is:
- The Sessions documentation explicitly covers daemon mode, attach/detach, other machines, and what survives.
- The README says the daemon keeps sessions alive and can reach sessions on other machines, which fits reconnecting after an SSH interruption.
- The project insight identifies host configuration, permissions, target-machine runtime, network interruptions, and version differences as factors affecting remote control.
- The supplied README does not state minimum remote operating systems, authentication details, agent deployment steps, or exact reconnect semantics, so it cannot guarantee every remote setup. Start with:
tuios

  • Sessions: Daemon mode, attach/detach, other machines, and what survives
  • README quote: A daemon keeps sessions alive, reaches sessions on your other machines
  • Project insight, usage_limitations: cross-machine support does not automatically solve code synchronization, credentials, network security, or build-environment consistency
  • Quick Start: tuios attaches to a daemon-backed session
tuios
Not stated in the README：The README does not specify SSH authentication, host-configuration format, or which components must be installed remotely.；It does not explain how agent state updates behave during an SSH outage or whether remote sessions are compatible across versions.；It does not define remote code synchronization, credential forwarding, or network-security boundaries.
It depends I need the same TUI workspace across Linux, macOS, Windows, FreeBSD, or OpenBSD, and want Go-based single-binary builds to reduce installation dependencies. Is TUIOS suitable for this cross-platform constraint?
For: A developer who wants one terminal workspace across Linux, macOS, Windows, or BSD without maintaining a complex build environment

It depends: the project clearly targets multiple platforms and is primarily Go-based, but source builds and advanced terminal features still have environment requirements. The evidence is:
- The project insight lists distribution packages for Linux, macOS, Windows, FreeBSD, and OpenBSD, indicating broad platform coverage.
- The README describes TUIOS as Go-based and provides go build -o tuios ./cmd/tuios; it also supports a pure Go terminal emulator or the ghostty emulator backend.
- The Development section requires Go 1.26.6 or newer, which matters for source builds.
- The supplied README does not detail cross-platform behavior for daemon operation, PTY handling, SSH, graphics protocols, or keyboard protocols on Windows and BSD, so identical feature coverage cannot be assumed. Start with:
go test ./...

  • Project insight, key_features: distributions are provided for Linux, macOS, Windows, FreeBSD, and OpenBSD
  • Development: go build -o tuios ./cmd/tuios
  • Development: It builds the pure Go emulator; the ghostty emulator backend is also supported
  • Project insight, common_pitfalls: the project requires Go 1.26.6 or newer to build
  • Project data: main language is Go; license is MIT License
go test ./...
Not stated in the README：The README does not state whether daemon, PTY, remote sessions, and agent management have full parity on every platform.；It does not document Windows and BSD installation, service-management, or terminal-backend differences.；It does not specify which architectures are covered by the prebuilt packages.

✨ Highlights

  • BSP Tiling, workspaces, and multiple Layout Modes manage terminal panes centrally
  • The Daemon keeps Sessions alive across terminal restarts and supports SSH hosts
  • Agents provide Inbox, approvals, Fleets, Grants, and MCP collaboration features
  • Bubble Tea v2 event-driven rendering claims zero CPU usage at idle
  • Building from source requires Go 1.26.6 or newer

🔧 Engineering

  • A Go terminal multiplexer with a vim-like modal interface, BSP Tiling, and Command Palette.
  • Daemon-backed Sessions survive terminal windows, while tuios attach connects to remote sessions.
  • The Agents section provides Inbox, approvals, Fleets, other machines, and MCP capabilities.
  • It supports the Kitty graphics protocol, sixel, 100+ configurable keybindings, and vim Copy mode.

⚠️ Risks

  • Source builds require Go 1.26.6 or newer, so older Go environments cannot follow the README directly.
  • Runtime requires a true-color terminal; Kitty graphics and sixel are only listed as recommended.
  • tuios connects to a daemon by default; only --standalone explicitly disables it for that run.
  • The project has 10 contributors, 5 releases, and 10 recent commits, indicating a limited maintenance scale.

👥 For who?

  • Terminal developers using Go and coding agents such as Claude Code who need Inbox collaboration.
  • Individual developers or small teams needing BSP Tiling, workspaces, and daemon-backed session persistence.
  • Users running Agents and remote Sessions across machines with SSH or a Tailscale tailnet.
  • Terminal users who need Kitty graphics, sixel, or Ghostty terminal graphics capabilities.