Contributing to Tempest

August 9, 2026 · View on GitHub

Thanks for your interest in contributing. Tempest is an open, early-stage project — bug reports, small fixes, and larger contributions are all welcome. This guide covers how to get set up, how the repo is organised, and what to expect when you open a pull request.

Table of contents

Ways to contribute

  • File a bug — use the bug report template
  • Suggest a feature — use the feature request template, or check ROADMAP.md for open workstreams
  • Send a pull request — small fixes need no discussion; for larger changes, open an issue first so we can align on approach
  • Improve docs — the marketing site (web/) and Mintlify docs (docs/) are in this same repo
  • Report a vulnerability — see SECURITY.md; do not open a public issue for security problems

If you want to work on something bigger, the Tempest Bridge workstream on the roadmap is the front door for collaboration.

Repository layout

tempest-git/
├── src/              React frontend (Tauri app)
├── src-tauri/        Rust backend (Tauri app)
├── packages/atlas/   Token Intelligence — code graph MCP server
├── web/              Marketing website (Next.js)
└── docs/             Documentation (Mintlify)

Prerequisites

  • Node.js 20 or later
  • Rust (stable)
  • Tauri CLI dependencies for your OS
  • Windows only: WebView2 (ships with Windows 11; standalone installer available for Windows 10)

Getting started

# Clone the repo
git clone https://github.com/tempestai-dev/tempest.git
cd tempest

# Install all workspace dependencies (app + web + docs)
npm install

# Build the atlas bundle (required before first dev run)
npm run setup

# Start the desktop app
npm run dev

Running individual pieces

npm run dev          # Tauri desktop app
npm run dev:web      # Marketing website  (localhost:3000)
npm run dev:docs     # Documentation      (localhost:3001)

Type checking

Both must pass clean before a PR can be merged:

npx tsc --noEmit          # Frontend TypeScript
cargo check               # Rust backend

Please run these locally rather than relying on CI to catch issues.

Making changes

Desktop app (src/ + src-tauri/)

  • Frontend: React 19, Vite, TypeScript — lives in src/
  • Backend: Tauri commands, PTY, git operations — lives in src-tauri/src/lib.rs
  • CSS variables only — no hardcoded colours; all values go through --tempest-* vars so themes work
  • No React.StrictMode — it double-invokes effects and breaks PTY spawning

Atlas package (packages/atlas/)

  • Run npm run build:atlas after any changes before testing in the app
  • tsc --noEmit must pass inside packages/atlas/

Website (web/)

npm run dev:web
npm run build:web

Docs (docs/)

npm run dev:docs
npm run build:docs

Submitting a pull request

  1. Fork the repo and create a branch from main
  2. Make your changes — keep the PR focused on one thing
  3. Run npx tsc --noEmit and cargo check — fix any errors
  4. Push and open a PR against main; the PR template will guide you
  5. Link the issue you're closing, and note anything a reviewer should test manually
  6. Be responsive to review feedback — small, iterative rounds land faster than one giant push

We aim to give an initial response within a few days. If a PR goes quiet for longer, feel free to ping.

Reporting bugs

Use the bug report template. Include:

  • OS and version
  • Tempest version
  • Steps to reproduce
  • What you expected vs what happened
  • Logs or screenshots if you have them (redact anything sensitive)

Security issues

Do not open a public issue. Email gsvprharsha@tempestai.dev — full policy in SECURITY.md.

Commit style

Plain imperative subject line, no emoji, no period at the end. A conventional prefix is helpful but not required.

fix: resolve atlas indexing in production builds
feat: add command palette
chore: update dependencies
docs: clarify Hephaestus scope in README

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License that covers the project.