Configuration & App Preferences
Relevant source files
The following files were used as context for generating this wiki page:
Termul utilizes a dual-layered configuration system consisting of global Application Preferences and local Project Settings. Application Preferences govern the behavior and appearance of the entire desktop environment, including terminal rendering, keyboard shortcuts, and AI agent timeouts. Project Settings provide granular control over individual workspaces, allowing users to define environment variables, shell overrides, and worktree symlink directories.
The configuration architecture relies on Zustand stores for reactive state management and interacts with the Rust runtime via specialized APIs (e.g., acpApi, shellApi, terminalApi) to apply changes immediately to the PTY manager and AI agent processes.
Sources: README.md:92-100, src/renderer/pages/AppPreferences.tsx:32-60, src/renderer/pages/ProjectSettings.tsx:102-120
Application Preferences Architecture
The Application Preferences system manages global state across several domains: Appearance, Behavior, AI Agents, and Updates. When a user modifies a setting in the AppPreferencesModal, the useUpdateAppSetting hook updates the app-settings-store. Certain settings trigger immediate side effects in the native runtime, such as updating orphan detection timeouts in the PtyManager.
The diagram shows the flow of a preference update from the UI to the reactive store and subsequent native side effects.
Sources: src/renderer/pages/AppPreferences.tsx:135-200, src/renderer/pages/app-preferences/behavior-section.tsx:55-100
Global Configuration Options
| Category | Option | Description |
|---|---|---|
| Appearance | terminalFontSize | Sets the font size for all XTerm instances. |
uiZoomLevel | Controls the global scaling of the React renderer. | |
terminalRenderer | Toggles between webgl, canvas, or dom rendering. | |
| Behavior | orphanDetection | Automatically cleans up inactive terminal processes. |
editorAutoSave | Automatically saves file buffers after a specified delay. | |
| AI Agents | acpTurnTimeout | Hard cap on duration for an AI agent's turn. |
acpSessionNewTimeout | Budget for initializing new agent sessions. | |
| Shell | defaultShell | The primary shell used for new terminals (e.g., powershell, zsh). |
Sources: src/renderer/pages/AppPreferences.tsx:64-90, src/renderer/pages/app-preferences/behavior-section.tsx:15-50, src-tauri/tauri.conf.json:34-45
Project Settings & Workspaces
Project Settings are specific to a single workspace ID. This module manages environment variables, shell execution parameters, and Git-specific configurations like worktree symlinks.
Environment Variable Management
Users can manually add key-value pairs or import them from a .env file located in the project root. The ProjectSettingsModal parses the .env file, validates lines, and merges variables into the project configuration. Secret values are masked in the UI but injected into the terminal session.
Worktree Symlinks
For Git-enabled projects, Termul supports auto-detecting directories from .gitignore to use as symlinks. This ensures shared dependencies (e.g., node_modules) are available across worktrees without redundant installations.
The sequence diagram represents the automated discovery of symlink directories via the Git configuration.
Sources: src/renderer/pages/ProjectSettings.tsx:165-210, src/renderer/pages/ProjectSettings.tsx:257-300
Project Scaffolding & Templates
Termul provides built-in templates to initialize new project directories. The scaffoldProject function handles the creation of the base directory, subdirectories, and boilerplate files with project-name interpolation.
// Example of the interpolation logic used during scaffolding
function interpolate(content: string, projectName: string): string {
const safeName = projectName.toLowerCase().replace(/[^a-z0-9_-]/g, '-')
return content.replace(/{{projectName}}/g, safeName)
}
Sources: src/renderer/lib/project-templates.ts:250-255
Available Templates
- Empty Project: No boilerplate files.
- Node.js: Includes
package.json,src/index.js, and.env.example. - Rust: Includes
Cargo.tomlandsrc/main.rs. - React App (Vite): Full TypeScript + Vite SPA structure.
- Python: Includes
main.pyandrequirements.txt.
Sources: src/renderer/lib/project-templates.ts:5-240
Native Integration & Security
Global settings are persisted via the @tauri-apps/plugin-store. The security policy defined in tauri.conf.json restricts the capabilities of the renderer to prevent unauthorized access, while allowing specific IPC communication for filesystem and process management.
- CSP (Content Security Policy): Restricts
script-srcandconnect-srctoself,ipc:, and trusted localhost/GitHub APIs. - Updater: Uses a Minisign public key for verifying signed artifacts during the auto-update flow.
Sources: src-tauri/tauri.conf.json:34-50, README.md:120-130
Conclusion
The configuration system in Termul balances global consistency with project-specific flexibility. By integrating reactive stores with native side effects, the application ensures that performance-critical settings like AI timeouts and terminal cleanup are enforced by the Rust runtime while remaining easily manageable through a unified React interface.