Overview
Tempest is a Tauri + React desktop application. The UI follows a split-pane workspace layout: a left sidebar for project and workspace navigation, a central content area for terminal sessions and tool panes, and a collapsible right panel for the file tree and git changes. Terminal rendering uses xterm.js and code editing uses CodeMirror 6. Icons come from a localUiIcon system rather than a third-party icon library — see Icon system.
App shell
WorkspaceView (src/components/WorkspaceView.tsx, roughly 2,600 lines) is the root container. It owns session lifecycle, the tab bar, the split-pane layout tree, global keyboard shortcuts, dialogs, and the top-level navigation sections. The components around it:
- TopBar / TitleBar — frameless window chrome: Tempest mark, window controls, and the zen-mode button (currently disabled).
- LeftSidebar — navigation sections plus the project, worktree, and session tree. See Sidebar.
- AgentTabs — the tab bar across the top of the workspace.
- RightSidebar — file tree and git changes panel.
- StatusBar — status strip along the bottom of the window.
- DynamicIsland — floating island for session activity notifications.
Zen mode has Rust-level window support, but the UI entry point is disabled — the TopBar button is labeled “coming soon”. It is infrastructure, not a usable feature.
Navigation sections
The LeftSidebar switches the main content area between four top-level sections. TheNavSection type is "overview" | "knowledge-base" | "tasks" | "automations":
Pane types
Each tab in the workspace renders one of four pane types, or the Threads canvas:
Details:
- TerminalPane renders each session’s PTY with xterm.js (fit, search, unicode11, and web-links addons). It reads theme colors from CSS variables so themes hot-swap without recreating the PTY, handles clipboard and in-terminal search keys, registers with SessionManager for output buffering, and drives work-done detection for agent sessions. A ResizeObserver keeps PTY dimensions in sync with the container.
- DiffPane shows staged and unstaged changes, supports staging and unstaging individual files or everything at once, and provides a commit form with optional co-author attribution. It also includes the DiscardFileDialog and DeleteBranchDialog sub-dialogs.
- PreviewPane hosts a dev server in an iframe with a URL/port picker, device size presets, navigation controls, and quick-launch buttons for common ports.
- CodeMirrorPane is a CodeMirror 6 editor for opening files from the file tree.
Threads canvas
Thethread tab kind opens the Threads canvas — a spatial graph where work is laid out as connected nodes. Node types include chat, text, agent, terminal, file, image, media, site, and collapsed groupings. Chat nodes are real conversations backed by BYOK providers or CLI-backed agent bridges; see Threads and Chat.
Key files
Dialog components are covered in detail on Dialogs and Modals; the individual panes on Panes.
Agent registry
Tempest ships a manifest of bundled agents atconfig/agents.json — 16 agents: agy (Antigravity), claude, cline, codex, copilot, cursor, gemini, goose, opencode, hermes, pi, amp, fx, qwen, droid, and grok.
src/lib/agentRegistry.ts derives AGENT_CONFIGS from that manifest (NewSessionMenu re-exports it). At startup the registry merges two more sources on top:
- A remote manifest, verified with minisign before it is applied.
- User-added agents from Settings → Agents.
Settings sections
SettingsPanel.tsx has 13 sections, grouped into General and Help:
State and persistence
State lives in 24 stores undersrc/store/ (sessions, tabs, threads, threadMessages, messageQueue, workState, keybindings, appSettings, prompts, attribution, and more). Each is a plain external store consumed through useSyncExternalStore, so components subscribe to exactly the slices they render.
Persistence is SQLite through the Tauri backend. tempest.db holds relational tables — projects, branches, sessions, tabs, layouts, threads — plus an app_state table containing a single JSON row (key "runtime") for app-global preferences such as settings, keybindings, session order, the active instance, prompts, and the active theme. Stores hydrate from SQLite at startup and flush writes asynchronously. See State management.
Three things are intentionally stored in localStorage instead:
- The PrDialog GitHub token (
tempest-github-token) - Tasks page filter state (
tempest:tasks-page:v1) - Custom run commands (
tempest-run-custom:{cwd})
Icon system
Icons come from a local system insrc/icons/:
UiIcon.tsx— the single icon component used across the UI. The icon pack is generated byscripts/gen-ui-icons.mjsand resolved throughresolveIcon.tsandIconPackContext.FileIcon.tsx— maps file names and extensions to file-type icons.
scripts/migrate-lucide.mjs); do not import it in new code.
Patterns
- Memoization — per-session badges (
SessionBadges.tsx) arememo()boundaries so a parent re-render does not cascade into every tab and sidebar row. - Portal rendering — modals, menus, and context menus render through
createPortalintodocument.bodyto escape scroll clipping and stacking contexts. - Ref stabilization — WorkspaceView keeps refs (pane layout, sessions, shortcut handler) so long-lived event listeners registered once at mount never read stale state.
- Keyboard shortcuts — app shortcuts are rebindable ActionIds from
src/store/keybindings.ts; see Keyboard shortcuts.