Contributing to Tempest
This guide covers the Tempest project structure, development workflow, and how to extend the application with new features like agents, themes, and Tauri commands.Project Structure
Tempest is organized into frontend (React/TypeScript) and backend (Rust/Tauri) components:Running the Dev Build
Prerequisites: Node.js 20+, Rust (latest stable via rustup), WebView2 Runtime (Windows only)npm install runs the postinstall scripts, which stage the bundled sidecars into src-tauri/resources/ (the Atlas runtime from the @usetempest/atlas package, the chat bridge Node dependencies) and fetch the cloudflared tunnel binary.
The dev command (tauri dev):
- Starts the Vite dev server on http://localhost:1420
- Launches the Tauri webview pointing at the dev server
- Hot-reloads React/TypeScript changes; recompiles Rust when
src-tauri/files change
Production Build
npm run build runs tauri build and then scripts/collect-artifacts.mjs. On a Windows machine it produces an NSIS installer, an MSI, and a portable .exe, copying the NSIS installer and the portable executable to dist-installers/ alongside updater artifacts. The released macOS and Linux artifacts (.dmg/.app.tar.gz, .AppImage/.deb) are built by CI.
Adding a New Agent
Agents are manifest-driven. The bundled list ships asconfig/agents.json (16 agents), is merged with a minisign-verified remote manifest fetched from this repository, and is further merged with user-added agents from Settings → Agents. AGENT_CONFIGS is derived from that manifest via src/lib/agentRegistry.ts — there is no hardcoded agent array to edit.
The full procedure — manifest entry shape, flag templates, placeholders, icon rules, and the validation checks — is documented in Supported Agents. The short version:
- Add an entry to
config/agents.jsonwith the agent’scommand, flag templates (flags.session,flags.resume,flags.model,flags.autoApprove,flags.print), and optionally acapturespec for agents that print their own session ID. - Commit the icon to
config/agent-icons/(bundled built-ins also live insrc/assets/agent-icons/). - Verify each flag against the CLI’s own
--help, then runnpm test—src/lib/agentsManifestFile.check.tsvalidates the shipped manifest (unique ids, resolvable icons, known placeholders). - New agent entries reach existing installs through the signed remote manifest once
config/agents.json.minisigis regenerated; until then they ship with the next release’s bundled floor.
Adding a New Theme
Themes are JSON files stored insrc/themes/{theme-name}/theme.json.
Step 1: Create the theme file
Insrc/themes/my-theme/theme.json:
src/themes/tempest-dark/theme.json for the complete reference.
Step 2: Rebuild
Themes are auto-discovered:ThemeContext globs src/themes/**/theme.json at build time via import.meta.glob, so placing your directory in src/themes/ and rebuilding is all the registration needed — there is no THEMES array to edit.
Step 3: Test
Restart the dev server and open Settings > Appearance. Your theme should appear in the theme grid.Adding a New Tauri Command
Tauri commands bridge the React frontend and Rust backend. They are called from TypeScript viainvoke() and handled by #[tauri::command] functions in Rust.
Example: Read a File
Step 1: Add the Rust function insrc-tauri/src/lib.rs:
lib.rs:
src/components/MyComponent.tsx:
Tauri Command Patterns
Returning data:serde::Serialize on structs.
Taking parameters:
Code Patterns and Style
React Components
Components use functional components with hooks:CSS Variables for Theming
Always use CSS variables for colors and UI tokens. Never hardcode color values.--tempest-{token.with.dots} becomes --tempest-{token-with-dashes}.
Error Handling
Use Result types and bubble errors:State Management
Tempest does not use Redux, Zustand, or Jotai. State lives in module-singleton stores undersrc/store/ built on React’s useSyncExternalStore — plain objects with getter/setter functions, plus use* hooks that subscribe with fine-grained selectors. The general shape:
app_state table) rather than held only in a store — see State Management.
TypeScript Types
Always define prop types and return types explicitly:Testing
Tempest uses lightweight self-checks rather than a test framework: assertions live assrc/**/*.check.ts files that import pure functions and assert with node:assert (Node strips TS types natively). tests/run.mjs discovers every check file and runs each in its own Node process.
- Run
npm run dev - Interact with the feature in the app
- Check the browser console (F12) for errors
- Verify the expected behavior
.check.ts beside it so npm test guards it.
For debugging:
- Use React DevTools browser extension to inspect component state
- Use the Tauri DevTools (right-click > Inspect) to see window/console output
- Add
console.log()statements liberally
Building for Release
.exe; scripts/collect-artifacts.mjs copies the NSIS setup executable and the portable executable to dist-installers/ alongside updater artifacts. The released macOS and Linux artifacts are built by CI.
Performance Considerations
Large File Trees
The file tree in the right sidebar is lazy-loaded. Nested folders do not fetch contents until expanded. This keeps the sidebar responsive even in large monorepos.Git Status
Git status operations are debounced and only refresh the Changes tab, not the file tree. This prevents layout shifts while browsing.Terminal Rendering
The embedded xterm.js terminal uses WebGL acceleration when available (via@xterm/addon-webgl). The WebGL context is pooled to avoid creating too many contexts simultaneously.
Code Editor
Syntax highlighting uses CodeMirror with language-specific tokenizers. Avoid rendering very large files (10k+ lines) in the editor at once.Debugging Tips
- Frontend logs - Open DevTools (F12) and check the Console tab
- Tauri logs - Right-click the Tempest window and select “Inspect” to see the native console
- React state - Install React DevTools browser extension and inspect component props/state
- Network requests - Check the Network tab for API calls (e.g., GitHub PR creation)
- Git operations - Git commands are invoked via Tauri; check stderr for git error messages
Next Steps
- Explore
src/components/to understand UI patterns - Read through
src-tauri/src/lib.rsto see available Tauri commands - Check
ROADMAP.mdfor upcoming features and architecture decisions - Join the community on X/Twitter (@usetempest) for questions and discussions