Onboarding Guide

First Steps

Get added to the GitHub organization and the hyprnote repo
Read through this handbook — start with What Hyprnote Is, Design Philosophy, and Product Philosophy
Download a staging build and use the app yourself
Set up your local development environment (see below)

Development Environment

Editor

If you don't have a specific preference, we recommend using Cursor. It has good AI-assisted editing and works well with our codebase.

Visual Editor intro — useful for learning Cursor basics

Repository Setup

Follow the developer setup guide for full instructions. The short version:

Mac:

brew install cmake pkg-config
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://github.com/fastrepl/hyprnote.git
cd hyprnote
pnpm install
pnpm -F ui build

Linux:

bash scripts/setup-linux.sh
git clone https://github.com/fastrepl/hyprnote.git
cd hyprnote
pnpm install

See Environment Variables for configuration, and Run for starting the dev server.

Troubleshooting

If Cursor cannot connect to the network when indexing the repo, try:

Ensure you have a stable internet connection
Restart Cursor and re-open the project
If the issue persists, you can still work by browsing the code directly — the project structure is documented in the developer docs

For Designers

Design work at Hyprnote lives close to the code. You don't need to be a full-stack engineer, but understanding the project structure helps you contribute effectively.

What to Explore First

Use the app — Download a staging build and use Hyprnote for your own meetings. The best design intuition comes from being a real user
Read the codebase — Browse apps/desktop/src/components/ to see how the UI is structured. The frontend is React + TypeScript + Tailwind CSS
Look at the UI library — packages/ui/ contains shared components built on Radix and styled with Tailwind

Design-to-Code Workflow

We use Figma for design exploration and prototyping. The workflow:

Explore in Figma — Use Figma (or Figma Make) to prototype ideas and iterate on static layouts
Share designs — Post screenshots or Figma links in Slack for feedback
Implement in code — Translate approved designs into React components. Use the existing component patterns in packages/ui/ and apps/desktop/src/components/
Open a PR — All changes go through pull requests on GitHub for review

Key Directories for UI Work

apps/desktop/src/components/ — Desktop app UI components
apps/web/src/ — Marketing website and docs
packages/ui/ — Shared component library (buttons, cards, dialogs, etc.)
extensions/ — Extension panels with their own React UIs
apps/web/content/ — MDX content for docs, handbook, blog, etc.

All written content (handbook, docs, blog posts) lives as MDX files in apps/web/content/. See the CMS page for how this works. You can contribute to docs and content by editing these files directly and opening a PR.

Downloading Staging Builds

Staging builds are created when testing new features before they go to nightly or stable releases. The easiest way to download the latest staging build is using the dedicated workflow:

Go to the Download Latest Staging Build workflow
Click "Run workflow"
Select the platform (currently macos-aarch64 for Apple Silicon Macs)
Click "Run workflow"
Once complete, download the artifact from the workflow run

Staging builds are stored in R2 with filenames like hyprnote-staging-{timestamp}-{commit}-macos-aarch64.dmg, making it easy to identify which commit a build corresponds to.