TUIOS review: a Go terminal multiplexer with a daemon, BSP tiling and agent panes

What TUIOS solves, and who it is actually for

tmux gives you panes and sessions. It does not give you draggable windows, a command palette, a nine-workspace model, or any notion of what the process inside a pane is doing. TUIOS takes that gap as its brief. The README describes it as a terminal multiplexer and window manager that runs inside your existing terminal, with a vim-like modal interface, multiple terminal panes, workspaces, BSP tiling, kitty graphics protocol support and a command palette.

The audience is narrower than "terminal users". The feature list is dominated by things that matter to people running several coding agents at once: agent state reporting, an agent inbox, git worktrees per agent, and a fan-out command that starts one prompt in several agents. The Machines section goes further, with named hosts reached over ssh, remote sessions drawn in the local client, and panes whose process runs on another machine. If you run one shell and a text editor, most of this is surface area you will never open.

How TUIOS is put together: PTYs, a daemon and a JSON verb protocol

The mechanism is visible in the repository layout and go.mod. TUIOS is a Go module, github.com/Gaurav-Gosain/tuios, on Go 1.26.6. It depends on charm.land/bubbletea/v2 and charm.land/lipgloss/v2 for the interface, github.com/charmbracelet/x/xpty for pseudo-terminals, charm.land/ssh and charm.land/wish/v2 for the remote side, and tailscale.com for tailnet host discovery. There is a cmd/ directory, and the Dockerfile builds two binaries from it: ./cmd/tuios and ./cmd/tuios-web.

So the shape is: a TUI client that owns the drawing and input, PTYs underneath it for each pane, and a daemon that keeps sessions alive and can be reached from another machine. The docs folder names a Control Protocol, docs/protocol.md, described as a JSON verb protocol for driving the daemon. That is the piece worth noticing. A daemon with a verb protocol means external programs can drive TUIOS, which is how the agent commands and the session rail can report state without scraping the screen.

Agent state has two paths. The README says panes running a coding agent show whether it is working, idle or waiting, and that agents report it with tuios set-agent-state, or TUIOS detects 22 agent CLIs by their process and screen. Process and screen detection is the fallback for tools that do not call the command. That fallback will be brittle for any CLI whose output changes, and the README does not claim otherwise.

Rendering is event-driven, which the README ties to near-zero idle CPU usage. That is a claim from the project, not a measurement, and the README gives no methodology behind it.

Installing TUIOS and running a first session

The README lists package managers first. On macOS or Linux with Homebrew, the command is brew install tuios. On Arch, yay -S tuios-bin from the AUR. With Nix, nix run github:Gaurav-Gosain/tuios#tuios. There is also a quick install script, a go install path, a Docker image, and pre-built binaries on the releases page.

The go install route pins nothing, so it takes whatever the latest tagged module is:

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

The Docker route runs the multiplexer as the default entrypoint. The image is built on gcr.io/distroless/static-debian11:nonroot, and the Dockerfile comments explain that a shell-bearing base would otherwise offer a root shell to whoever reaches the terminal it serves:

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

The same image also contains tuios-web, but the Dockerfile deliberately does not make it the entrypoint and does not declare an EXPOSE. The comment is explicit that tuios-web serves a shell, has no authentication of its own, and refuses a non-loopback bind in clear text on purpose. To run it you name it and pass the host yourself:

docker run --rm -p 7681:7681 --entrypoint /tuios-web <image> \
  --host 0.0.0.0 --auto-tls

Once installed, the first real use is a session with a pane you can split. The README points to docs/getting-started for install and first session, and to docs/KEYBINDINGS.md for default keys and rebinding. The interface is modal, so the keys differ between Window Management mode and Terminal mode. Ctrl+P opens the command palette, a fuzzy-searchable action launcher, and Alt+Space opens the launcher, which searches $PATH and installed desktop apps. Pressing Enter starts the highlighted entry; Tab opens a shell with the command typed but not entered, so you can add arguments.

For a floating pane that closes when the command exits, the README gives this form:

tuios popup -- fzf

Updating depends on how you installed. If you used the quick install script or a release binary, tuios update fetches the newest release, and tuios update --check only reports. For every other install, TUIOS detects the package manager and prints the right command rather than overwriting the binary.

The terminal has to cooperate: graphics, true color and where that breaks

The requirements section is short and worth taking literally. A terminal with true color support is listed as required; kitty graphics and sixel support are recommended, with Ghostty, Kitty and WezTerm named. Flicker-free kitty image passthrough is a headline feature, and the launcher draws app icons where the terminal supports kitty graphics. On a terminal without it, those paths degrade rather than fail, but the image handling that distinguishes TUIOS from a text-only multiplexer is simply absent.

This is the wrong tool in a few concrete situations. Over a slow ssh link, an event-driven renderer that redraws windows, a dockbar and a session rail is more to push than a grid of text. Inside a plain xterm or a CI pseudo-terminal, the graphics features have nothing to draw into. And if your work is one long-running process you attach to and detach from, the window manager layer is overhead you will keep ignoring.

There is a second limitation in the Dockerfile itself. tuios-web has no authentication of its own, so exposing it is a decision the operator makes explicitly, with TLS or with --insecure. The project's choice to refuse a non-loopback clear-text bind is a good default, but it also means the web terminal is not something you can casually put behind a port forward and forget.

TUIOS versus tmux and Zellij

The honest comparison is about what each one refuses to do. tmux is a session manager with a scripting language bolted on; you drive it with commands and configuration files, and it has been stable for long enough that its behaviour is predictable across machines. TUIOS inverts that. The window manager is the product, the daemon exists to keep sessions alive and reach them on other machines, and automation arrives through a JSON verb protocol rather than a shell command language. If your existing workflow is a .tmux.conf plus scripts that call tmux send-keys, none of that transfers.

Zellij is the closer comparison, since it also ships a tiling layout, a plugin system and a status bar. The difference in approach: Zellij's extension point is WebAssembly plugins, while TUIOS's is the daemon protocol plus shell hooks (docs/HOOKS.md covers running shell commands on window, session and agent events). Plugins let you build interface inside the multiplexer; hooks and verbs let you react to it from outside. Which one you want depends on whether your customisation is visual or procedural.

Against both, TUIOS's distinctive claim is the agent layer: tuios list-agents to see every agent pane and what it is doing, tuios send-agent-message to leave a message in another agent's inbox, tuios ask-agent to ask and wait for the answer, and tuios fan to start one prompt in several agents, each in its own git worktree. tmux can approximate this with send-keys and capture-pane, but you would be writing the state machine yourself.

Maintenance, licence and what an upgrade costs you

TUIOS is MIT licensed, which permits commercial and closed-source use and requires only that the licence and copyright notice travel with copies. That is the whole of the licence implication; anything beyond it is a question for a lawyer, not for this article.

The project is not archived, and the last push was on 2026-09-23. Releases are not frequent: v0.5.1 on 2025-12-26, v0.6.0 on 2026-01-25, v0.7.0 on 2026-03-28. The gap between the v0.7.0 tag and the most recent push is roughly six months, so the repository is moving between releases rather than at each one. That matters for anyone building on the control protocol, because the protocol is documented in the repository (docs/protocol.md) rather than versioned as a public API.

Upgrade cost is concentrated in two places. Configuration lives in TOML, toml is in the dependency list via github.com/pelletier/go-toml/v2, and docs/CONFIGURATION.md covers keybindings, themes and behaviour; themes can also be custom JSON, per docs/THEMES.md. Any release that renames a config key or a theme field will show up as a broken startup, and the README does not document a migration path or a rollback. The second place is the binary itself: if a package manager owns it, tuios update will not touch it, so your upgrade cadence is your package manager's cadence.

Editorial conclusion

Adopt TUIOS if you want tiling, workspaces and a daemon that survives detach in one binary, and if you are willing to read docs/KEYBINDINGS.md before your first session. Skip it if you need tmux's scripting surface or Zellij's plugin model, or if your terminal lacks true color. Verify two things first: that your terminal handles kitty graphics or sixel if you want image passthrough, and which install channel owns your binary, because tuios update refuses to overwrite a package-manager copy and only handles the quick install script or a release binary.

Frequently asked questions

Official sources

1. Gaurav-Gosain/tuios on GitHub
2. License: MIT
3. Project website
4. README
5. Releases