Terminal Multiplexing System
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal Multiplexing System is a core infrastructure component of the ATMOS project, designed to provide persistent, multi-session terminal capabilities within a web-based environment. It leverages a backend architecture built on Rust and tmux to ensure that terminal sessions remain active even when the frontend client disconnects or the browser is refreshed.
The system facilitates complex workspace management by allowing developers to maintain multiple isolated terminal environments, each associated with specific worktrees or project contexts. It integrates high-performance rendering via Xterm.js with a robust backend PTY manager to deliver a responsive and reliable command-line experience.
Sources: specs/tech/TechPlan-V1.0.md, specs/tech/Terminal-Multiplexing-System.md
System Architecture
The architecture is split between a React-based frontend and a Rust-based backend. The frontend handles rendering and user input, while the backend manages the lifecycle of PTY (Pseudo-Terminal) processes and session persistence through tmux.
High-Level Component Interaction
The following diagram illustrates the data flow between the web interface, the backend server, and the underlying terminal processes.
Backend Session Management
The backend utilizes tmux to provide session persistence. This ensures that long-running tasks, such as build processes or backend servers, continue to execute if the user navigates away from the workspace.
Key Backend Components
| Component | Responsibility |
|---|---|
| PTY Manager | Manages the creation and pooling of PTY processes using portable-pty. |
| Tmux Manager | Orchestrates tmux sessions, windows, and panes for persistence. |
| WebSocket Manager | Handles real-time bi-directional communication and broadcasts terminal output to connected clients. |
Sources: specs/tech/TechPlan-V1.0.md:52-60, specs/tech/Terminal-Multiplexing-System.md
Terminal Lifecycle Flow
When a terminal is requested for a workspace, the system follows a specific sequence to ensure the environment is correctly initialized.
Dynamic Title Technology (Shell Shim Injection)
To provide accurate context in the UI, the system implements a dynamic title technology based on "Shell Shim Injection." This allows the terminal to report the current working directory (CWD) and the currently executing command back to the ATMOS frontend.
Implementation Logic
The system injects a "shim" or a set of shell hooks into the user's .bashrc or .zshrc. These hooks utilize ANSI escape sequences (specifically OSC - Operating System Command codes) to emit metadata whenever the prompt is rendered or a command is executed.
- CWD Tracking: The shell hook sends the updated path after every
cdcommand. - Command Tracking: Before a command is executed, a pre-exec hook sends the command string.
- Title Updates: The backend intercepts these specific escape sequences and updates the terminal metadata in the SQLite database.
Sources: specs/tech/Web 终端动态标题技术方案：基于 Shell 垫片注入.md
Frontend Components
The frontend is responsible for rendering the terminal output and providing management interfaces for multiple sessions.
Terminal Component
The Terminal.tsx component wraps Xterm.js. It handles:
- Initialization: Setting up the Xterm instance with specific themes and addons (FitAddon, WebLinksAddon).
- Communication: Sending user keystrokes over WebSocket and writing received ANSI streams to the terminal buffer.
- Resizing: Detecting container size changes and notifying the backend to adjust the PTY columns and rows.
Terminal Manager View
The TerminalManagerView.tsx provides a higher-level interface to manage multiple terminal tabs or panes within a workspace. It allows users to:
- Switch between different active terminal sessions.
- Create new terminals (Standard, Claude Agent, etc.).
- Monitor terminal status.
Sources: apps/web/src/components/terminal/Terminal.tsx, apps/web/src/components/terminal/TerminalManagerView.tsx
Data Model
Terminal metadata is stored in SQLite via SeaORM to maintain configuration and relationship data.
| Field | Type | Description |
|---|---|---|
id | String/UUID | Unique identifier for the terminal instance. |
workspace_id | String | Foreign key linking to the associated Workspace. |
name | String | User-defined or auto-generated name for the terminal. |
agent_type | Enum | The type of agent running (e.g., claude, codex, native). |
tmux_session | String | Identifier for the backend tmux session. |
Sources: specs/tech/TechPlan-V1.0.md:165-175
Conclusion
The Terminal Multiplexing System provides a robust foundation for the ATMOS development environment. By combining tmux for persistence, Rust for high-performance process management, and Xterm.js for a seamless web experience, the system enables complex, multi-session workflows that survive client disconnections and provide rich contextual feedback through dynamic title injection.