Introduction to Termul
Relevant source files
The following files were used as context for generating this wiki page:
Termul is a modern, project-aware terminal manager that treats workspaces as first-class citizens. It allows you to organize terminals by project with persistent sessions, snapshots, and a tabbed interface. The system functions as a terminal-based agent chat client that spawns external AI coding agents using the Agent Client Protocol (ACP).
The application is cross-platform, supporting Windows, macOS, and Linux. It is built as a Tauri 2 desktop application with a React/TypeScript renderer and a Rust runtime. In addition to the desktop app, the project supports a standalone termul-server and a responsive browser client.
Sources: README.md:3-8, CONTEXT.md:3-5, AGENTS.md:7-9
Core Architecture
Termul utilizes a multi-layered architecture to separate UI concerns from native system integrations and agent management.
Tech Stack Overview
| Layer | Technology |
|---|---|
| Desktop Runtime | Tauri 2.0 |
| Backend | Rust |
| UI Framework | React 18 |
| Type System | TypeScript 5 |
| Styling | Tailwind CSS + shadcn/ui |
| Terminal Emulation | tauri-pty + xterm.js |
| State Management | Zustand |
Sources: README.md:183-195
Component Relationship
The following diagram illustrates the relationship between the different runtime environments and the shared core logic.
The application shares host-backed behavior in Rust services while exposing them through different transports (Tauri for desktop, WebSockets/HTTP for the server).
Sources: AGENTS.md:20-29, src-tauri/src/server_main.rs:1-10
Key System Modules
Workspace Management
Termul organizes work around Projects, which represent a single workspace root. The UI is divided into an app chrome (sidebar, tab bar, status bar) and a terminal grid.
- Project-Based Workspaces: Dedicated directories with separate state and per-project configuration.
- Tabbed Interface: Windows Terminal-style tab bar with drag-and-drop reordering.
- Split Layout: Resizable panes that can hold terminals, editors, or browser tabs.
Sources: README.md:31-36, CONTEXT.md:65-67, CONTEXT.md:92-99
Agent Client Protocol (ACP)
The system acts as a host for AI agents. It manages an Agent Catalog, which is a resolved view of the active registry based on OS availability and installation state.
- Agent Chats: Open conversation tabs for specific sessions.
- Agent Process: The running ACP agent instance. The system preserves live PTY sessions across project switches.
- Permission Rendezvous: A server-side mechanism that handles agent permission requests with bounded timeouts and disconnect-deny policies.
Sources: CONTEXT.md:7-36, CONTEXT.md:46-52, src-tauri/src/server_main.rs:260-267, AGENTS.md:75-76
Standalone Server (termul-server)
The termul-server is a headless binary that provides remote access to terminals and agents.
- Web Auth: Employs a bearer token gate for non-loopback binds to secure API and WebSocket routes.
- Self-Update: Includes an opt-in periodic update loop that fetches channel manifests and verifies binary signatures before swapping.
- Session Persistence: Manages durable session roots and event-log ring buffers for each terminal session.
Sources: src-tauri/src/server_main.rs:80-143, src-tauri/src/server_main.rs:430-440
Design and Development Standards
Design System
Termul uses a dark-first design. All colors must use semantic OKLCH tokens.
- Semantic Tokens: Fills, text, and overlays use tokens like
bg-backgroundortext-destructive. - Palette Rules: Developers are prohibited from using Tailwind palette primitives (e.g.,
bg-red-500) or raw hex codes in JSX. - Platform Parity: Features should be implemented across all surfaces (Tauri desktop, remote server, browser) simultaneously.
Sources: DESIGN.md:3-17, AGENTS.md:26-29
Project Directory Structure
src/
├── renderer/ # React frontend (Components, Hooks, Pages, Stores)
├── shared/ # Runtime-neutral contracts and types
src-tauri/ # Rust backend, Tauri configuration, and server logic
landing/ # Standalone Vite-based marketing page
Sources: CONTRIBUTING.md:118-125, README.md:223-230
Summary
Termul Manager provides a unified environment for managing project-specific terminal sessions and AI agents. By leveraging Tauri for desktop and Rust for the backend, it ensures high performance and cross-platform compatibility. The system's project-aware nature, combined with persistent sessions and built-in agent support, streamlines modern development workflows.
Sources: README.md:3-8, AGENTS.md:7-12