Core Engine: Tmux & PTY

Relevant source files

The following files were used as context for generating this wiki page:

• crates/core-engine/src/pty/mod.rs
• crates/core-engine/src/tmux/mod.rs
• crates/core-engine/src/shims/bash_shim.sh
• crates/infra/src/websocket/message.rs
• crates/core-service/src/service/ws_message.rs

The Core Engine provides the foundational infrastructure for terminal emulation and session management within ATMOS. It leverages Pseudo-Terminal (PTY) interfaces to interact with the underlying operating system's shell while utilizing Tmux for robust session persistence and multiplexing. This allows the system to maintain active terminal states independently of the frontend connection.

This module acts as the bridge between high-level WebSocket requests and low-level process execution. By combining PTY management with Tmux control, the engine ensures that terminal sessions are resilient, resizable, and capable of executing complex shell commands through specialized shims.

PTY Management

The PTY (Pseudo-Terminal) component is responsible for creating and managing the lifecycle of terminal processes. It handles the low-level I/O required to pass data between the application and the spawned shell.

Core PTY Structure

The PTY system is centered around a Pty struct which manages the file descriptors for the primary and secondary ends of the terminal.

Lifecycle and Data Flow

When a new terminal is requested, the engine forks a process, sets up the PTY descriptors, and executes the target shell (often wrapped in a bash shim).

Tmux Integration

Tmux is utilized as the session multiplexer, providing persistence for terminal sessions. The Core Engine interacts with Tmux via CLI commands to create sessions, attach panes, and manage window state.

Session Management

The Tmux module handles the orchestration of sessions, ensuring that each user or workspace has a dedicated environment.

Component	Responsibility
TmuxSession	Manages the creation and deletion of tmux sessions.
TmuxPane	Controls individual panes within a session, handling resizing and input.
TmuxConfig	Defines session parameters such as default shell and initial size.

Sources: crates/core-engine/src/tmux/mod.rs

Command Execution Flow

Tmux commands are dispatched from the core service to the engine, which translates them into shell-level tmux invocations.

Bash Shims and Environment

The bash_shim.sh script is a critical component used during the PTY spawning process. It prepares the environment, sets up necessary aliases, and ensures that the terminal session is correctly initialized before handing control over to the interactive shell.

Shim Features

• Environment Normalization: Sets standard variables like TERM and LANG.
• Command Interception: Allows the engine to intercept certain commands for integration features.
• Initialization Hooks: Executes project-specific setup scripts.

Sources: crates/core-engine/src/shims/bash_shim.sh

WebSocket Orchestration

The integration between the Core Engine and the outside world is managed via WebSocket actions. The message.rs file defines the protocol for terminal interaction.

Terminal Actions Table

Action Variant	Request Struct	Description
TerminalInput	TerminalInputRequest	Sends raw string data or control sequences to the PTY.
TerminalResize	TerminalResizeRequest	Updates the cols and rows of the active PTY/Tmux pane.
GitGetHeadCommit	GitGetHeadCommitRequest	Retrieves current HEAD via the engine's git integration.

Sources: crates/infra/src/websocket/message.rs:574-580, crates/core-service/src/service/ws_message.rs

Conclusion

The "Core Engine: Tmux & PTY" module provides a resilient and scalable terminal infrastructure for ATMOS. By abstracting raw PTY interactions into manageable Tmux sessions and exposing them via a structured WebSocket API, the system enables complex terminal workflows—including multi-pane management and persistent sessions—while maintaining low-level control over process execution and environment configuration.