Skip to main content

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):
  1. Starts the Vite dev server on http://localhost:1420
  2. Launches the Tauri webview pointing at the dev server
  3. Hot-reloads React/TypeScript changes; recompiles Rust when src-tauri/ files change
The app opens in a frameless window with custom styling via Tauri’s window configuration. For frontend-only work without rebuilding Rust:
This starts the Vite dev server only. Changes to React/TypeScript hot-reload instantly.

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 as config/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:
  1. Add an entry to config/agents.json with the agent’s command, flag templates (flags.session, flags.resume, flags.model, flags.autoApprove, flags.print), and optionally a capture spec for agents that print their own session ID.
  2. Commit the icon to config/agent-icons/ (bundled built-ins also live in src/assets/agent-icons/).
  3. Verify each flag against the CLI’s own --help, then run npm test — src/lib/agentsManifestFile.check.ts validates the shipped manifest (unique ids, resolvable icons, known placeholders).
  4. New agent entries reach existing installs through the signed remote manifest once config/agents.json.minisig is regenerated; until then they ship with the next release’s bundled floor.

Adding a New Theme

Themes are JSON files stored in src/themes/{theme-name}/theme.json.

Step 1: Create the theme file

In src/themes/my-theme/theme.json:
All color tokens are required. See 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 via invoke() and handled by #[tauri::command] functions in Rust.

Example: Read a File

Step 1: Add the Rust function in src-tauri/src/lib.rs:
Tauri automatically serializes the return type to JSON and deserializes errors. Step 2: Register the command in the builder in lib.rs:
Step 3: Call from React in src/components/MyComponent.tsx:

Tauri Command Patterns

Returning data:
Returns JSON-serializable types. Use serde::Serialize on structs. Taking parameters:
Function arguments are automatically deserialized from the invoke call’s payload. Long-running commands with streaming: For long operations (like indexing files), use Tauri channels:
On the frontend, listen for events:

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.
CSS variables follow the naming pattern: --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 under src/store/ built on React’s useSyncExternalStore — plain objects with getter/setter functions, plus use* hooks that subscribe with fine-grained selectors. The general shape:
Settings that must survive restarts are written through the runtime state layer (persisted to the SQLite 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 as src/**/*.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.
There is no Vitest at the repo root (only the published Atlas package uses Vitest in its own repository) and no Rust integration-test directory. Manual testing via the dev build is still standard for UI work:
  1. Run npm run dev
  2. Interact with the feature in the app
  3. Check the browser console (F12) for errors
  4. Verify the expected behavior
If you add a pure function with edge cases, add a .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

On Windows this produces an NSIS installer, an MSI, and a portable .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

  1. Frontend logs - Open DevTools (F12) and check the Console tab
  2. Tauri logs - Right-click the Tempest window and select “Inspect” to see the native console
  3. React state - Install React DevTools browser extension and inspect component props/state
  4. Network requests - Check the Network tab for API calls (e.g., GitHub PR creation)
  5. 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.rs to see available Tauri commands
  • Check ROADMAP.md for upcoming features and architecture decisions
  • Join the community on X/Twitter (@usetempest) for questions and discussions