The Problem

Developers who work in a single terminal window often have to juggle multiple shells, copy‑paste commands, and switch contexts manually. When a session crashes or a pane is resized, the state is lost, and reproducing a layout is painful.

What This Does

TUIOS supplies a terminal‑native window manager that lets you split, move, and persist panes inside the same terminal emulator. The core implementation lives in the internal/ package (≈ 794 files, 746 Go source files) and is exercised by the CLI in cmd/tuios/main.go. Configuration, key‑bindings and theme JSON live under docs/ and are parsed by cmd/tuios/config_commands.go. A web front‑end (cmd/tuios-web/main.go) and a fuzz harness (cmd/tuios-fuzz/main.go) are provided as separate binaries, confirming that the repo is a portfolio of related tools rather than a monolith.

How It Is Wired

Execution starts at cmd/tuios/main.go, which parses flags, loads the user config (docs/CONFIGURATION.md format) and creates a session.Session (defined in internal/session/session.go). The session spawns a daemon process (internal/session/daemon.go) that owns a collection of app.Workspace objects (internal/app/workspace.go). Each workspace contains a BSP tiling tree (internal/app/bsp.go) that drives pane geometry.

User input is funneled through the Charm stack: cmd/tuios/keybinds_commands.go maps key sequences to verb structs, which are dispatched to the session via the JSON protocol (docs/protocol.md). Rendering is performed by Bubble Tea (internal/app/render.go) and Lipgloss for styling.

The two internal modules (internal/app and internal/session) have zero import edges and no circular dependencies, so the call graph is shallow: main.go → session.New → workspace.New → render.Draw. The widest blast radius belongs to internal/session/session.go (≈ 1 300 lines) and its test counterpart, because they orchestrate daemon lifecycle, client attachment, and tape scripting.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/tuios
cd tuios

# Build the binary (requires Go 1.25)
go install ./cmd/tuios

# Or run the pre‑built container
docker build -t tuios .
docker run -it --rm tuios

# Install via package manager (if you prefer)
brew install tuios          # macOS / Linux
yay -S tuios-bin            # Arch AUR
nix run github:Gaurav-Gosain/tuios#tuios

Configuration files are expected in the user’s XDG config directory ($XDG_CONFIG_HOME/tuios/), following the formats described in docs/KEYBINDINGS.md and docs/THEMES.md. The CLI flags are listed in docs/CLI_REFERENCE.md.

Real‑World Use

A DevOps engineer can start a persistent session on a bastion host (tuios daemon start) and attach from multiple SSH clients. Each client sees the same workspace layout, and the engineer can script pane arrangements with a tape file (tuios tape run mysetup.tape) to recreate complex dashboards after a reboot.

Code Health & Issues

Measured static findings (18 high, 223 medium):

  • Deep nesting – 57 files, e.g. internal/app/dock_workspace_pills_test.go (max depth 8).
  • Duplicated code – 710 identical 6‑line blocks across 274 files (cmd/tuios/diagnostics.go, internal/session/verb_hints.go, etc.).
  • Oversized files – internal/session/session.go and its test (≈ 1 300 LOC each).

Health audit (8 findings):

  • HIGH – Pin GitHub Actions to commit SHAs (.github/workflows/*.yml).
  • HIGH – Use PR workflow instead of direct push (.github/workflows/update-nix.yml).
  • MEDIUM – Enable Dependabot (.github/dependabot.yml).
  • MEDIUM – Pin Docker base images by digest (Dockerfile).
  • MEDIUM – Add dependency‑vulnerability scan to CI.
  • MEDIUM – Move large assets (assets/demo.gif) to Git LFS.
  • MEDIUM – Run container as non‑root (Dockerfile).
  • LOW – Set timeout-minutes on workflow jobs (.github/workflows/docker-publish.yml).

All expected CI files, a licence, and a lockfile are present; no secrets were found.

The Bottom Line

TUIOS delivers a fully featured terminal multiplexer built on a clean Go codebase, but the project suffers from deep nesting, duplicated snippets, and a few very large files that make change impact analysis difficult. The CI pipeline is functional but needs hardening (action pinning, PR gating, vulnerability scans). It is well‑suited for engineers who need a programmable, persistent terminal workspace and are comfortable navigating a moderately complex Go codebase.