PTY & Process Management
Relevant source files
The following files were used as context for generating this wiki page:
PTY and Process Management in Termul handles the lifecycle, input/output, and persistence of pseudo-terminal sessions. The system provides project-aware terminal management, allowing users to organize processes by workspace with persistent sessions that survive navigation. It utilizes tauri-pty on the Rust backend for native process execution and xterm.js on the React frontend for rendering terminal output.
Sources: README.md:143-155, AGENTS.md:13-16
Terminal Architecture and Lifecycle
The terminal system operates through a layered architecture that connects the React-based frontend to native OS processes via a Rust runtime. Termul utilizes a P1 priority domain for Terminal operations, ensuring critical functionality like spawning, resizing, and killing processes is verified through automated parity tests.
PTY Management Flow
The following diagram illustrates the flow from a user action in the UI to the underlying process execution in the OS.
This diagram shows the sequence of communication from the frontend UI components down to the native process management layer.
Sources: src/renderer/lib/tests/parity-checklist.test.ts:142-159, README.md:143-155
Core Terminal Operations
Termul implements a standard set of terminal operations through its API bridge. The system specifically manages the following actions:
- Spawn: Initiates a new PTY instance with a specified shell (e.g., PowerShell, Zsh, Fish).
- Write: Sends character data from the frontend to the process standard input.
- Resize: Updates the PTY dimensions (columns and rows) to match the UI pane size.
- Kill: Terminates the underlying process and cleans up resources.
- Attach: Reconnects the frontend to an existing, running PTY session.
Sources: src/renderer/lib/tests/parity-checklist.test.ts:145-155, README.md:36-41
Session Persistence and Switching
Termul treats workspaces as first-class citizens. A key policy of the terminal manager is the preservation of live PTY sessions across project switches. The application does not kill or recreate sessions during navigation cleanup. This allows users to switch between projects while maintaining the state of long-running terminal tasks.
This sequence shows how the system maintains process continuity even when the user navigates away from the active terminal view.
Sources: AGENTS.md:52-54, README.md:36-41
Process Execution Management
For operations that involve heavy I/O or long-running tasks, such as Git worktree management or file operations, Termul utilizes asynchronous task management in Rust. The system offloads blocking operations from the main async runtime to prevent UI freezes.
Blocking Task Handling
When the system executes commands like worktree_copy_include_files, it uses tokio::task::spawn_blocking. This ensures that filesystem walks and file copies do not block the terminal's responsiveness.
Sources: src-tauri/src/commands/worktree.rs:252-258
IPC Channel Mapping
The terminal manager uses a structured IPC channel map to communicate between the renderer and the host.
| Channel | Action | Data Type |
|---|---|---|
terminal:spawn | Create PTY | TerminalDescriptor |
terminal:write | Send Input | String |
terminal:resize | Resize PTY | (rows, cols) |
terminal:attach | Reconnect Session | ClaimHandle |
terminal:kill | Stop Process | TerminalId |
Sources: src/renderer/lib/tests/parity-checklist.test.ts:145-165, src/renderer/lib/tests/parity-checklist.test.ts:400-410
Platform Parity and Transports
Termul maintains parity between the desktop Tauri application and the standalone termul-server. Terminal functionality is gated by a facade that branches based on the runtime context.
Transport Adapters
The system uses different transport mechanisms depending on the environment:
- Desktop (Tauri): Communicates via the
invokeAPI to call Rust functions directly. - Web (Server): Communicates via WebSockets (WS) to relay PTY data and HTTP routes for management commands.
This diagram demonstrates the strategy used to ensure terminal functionality remains consistent across desktop and web surfaces.
Sources: src/renderer/lib/tests/parity-checklist.test.ts:416-430, AGENTS.md:27-31
Conclusion
PTY & Process Management in Termul provides a robust foundation for project-centric development. By combining native PTY execution with a persistent session policy, the system ensures that terminal workflows remain uninterrupted during workspace navigation. The use of structured IPC and platform-agnostic adapters allows the application to deliver a consistent experience across desktop and web environments.