# gaurav-gosain/tuios architecture

> Architecture diagram of the GitHub repository gaurav-gosain/tuios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gaurav-gosain/tuios
- Repository: https://github.com/gaurav-gosain/tuios

## Overview

TUIOS is a terminal multiplexer and window manager. A user launches the CLI, interacts with its modal interface to manage panes and workspaces, and runs shell processes in terminal panes; sessions can persist under the daemon and be reached remotely. The architecture also includes agent-state and Inbox capabilities, configuration, review, tape automation, and a browser server. The README establishes product capabilities; source-index references support several internal dependencies. Unsampled implementation details are represented only where documented, and uncertain links are omitted.

Main entry points: [`cmd/tuios/main.go`](https://github.com/gaurav-gosain/tuios/blob/main/cmd/tuios/main.go) (CLI), [`internal/input/handler.go`](https://github.com/gaurav-gosain/tuios/blob/main/internal/input/handler.go) (Input Routing), [`internal/terminal/window.go`](https://github.com/gaurav-gosain/tuios/blob/main/internal/terminal/window.go) (Terminal Window), [`internal/session/manager.go`](https://github.com/gaurav-gosain/tuios/blob/main/internal/session/manager.go) (Session Manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Terminal Interface"]
  node_cli["CLI<br/>[main.go]"]
  node_input["Input Routing<br/>[handler.go]"]
  node_keybind_ui["Keybind Manager UI"]
  node_keybinds["Keybind Manager<br/>[keybind_manager.go]"]
  node_config["Configuration<br/>[options.go]"]
end

subgraph group_runtime["Pane Runtime"]
  node_layout["BSP Layout<br/>[bsp.go]"]
  node_terminal_window["Terminal Window<br/>[window.go]"]
  node_vt["Terminal Emulator<br/>[handlers.go]"]
  node_scrollback["Scrollback Parser<br/>[parser.go]"]
end

subgraph group_sessions["Sessions And Agents"]
  node_session_manager[("Session Manager<br/>[manager.go]")]
  node_agent_protocol["Agent Protocol<br/>[session.go]"]
  node_worktree["Worktree Checkpoints<br/>[checkpoint.go]"]
end

subgraph group_extensions["Automation And Access"]
  node_web_server["Web Terminal Server<br/>[main.go]"]
  node_dock["Dock Engine<br/>[dock_engine.go]"]
  node_tapes["Tape Manager<br/>[tapemanager.go]"]
  node_review["Review Commands<br/>[review_commands.go]"]
  node_review_engine["Review Engine<br/>[review.go]"]
end

node_user(("User"))
node_shell["Pane Shell Process"]

node_user -->|"launches"| node_cli
node_cli -.->|"starts interface"| node_input
node_cli -->|"manages sessions"| node_session_manager
node_input -.->|"opens"| node_keybind_ui
node_keybind_ui -.->|"uses"| node_keybinds
node_input -.->|"routes by bindings"| node_config
node_input -->|"routes pane input"| node_terminal_window
node_layout -->|"reads settings"| node_config
node_terminal_window -->|"uses emulator"| node_vt
node_terminal_window -->|"manages PTY process"| node_shell
node_scrollback -->|"parses terminal state"| node_vt
node_cli -->|"exposes checkpoint commands"| node_worktree
node_cli -->|"dispatches review commands"| node_review
node_review -->|"calls"| node_review_engine
node_user -->|"connects in browser"| node_web_server
node_web_server -.->|"serves TUIOS sessions"| node_session_manager
node_session_manager -.->|"tracks agent sessions"| node_agent_protocol
node_user -->|"views session rail"| node_dock
node_user -->|"records or replays"| node_tapes

click node_cli "https://github.com/gaurav-gosain/tuios/blob/main/cmd/tuios/main.go"
click node_input "https://github.com/gaurav-gosain/tuios/blob/main/internal/input/handler.go"
click node_keybind_ui "https://github.com/gaurav-gosain/tuios/blob/main/internal/app/render_keybind_manager.go"
click node_keybinds "https://github.com/gaurav-gosain/tuios/blob/main/internal/app/keybind_manager.go"
click node_config "https://github.com/gaurav-gosain/tuios/blob/main/internal/config/options.go"
click node_layout "https://github.com/gaurav-gosain/tuios/blob/main/internal/layout/bsp.go"
click node_terminal_window "https://github.com/gaurav-gosain/tuios/blob/main/internal/terminal/window.go"
click node_vt "https://github.com/gaurav-gosain/tuios/blob/main/internal/vt/handlers.go"
click node_scrollback "https://github.com/gaurav-gosain/tuios/blob/main/internal/scrollback/parser.go"
click node_session_manager "https://github.com/gaurav-gosain/tuios/blob/main/internal/session/manager.go"
click node_agent_protocol "https://github.com/gaurav-gosain/tuios/blob/main/internal/agentproto/session.go"
click node_worktree "https://github.com/gaurav-gosain/tuios/blob/main/internal/worktree/checkpoint.go"
click node_web_server "https://github.com/gaurav-gosain/tuios/blob/main/cmd/tuios-web/main.go"
click node_dock "https://github.com/gaurav-gosain/tuios/blob/main/internal/app/dock_engine.go"
click node_tapes "https://github.com/gaurav-gosain/tuios/blob/main/internal/app/tapemanager.go"
click node_review "https://github.com/gaurav-gosain/tuios/blob/main/cmd/tuios/review_commands.go"
click node_review_engine "https://github.com/gaurav-gosain/tuios/blob/main/internal/review/review.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_input,node_keybind_ui,node_keybinds,node_config,node_user toneBlue
class node_layout,node_terminal_window,node_vt,node_scrollback toneAmber
class node_session_manager,node_agent_protocol,node_worktree toneMint
class node_web_server,node_dock,node_tapes,node_review,node_review_engine toneRose
class node_shell toneIndigo
```

## Components

### Terminal Interface

- [CLI](https://github.com/gaurav-gosain/tuios/blob/main/cmd/tuios/main.go): `cmd/tuios/main.go`
- [Input Routing](https://github.com/gaurav-gosain/tuios/blob/main/internal/input/handler.go): `internal/input/handler.go`
- [Keybind Manager UI](https://github.com/gaurav-gosain/tuios/blob/main/internal/app/render_keybind_manager.go): `internal/app/render_keybind_manager.go`
- [Keybind Manager](https://github.com/gaurav-gosain/tuios/blob/main/internal/app/keybind_manager.go): `internal/app/keybind_manager.go`
- [Configuration](https://github.com/gaurav-gosain/tuios/blob/main/internal/config/options.go): `internal/config/options.go`

### Pane Runtime

- [BSP Layout](https://github.com/gaurav-gosain/tuios/blob/main/internal/layout/bsp.go): `internal/layout/bsp.go`
- [Terminal Window](https://github.com/gaurav-gosain/tuios/blob/main/internal/terminal/window.go): `internal/terminal/window.go`
- [Terminal Emulator](https://github.com/gaurav-gosain/tuios/blob/main/internal/vt/handlers.go): `internal/vt/handlers.go`
- [Scrollback Parser](https://github.com/gaurav-gosain/tuios/blob/main/internal/scrollback/parser.go): `internal/scrollback/parser.go`

### Sessions And Agents

- [Session Manager](https://github.com/gaurav-gosain/tuios/blob/main/internal/session/manager.go): `internal/session/manager.go`
- [Agent Protocol](https://github.com/gaurav-gosain/tuios/blob/main/internal/agentproto/session.go): `internal/agentproto/session.go`
- [Worktree Checkpoints](https://github.com/gaurav-gosain/tuios/blob/main/internal/worktree/checkpoint.go): `internal/worktree/checkpoint.go`

### Automation And Access

- [Web Terminal Server](https://github.com/gaurav-gosain/tuios/blob/main/cmd/tuios-web/main.go): `cmd/tuios-web/main.go`
- [Dock Engine](https://github.com/gaurav-gosain/tuios/blob/main/internal/app/dock_engine.go): `internal/app/dock_engine.go`
- [Tape Manager](https://github.com/gaurav-gosain/tuios/blob/main/internal/app/tapemanager.go): `internal/app/tapemanager.go`
- [Review Commands](https://github.com/gaurav-gosain/tuios/blob/main/cmd/tuios/review_commands.go): `cmd/tuios/review_commands.go`
- [Review Engine](https://github.com/gaurav-gosain/tuios/blob/main/internal/review/review.go): `internal/review/review.go`

### Other components

- **User**
- **Pane Shell Process**

## Connections

- User → CLI: launches
- CLI → Input Routing: starts interface
- CLI → Session Manager: manages sessions
- Input Routing → Keybind Manager UI: opens
- Keybind Manager UI → Keybind Manager: uses
- Input Routing → Configuration: routes by bindings
- Input Routing → Terminal Window: routes pane input (evidence: `internal/input/handler.go`)
- BSP Layout → Configuration: reads settings (evidence: `internal/layout/bsp.go`)
- Terminal Window → Terminal Emulator: uses emulator (evidence: `internal/terminal/window.go`)
- Terminal Window → Pane Shell Process: manages PTY process
- Scrollback Parser → Terminal Emulator: parses terminal state (evidence: `internal/scrollback/parser.go`)
- CLI → Worktree Checkpoints: exposes checkpoint commands (evidence: `cmd/tuios/main.go`)
- CLI → Review Commands: dispatches review commands (evidence: `cmd/tuios/main.go`)
- Review Commands → Review Engine: calls (evidence: `cmd/tuios/review_commands.go`)
- User → Web Terminal Server: connects in browser
- Web Terminal Server → Session Manager: serves TUIOS sessions
- Session Manager → Agent Protocol: tracks agent sessions
- User → Dock Engine: views session rail
- User → Tape Manager: records or replays