Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Termul is a desktop application built on Tauri 2 that provides a project-aware terminal management system. It employs a multi-surface architecture supporting a native desktop experience, a standalone server (termul-server), and a responsive web client. The system centralizes terminal sessions, AI agent chats via the Agent Client Protocol (ACP), and workspace state within a Rust-based runtime while exposing a React/TypeScript renderer for the user interface.
Sources: AGENTS.md:8-12, README.md:213-219, CONTEXT.md:3-5
Core System Architecture
Termul utilizes a layered architecture to maintain parity across different execution environments (Desktop, Remote Host, and Web). The logic is split across three primary directories:
src/renderer/: Contains the React frontend, including UI components, custom hooks, and Zustand-powered state management.src-tauri/: Contains the Rust backend responsible for the desktop runtime, shared web/server implementations, and PTY management.src/shared/: Defines runtime-neutral contracts and types used by both the renderer and the backend.
Sources: AGENTS.md:20-22, README.md:243-250
Multi-Surface Transports
The application architecture ensures behavioral parity between the Tauri desktop environment and the standalone web server through an adapter/service layer. Renderer facades detect the execution context via isTauriContext() and route requests through appropriate transports.
The diagram shows how the UI interacts with shared Rust services through context-aware API facades.
Sources: AGENTS.md:28-33, src/renderer/lib/tests/parity-checklist.test.ts:251-265, src/renderer/lib/tests/worktree-api.web.test.ts:40-50
Component Model & State Management
Termul organizes its internal state using Zustand stores. These stores manage reactive data for specific domains, ensuring persistence and synchronization across the workspace.
| Domain | Key Components | Zustand Store |
|---|---|---|
| Workspace | WorkspaceLayout, PaneRenderer, WorkspaceTabBar | workspace-store |
| Terminal | ConnectedTerminal, XTerminal, ActivityIndicator | terminal-store |
| Editor | EditorPanel, CodeEditor, MarkdownEditor | editor-store |
| Browser | BrowserPanel, AnnotationPanel | browser-session-store, annotation-store |
| Agents | AgentChatPanel, AgentTools | acp-store |
Sources: README.md:89-110, src/renderer/lib/tests/parity-checklist.test.ts:577-585
Agent Client Protocol (ACP) Integration
A core feature of Termul is its ability to manage AI coding agents using the Agent Client Protocol. The host acts as the single source of truth for agent sessions, maintaining durable transcripts that are shared across desktop and browser surfaces.
- Registry Management: The system maintains an ACP Registry of agents, distinguishing between a Bundled Registry (frozen in app) and an Applied Registry (user-opted update).
- Session Persistence: The host owns the session transcript. Desktop clients use Tauri commands (
acp_history_get), while web clients use WebSocket requests (get_session_payload). - Agent Spawning: The host handles the verified-atomic installation and spawning of agents, returning metadata including
capabilities,authMethods, andstableNamespace.
Sources: CONTEXT.md:9-40, src/renderer/lib/tests/parity-checklist.test.ts:468-478, src/renderer/lib/tests/parity-checklist.test.ts:522-535
The sequence shows the communication flow between the UI, the host runtime, and the external AI agent process.
Sources: src/renderer/lib/tests/parity-checklist.test.ts:520-545, src/renderer/lib/tests/parity-checklist.test.ts:600-610
API Bridge and Platform Adapters
Termul uses a unified api.ts bridge to isolate desktop integrations from UI code. This bridge exports singletons that abstract platform-specific implementation details.
Key API Facades
terminalApi: Manages PTY spawning, writing, and resizing. Desktop implementations useinvokewhile web implementations usetauri-ptyequivalent over WebSocket.filesystemApi: Provides file operations and directory watching. On web, this utilizes an Axum-based HTTP API at/fs/*.workspaceManifestApi: Handles persistent workspace layouts throughgetManifestandwriteManifestoperations.sessionApi: Manages the application session state, including save/restore operations.
Sources: src/renderer/lib/api.ts:20-50, src/renderer/lib/tests/parity-checklist.test.ts:135-155, src/renderer/lib/tests/worktree-api.web.test.ts:55-75
Conclusion
Termul's architecture emphasizes host authority. By centering the Rust runtime as the sole owner of PTY sessions, ACP agent transcripts, and workspace manifests, the system ensures that state remains consistent whether accessed via a local desktop window or a remote browser. The use of strict API facades and adapter patterns allows the codebase to scale across different platforms without duplicating business logic or sacrificing technical reliability.
Sources: AGENTS.md:28-35, src/renderer/lib/tests/parity-checklist.test.ts:550-565