Skip to content
TUIOS: Terminal Multiplexer That Tracks AI Agent States Across Sessions and Machines
Operations 23 min read

TUIOS: Terminal Multiplexer That Tracks AI Agent States Across Sessions and Machines

TUIOS is a Go-based terminal multiplexer that treats AI agent states as first-class citizens, using a seven-level credibility hierarchy to detect whether agents are working, waiting for input, done, or errored, aggregating all waiting items into a cross-session inbox, and enabling agent-to-agent messaging with security hardening.

Geek Labs
Geek Labs
Geek Labs

The Problem: Polling Multiple AI Agents

Developers often run several AI coding assistants simultaneously — e.g., Claude Code, Codex, Gemini CLI — each in its own terminal window. The current workflow forces the developer to act as a poor scheduler: constantly switching windows to check which agent is running tests, blocked on a permission prompt, finished, errored, or waiting for a question. A significant portion of the workday is spent polling.

What TUIOS Is

TUIOS (6k+ stars, MIT, Go, v0.11.0) is a terminal multiplexer that makes agent state a first-class citizen. It provides standard tmux/zellij features — tiling, nine workspaces, persistent sessions, detach/reattach — but its differentiators are:

Per-pane agent state: Each pane shows whether the agent is Working, Waiting for you, Done, Errored, or Unknown.

Unified inbox: All "Waiting for you" items across sessions and machines aggregate into a single inbox (Ctrl+B i), where you can reply in place without switching panes.

Agent-to-agent messaging: Agents can send messages and ask questions of each other via tuios fan, tuios send-agent-message, and tuios ask-agent.

How State Detection Works: A Seven-Level Credibility Hierarchy

A terminal emulator only sees a byte stream; it cannot inherently know if an agent is awaiting input. TUIOS solves this by combining multiple signal sources, ranked by credibility (highest to lowest):

report — Agent self-report (highest). Hooks installed via tuios integration install claude-code add tuios agent-hook calls to the agent's config. The installer backs up the original file ( .tuios.bak), preserves unrelated content, and refuses to write if parsing fails.

program — Program prints OSC 7501. Any program can emit

tuios status blocked --kind permission --app deploy --msg 'Approve deploy to production?'

to appear in the sidebar and inbox.

transcript — Read session logs. Some agent frameworks write conversations to files; the daemon reads them.

osc — Terminal escape sequences. OSC 9;4 progress bars: set = Working, cleared = Idle, error = Errored.

screen — Screen-content rules. Matches text at the bottom of the pane. Essential because agents stuck on permission prompts often print nothing — no output, no title, no progress. The only evidence is the on-screen prompt. Codex rules match Action Required in the title; Crush rules require all strings inside the same bordered box to avoid false positives from quoted text in history.

detect — Process identification. Every 2 seconds the foreground process is checked against a list of 24 known agent CLIs, traversing wrappers like sh -c, timeout, npx, uvx, mise exec. Custom agents can be added via TOML in ~/.config/tuios/harnesses/.

stall — Stall timer (lowest). If state was Working and no activity for 30 seconds, the daemon re-checks screen rules; if none match, it downgrades to Unknown.

Priority rule: A source can only override its own level or lower; it never overwrites a higher-credibility source. The sole exception: a screen rule detecting a permission prompt may override a stale Working state; when the prompt disappears, the previous state returns. The design principle: better to admit ignorance than let a low-credibility source pretend to know. As the docs state: "Detection can tell an agent exists, but it cannot tell whether the agent is waiting for you."

Seven-level credibility hierarchy: who has the final say
Seven-level credibility hierarchy: who has the final say

State Visualization: Shapes Over Colors

Seven states, six distinct shapes: ● Working, ▲ Waiting, ○ Idle, ■ Done, × Errored, □ Unknown. Shapes are used instead of color changes because colors fail in black-and-white prints, projectors, color-blind users, and oddly configured SSH terminals. An ASCII-only mode ( --ascii-only) maps states to *, !, o, #, x, ?. This attention to real-world environments shows the author has run the tool in diverse conditions.

TUIOS official screenshot: four tiled panes with state markers in titles, right sidebar listing agent states
TUIOS official screenshot: four tiled panes with state markers in titles, right sidebar listing agent states

Inbox: Turning Polling Into Mail Processing

The inbox lists all waiting items sorted by urgency, showing pane name, what is needed, and wait time. Categories: approval requests, questions, plans, emails, errors, completed rounds awaiting review. Interaction: Space opens the original prompt; a approve, d deny, 1-9 select option, R deny with reason — all without leaving the inbox.

Two notable safety designs:

Re-read before approve: Before executing an approval, the daemon re-reads the prompt; if content changed, the action is rejected. Prevents "you looked at A but approved B" in concurrent multi-agent scenarios.

Double-confirm for dangerous commands: A built-in risk rule matches shell command segments, penetrating wrappers like sudo, env, sh -c, $( ), backticks, eval. Triggered commands (e.g., rm -rf, git push --force, git reset --hard, curl | sh, dd of=, mkfs, chmod -R 777, DROP TABLE, terraform apply/destroy, kubectl delete, npm publish, and any write outside the working directory ) require the same key pressed twice within three seconds. The project calls this a "speed bump, not a sandbox" — it only ensures deliberate keystrokes; true boundaries remain the agent framework's permission system.

Inbox: all agents' waits aggregated in one place
Inbox: all agents' waits aggregated in one place
TUIOS official screenshot: inbox UI
TUIOS official screenshot: inbox UI

Agent-to-Agent Messaging and a Real Vulnerability

The fleet feature ( tuios fan) runs the same prompt across up to 8 agents in separate git worktrees for comparison. Combined with send-agent-message and ask-agent, agents can communicate and wait for each other's replies.

This capability introduced a critical vulnerability (GHSA-78rj-pghh-vh42, fixed in v0.11.0). Under default config agents.permissions mode = open, every pane had admin rights. The only guard was a check blocking keystrokes into a pane currently awaiting input. However, that check looked at the target pane's state , while "set agent state" was a separate verb not restricted to the caller's own pane. Exploit: (1) change target pane's state from needs_input to working (bypassing the keystroke block), (2) send 1 and Enter to approve the permission prompt. A prompt-injected agent could silently approve any other agent's permission on the same daemon, with no human present.

Fix: bind set-agent-state to the caller's own pane, aligning with the existing scopeSelf rule used for restricted connections. The lesson: introducing cross-process agent collaboration also introduces impersonation channels; default admin-per-pane is convenient for single-agent use but becomes a vulnerability farm in multi-agent setups.

Vulnerability principle: one pane presses agree for another agent
Vulnerability principle: one pane presses agree for another agent

Architecture: Daemon Holds PTYs, Clients Are Just Screens

TUIOS runs as a daemon holding all PTYs and terminal emulators; clients connect via Unix socket and only render. Benefits:

Detach (Ctrl+B d) leaves everything running; reattach later (even from another machine via SSH) and all agents persist.

Multiple clients (local terminal, SSH, browser via tuios-web) can attach to the same session, seeing identical state.

Protocol hardening: max frame 16 MB; nesting depth >1024 rejected; type definitions >1024 rejected; layout nodes >16383 rejected; oversized frames are skipped without breaking the connection. This prevents a poisoned daemon or remote peer from exhausting client memory.

Stack: Go + Bubble Tea v2 + Lipgloss v2 (Model-View-Update). Custom pure-Go terminal emulator (no cgo) enables go install and cross-compilation for Linux, macOS, Windows, FreeBSD, OpenBSD. A second emulator using libghostty-vt is differential-tested against the same byte streams. Rendering is event-driven: PTY read goroutine notifies render only on data; idle CPU usage near zero — critical for an all-day resident tool.

Architecture: daemon holds PTY, client is just a screen
Architecture: daemon holds PTY, client is just a screen

Installation and First Steps

brew install tuios

Also available via AUR, Nix, go install, Docker, or prebuilt binaries. First run creates session-0. Two modes: Window Management Mode (keys manipulate panes) and Terminal Mode (keys pass to shell). Press n for new pane, i to enter Terminal Mode, Alt+Esc to return. Single Esc still goes to the program (so vim isn't disrupted).

Common keys:

n                 new pane (window mode)  Ctrl+B then d   detach  Alt+1..9          switch workspace  Ctrl+P            command palette  Ctrl+B i          inbox  Ctrl+B o          jump to oldest todo  Ctrl+B ?          help

Press Ctrl+B and hold for half a second — a popup lists valid next keys.

Enable agent status reporting:

tuios integration install claude-code  tuios integration install --all  tuios doctor agents

12 frameworks support full status reporting (Claude Code, Codex, Copilot, Cursor Agent, Gemini CLI, opencode, Kilo, Amp, Kimi Code CLI, Pi, oh-my-pi, Qwen Code); 7 more report only session ID for crash recovery. Without integrations, TUIOS falls back to process detection and screen rules — can detect agent presence and rough activity but not "waiting for you." Disable all agent features with [agents] enabled = false.

When to Switch (and When Not To)

Not suitable if:

You use one model, one task at a time — inbox stays empty, state column is decorative; tmux suffices.

Your workflow is deeply scripted around tmux — TUIOS has a tmux compatibility layer for tools like Claude Code's agent teams, but it's a patch, not native; migration cost is high.

You're on Windows — prebuilt binaries exist, but primary targets are macOS/Linux; docs devote significant space to macOS Alt-key quirks and Docker Desktop issues.

Ideal for:

Running two or more agents concurrently — the only group that truly eliminates polling.

Scheduling agents across machines — tuios hosts + SSH federation ( tuios attach --host build) renders remote sessions locally, inbox includes remote waits; tmux would require custom plumbing.

Terminal customization enthusiasts — theme editor, keybind presets (tmux/screen/zellij), kitty graphics, sixel, nine workspaces, three layout algorithms (BSP, master-stack, horizontal infinite).

Caveats

Young project: v0.11.0, dozens of releases in a month, 31 open issues. The permission vulnerability affected v0.10.1 and earlier — upgrade before use.

Default permissions are permissive: agents.permissions = open makes every pane admin. For multi-agent collaboration, review the grants documentation; don't assume safety by default.

Hooks modify your config files: They backup, refuse unparsable files, and cleanly uninstall, but they do edit Claude Code etc. configs — be aware.

Author's Verdict

TUIOS's value isn't "better tmux" — rendering, mouse, key density are well done but that's table stakes. It captures a new problem: when AI agents become daily parallel collaborators, the terminal shifts from "managing processes" to "managing coworkers." Managing coworkers requires state visibility and a converged todo entry point : who's working, who's stuck, who needs a decision. Solve those three, and you can confidently run more agents in parallel.

The seven-level credibility table is the most engineering-flavored page in the docs. It admits a fundamental truth: you cannot reliably know what a black-box process is thinking, so you let every possible signal in, assign strict priorities, and explicitly label "Unknown." That honesty is more practical than pretending to see inside the agent.

Project: https://github.com/Gaurav-Gosain/tuios  Website & live demo: https://tuios.dev https://tuios.dev/learn
Original Source

Signed-in readers can open the original source through BestHub's protected redirect.

Sign in to view source
Republication Notice

This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactadmin@besthub.devand we will review it promptly.

AI agentsGoDeveloper Toolsterminal multiplexersecurity vulnerabilitytmux alternativeagent state managementTUIOS
Reader feedback

How this landed with the community

Sign in to like

Rate this article

Was this worth your time?

Sign in to rate
Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.