Skip to main content

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 local UiIcon 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.
The LeftSidebar switches the main content area between four top-level sections. The NavSection 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

The thread 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 at config/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.
Each manifest entry declares the launch command, icon, and flags for session tracking, resuming, model selection, and auto-approval. See Supported agents.

Settings sections

SettingsPanel.tsx has 13 sections, grouped into General and Help:

State and persistence

State lives in 24 stores under src/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 in src/icons/:
  • UiIcon.tsx — the single icon component used across the UI. The icon pack is generated by scripts/gen-ui-icons.mjs and resolved through resolveIcon.ts and IconPackContext.
  • FileIcon.tsx — maps file names and extensions to file-type icons.
lucide-react has been fully migrated out (scripts/migrate-lucide.mjs); do not import it in new code.

Patterns

  • Memoization — per-session badges (SessionBadges.tsx) are memo() boundaries so a parent re-render does not cascade into every tab and sidebar row.
  • Portal rendering — modals, menus, and context menus render through createPortal into document.body to 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.