### Install libgtk-layer-shell0 for Ubuntu/Debian

Source: https://github.com/cjpais/handy/blob/main/README.md

Install the libgtk-layer-shell0 runtime package on Ubuntu or Debian systems if Handy fails to start due to missing libgtk-layer-shell.so.0.

```bash
sudo apt install libgtk-layer-shell0
```

--------------------------------

### Install gtk-layer-shell for Fedora/RHEL

Source: https://github.com/cjpais/handy/blob/main/README.md

Install the gtk-layer-shell runtime package on Fedora or RHEL systems if Handy fails to start due to missing libgtk-layer-shell.so.0.

```bash
sudo dnf install gtk-layer-shell
```

--------------------------------

### Start Development Server

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

Starts the Tauri development server to run the Handy application locally.

```bash
bun tauri dev
```

--------------------------------

### Install gtk-layer-shell for Arch Linux

Source: https://github.com/cjpais/handy/blob/main/README.md

Install the gtk-layer-shell runtime package on Arch Linux systems if Handy fails to start due to missing libgtk-layer-shell.so.0.

```bash
sudo pacman -S gtk-layer-shell
```

--------------------------------

### Install Dependencies

Source: https://github.com/cjpais/handy/blob/main/CRUSH.md

Installs project dependencies using Bun. Ensure Bun is installed before running.

```bash
bun install
```

--------------------------------

### Install Handy from Deb Bundle

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

Installs the Handy application from a .deb bundle on Linux, copying necessary files to system directories.

```bash
cd /tmp
ar x /path/to/Handy/src-tauri/target/release/bundle/deb/Handy_*_amd64.deb data.tar.gz
tar xzf data.tar.gz
sudo cp usr/bin/handy /usr/bin/
sudo cp -r usr/lib/Handy /usr/lib/
sudo cp -r usr/share/icons/hicolor/* /usr/share/icons/hicolor/
sudo cp usr/share/applications/Handy.desktop /usr/share/applications/
```

--------------------------------

### Start Handy Hidden with CLI

Source: https://github.com/cjpais/handy/blob/main/README.md

Use this flag to start Handy without displaying the main window.

```bash
handy --start-hidden
```

--------------------------------

### Combine Startup Flags for Handy

Source: https://github.com/cjpais/handy/blob/main/README.md

Example of combining startup flags for scenarios like autostart.

```bash
handy --start-hidden --no-tray
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

Installs all necessary project dependencies using the Bun package manager.

```bash
bun install
```

--------------------------------

### Install wtype for Wayland

Source: https://github.com/cjpais/handy/blob/main/README.md

Install the wtype package, recommended for text input on Wayland display servers. It is essential for Handy's text input functionality on Wayland.

```bash
sudo apt install wtype
```

--------------------------------

### Start Handy Without System Tray Icon

Source: https://github.com/cjpais/handy/blob/main/README.md

Use this flag to start Handy without the system tray icon.

```bash
handy --no-tray
```

--------------------------------

### Install ONNX Runtime and Build/Dev

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

For Intel Macs, install ONNX Runtime via Homebrew and set environment variables for dynamic linking when developing or building.

```bash
brew install onnxruntime
ORT_LIB_LOCATION=$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK=1 bun run tauri dev
```

```bash
ORT_LIB_LOCATION=$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK=1 bun run tauri build
```

--------------------------------

### Run Frontend Only

Source: https://github.com/cjpais/handy/blob/main/CRUSH.md

Starts the frontend development server using Vite. Useful for frontend-specific development without the Tauri overlay.

```bash
bun run dev
```

--------------------------------

### Install dotool for X11 and Wayland

Source: https://github.com/cjpais/handy/blob/main/README.md

Install the dotool package, which works on both X11 and Wayland. This tool requires adding your user to the 'input' group for proper functionality.

```bash
sudo apt install dotool
```

--------------------------------

### Install xdotool for X11

Source: https://github.com/cjpais/handy/blob/main/README.md

Install the xdotool package for reliable text input on X11 display servers. This tool supports direct typing and clipboard paste shortcuts.

```bash
sudo apt install xdotool
```

--------------------------------

### Run Development Server

Source: https://github.com/cjpais/handy/blob/main/CRUSH.md

Starts the full application development server with Tauri. For macOS with a specific CMake version, use the prefixed command.

```bash
bun run tauri dev
```

```bash
CMAKE_POLICY_VERSION_MINIMUM=3.5 bun run tauri dev
```

--------------------------------

### Install Linux Build Dependencies

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

Installs essential build tools and libraries for Linux distributions like Ubuntu/Debian, Fedora/RHEL, and Arch Linux.

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install build-essential libasound2-dev pkg-config libssl-dev libvulkan-dev vulkan-tools glslc libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev patchelf cmake
```

```bash
# Fedora/RHEL
sudo dnf groupinstall "Development Tools"
sudo dnf install alsa-lib-devel pkgconf openssl-devel vulkan-devel \
  gtk3-devel webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel \
  gtk-layer-shell gtk-layer-shell-devel \
  cmake
```

```bash
# Arch Linux
sudo pacman -S base-devel alsa-lib pkgconf openssl vulkan-devel \
  gtk3 webkit2gtk-4.1 libappindicator-gtk3 librsvg gtk-layer-shell \
  cmake
```

--------------------------------

### Configure Sway/i3 global shortcuts for Handy signals

Source: https://github.com/cjpais/handy/blob/main/README.md

Configure Sway or i3 to use Unix signals for controlling Handy transcription. This example shows how to bind keys to send SIGUSR2 for toggling and SIGUSR1 for toggling with post-processing.

```ini
bindsym $mod+o exec pkill -USR2 -n handy
bindsym $mod+p exec pkill -USR1 -n handy
```

--------------------------------

### Run Development Server

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING.md

Start the application in development mode using Tauri. On macOS, you might need to set a minimum CMake policy version if encountering errors.

```bash
bun run tauri dev
```

```bash
# On macOS if you encounter cmake errors:
CMAKE_POLICY_VERSION_MINIMUM=3.5 bun run tauri dev
```

--------------------------------

### Frontend Development Commands

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

Commands for frontend-only development, including starting the Vite dev server, building the frontend assets, and previewing the built application.

```bash
bun run dev
```

```bash
bun run build
```

```bash
bun run preview
```

--------------------------------

### Invoke Handy Binary Directly on macOS

Source: https://github.com/cjpais/handy/blob/main/README.md

On macOS, when Handy is installed as an app bundle, invoke the binary directly to control it.

```bash
/Applications/Handy.app/Contents/MacOS/Handy --toggle-transcription
```

--------------------------------

### Copy English Translation File

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING_TRANSLATIONS.md

Copy the default English translation file to your new language directory as a starting point.

```bash
cp src/i18n/locales/en/translation.json src/i18n/locales/[language-code]/translation.json
```

--------------------------------

### Update Handy Binary on Linux

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

After rebuilding, this command updates only the binary file in the system installation.

```bash
sudo cp src-tauri/target/release/handy /usr/bin/
```

--------------------------------

### Conventional Commits

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

Example of using conventional commit prefixes for Git commits. The message should focus on the 'why' behind the change.

```bash
feat: add new feature
fix: resolve bug
docs: update documentation
refactor: improve code structure
chore: perform maintenance task
```

--------------------------------

### Build for Production

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

Compiles a release binary and generates platform-specific bundles for the Handy application.

```bash
bun run tauri build
```

--------------------------------

### Display Handy CLI Help

Source: https://github.com/cjpais/handy/blob/main/README.md

Use this flag to show all available command-line flags for Handy.

```bash
handy --help
```

--------------------------------

### Clone Handy Repository

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING.md

Clone your forked repository and navigate into the project directory.

```bash
git clone git@github.com:YOUR_USERNAME/Handy.git
cd Handy
```

--------------------------------

### Build Production Application

Source: https://github.com/cjpais/handy/blob/main/CRUSH.md

Creates a production build of the entire application, including the frontend and backend with Tauri.

```bash
bun run tauri build
```

--------------------------------

### Clone Handy Repository

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

Clones the Handy project repository and navigates into the project directory.

```bash
git clone git@github.com:cjpais/Handy.git
cd Handy
```

--------------------------------

### Handy CLI Parameters

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

A list of command-line flags supported by the Handy application for runtime control. These flags override persisted settings and are handled via `tauri_plugin_single_instance` for running instances.

```bash
--toggle-transcription
--toggle-post-process
--cancel
--start-hidden
--no-tray
--debug
```

--------------------------------

### Configure Sway/i3 global shortcut for Handy

Source: https://github.com/cjpais/handy/blob/main/README.md

Add a global keyboard shortcut to your Sway or i3 configuration file to toggle Handy transcription. This uses the 'exec' command with the Handy CLI flag.

```ini
bindsym $mod+o exec handy --toggle-transcription
```

--------------------------------

### Download Model for Development

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

Downloads the Silero VAD model to the specified resources directory. This is a required step for development.

```bash
mkdir -p src-tauri/resources/models
curl -o src-tauri/resources/models/silero_vad_v4.onnx https://blob.handy.computer/silero_vad_v4.onnx
```

--------------------------------

### Toggle Post-Processing with Handy CLI

Source: https://github.com/cjpais/handy/blob/main/README.md

Use this flag to toggle recording with post-processing enabled or disabled on a running Handy instance.

```bash
handy --toggle-post-process
```

--------------------------------

### Run Development Server

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING_TRANSLATIONS.md

Use this command to run the Tauri development server and test your translation changes locally.

```bash
bun run tauri dev
```

--------------------------------

### Verify Release Signature with Minisign

Source: https://github.com/cjpais/handy/blob/main/README.md

This script verifies the signature of Handy release artifacts using minisign. It requires the downloaded artifact, a public key file, and a signature file.

```bash
# Replace with the file you downloaded
ARTIFACT="Handy_0.8.1_amd64.AppImage"

python3 - "$ARTIFACT" <<'PY'
import base64, pathlib, sys

artifact = sys.argv[1]

pub = pathlib.Path("handy.pub.b64").read_text().strip()
pathlib.Path("handy.pub").write_bytes(base64.b64decode(pub))

sig = pathlib.Path(f"{artifact}.sig").read_text().strip()
pathlib.Path(f"{artifact}.minisig").write_bytes(base64.b64decode(sig))
PY

minisign -Vm "$ARTIFACT" \
  -p handy.pub \
  -x "$ARTIFACT.minisig"
```

--------------------------------

### Build Frontend

Source: https://github.com/cjpais/handy/blob/main/CRUSH.md

Builds the frontend application using Vite. This command is also used for validation during the build process.

```bash
bun run build
```

--------------------------------

### Configure Hyprland global shortcut for Handy

Source: https://github.com/cjpais/handy/blob/main/README.md

Add a global keyboard shortcut to your Hyprland configuration file to toggle Handy transcription. This uses the 'bind' directive with the 'exec' action.

```ini
bind = $mainMod, O, exec, handy --toggle-transcription
```

--------------------------------

### Enable Debug Mode with Handy CLI

Source: https://github.com/cjpais/handy/blob/main/README.md

Use this flag to enable debug mode, which provides verbose logging.

```bash
handy --debug
```

--------------------------------

### Create Models Directory on macOS/Linux

Source: https://github.com/cjpais/handy/blob/main/README.md

Command to create the 'models' directory within the Handy application data path on macOS and Linux systems.

```bash
# macOS/Linux
mkdir -p ~/Library/Application\ Support/com.pais.handy/models
```

--------------------------------

### Download Model

Source: https://github.com/cjpais/handy/blob/main/CRUSH.md

Downloads the ONNX model for Silero VAD. This is required for voice activity detection functionality.

```bash
mkdir -p src-tauri/resources/models
curl -o src-tauri/resources/models/silero_vad_v4.onnx https://blob.handy.computer/silero_vad_v4.onnx
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

Keyboard shortcuts to enable debug mode in the Handy application. This provides verbose logging for troubleshooting.

```bash
Cmd+Shift+D (macOS)
Ctrl+Shift+D (Windows/Linux)
```

--------------------------------

### Disable GTK Layer Shell Overlay

Source: https://github.com/cjpais/handy/blob/main/README.md

Run Handy with HANDY_NO_GTK_LAYER_SHELL=1 to disable GTK layer shell initialization as a workaround for Wayland/KDE Plasma issues.

```bash
HANDY_NO_GTK_LAYER_SHELL=1 handy
```

--------------------------------

### Manually Run linuxdeploy for Debugging

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

Executes linuxdeploy manually to diagnose AppImage build failures on rolling-release Linux distributions.

```bash
cd src-tauri/target/release/bundle/appimage
~/.cache/tauri/linuxdeploy-x86_64.AppImage --appimage-extract-and-run \
  --appdir Handy.AppDir --plugin gtk --output appimage
```

--------------------------------

### Build Production Bundles Excluding AppImage

Source: https://github.com/cjpais/handy/blob/main/BUILD.md

Builds production bundles for Handy, specifically excluding the AppImage format to bypass build failures on certain Linux distributions.

```bash
bun run tauri build -- --bundles deb
```

--------------------------------

### Whisper Model Directory Structure

Source: https://github.com/cjpais/handy/blob/main/README.md

Place Whisper GGML .bin files directly into the 'models' directory. Ensure exact filenames are used as downloaded.

```bash
{app_data_dir}/models/
├── ggml-small.bin
├── whisper-medium-q4_1.bin
├── ggml-large-v3-turbo.bin
└── ggml-large-v3-q5_0.bin
```

--------------------------------

### Toggle Handy transcription with post-processing using SIGUSR1

Source: https://github.com/cjpais/handy/blob/main/README.md

Send a SIGUSR1 signal to the Handy process to toggle transcription with post-processing enabled. This allows for signal-based control of Handy's features.

```bash
pkill -USR1 -n handy
```

--------------------------------

### Toggle Transcription with Handy CLI

Source: https://github.com/cjpais/handy/blob/main/README.md

Use this flag to toggle the recording status of a running Handy instance.

```bash
handy --toggle-transcription
```

--------------------------------

### Rust Code Formatting and Linting

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

Commands to format Rust code using `cargo fmt` and run clippy for linting. These should be executed before committing code.

```bash
cargo fmt
cargo clippy
```

--------------------------------

### Make Workaround Permanent in .desktop File

Source: https://github.com/cjpais/handy/blob/main/README.md

Prefix the 'Exec=' line in a .desktop file with 'env VARIABLE=value' to make a workaround permanent for Handy.

```ini
Exec=env HANDY_NO_GTK_LAYER_SHELL=1 handy
```

--------------------------------

### Create Models Directory on Windows (PowerShell)

Source: https://github.com/cjpais/handy/blob/main/README.md

Command to create the 'models' directory within the Handy application data path on Windows using PowerShell.

```powershell
# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\com.pais.handy\models"
```

--------------------------------

### Create New Language Folder

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING_TRANSLATIONS.md

Use this bash command to create a new directory for your language translations, named after its ISO 639-1 code.

```bash
mkdir src/i18n/locales/[language-code]
```

--------------------------------

### Push to Fork

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING.md

Push your local feature branch to your remote fork to prepare for a pull request.

```bash
git push origin feature/your-feature-name
```

--------------------------------

### Parakeet Model Directory Structure

Source: https://github.com/cjpais/handy/blob/main/README.md

Extract Parakeet .tar.gz archives and place the extracted directory into the 'models' folder. The directory name must match the specified format.

```bash
{app_data_dir}/models/
├── parakeet-tdt-0.6b-v2-int8/     (directory with model files inside)
│   ├── (model files)
│   └── (config files)
└── parakeet-tdt-0.6b-v3-int8/     (directory with model files inside)
    ├── (model files)
    └── (config files)
```

--------------------------------

### Create Feature Branch

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING.md

Use these commands to create a new branch for feature development or bug fixes.

```bash
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
```

--------------------------------

### Add user to input group for dotool

Source: https://github.com/cjpais/handy/blob/main/README.md

Add your user to the 'input' group to enable dotool functionality. This change requires logging out and back in to take effect.

```bash
sudo usermod -aG input $USER
```

--------------------------------

### Toggle Handy transcription with SIGUSR2 signal

Source: https://github.com/cjpais/handy/blob/main/README.md

Send a SIGUSR2 signal to the Handy process to toggle transcription. This method is useful for managing shortcuts via Unix signals, especially on Wayland.

```bash
pkill -USR2 -n handy
```

--------------------------------

### Update Fork

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING.md

Keep your local repository up-to-date with the upstream main branch before rebasing.

```bash
git fetch upstream
git rebase upstream/main
```

--------------------------------

### Lint and Format Code

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

Commands for maintaining code quality. Use `lint:fix` and `format:check` for automated fixes and verification. `format` applies both Prettier and cargo fmt.

```bash
bun run lint
```

```bash
bun run lint:fix
```

```bash
bun run format
```

```bash
bun run format:check
```

```bash
bun run format:frontend
```

```bash
bun run format:backend
```

--------------------------------

### Recording Overlay CSS

Source: https://github.com/cjpais/handy/blob/main/src/overlay/index.html

Applies to the html and body elements to ensure no margins or padding, a transparent background, and full viewport coverage. Also styles the root element for overflow and dimensions.

```css
html, body {
  margin: 0;
  padding: 0;
  background: transparent;
  overflow: hidden;
  width: 100%;
  height: 100%;
}

#root {
  width: 100%;
  height: 100%;
  overflow: hidden;
}
```

--------------------------------

### Commit Changes

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING.md

Commit your changes using conventional commit messages. Use 'feat:' for new features and 'fix:' for bug fixes.

```bash
git add .
git commit -m "feat: add your feature description"
# or
git commit -m "fix: describe the bug fix"
```

--------------------------------

### Add Upstream Remote

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING.md

Add the upstream remote to track changes from the main repository.

```bash
git remote add upstream git@github.com:cjpais/Handy.git
```

--------------------------------

### Disable WebKit DMA-BUF Renderer

Source: https://github.com/cjpais/handy/blob/main/README.md

Run Handy with WEBKIT_DISABLE_DMABUF_RENDERER=1 to disable the WebKitGTK DMA-BUF renderer, which can cause rendering failures or crashes on certain GPU/driver combinations.

```bash
WEBKIT_DISABLE_DMABUF_RENDERER=1 handy
```

--------------------------------

### Cancel Operation with Handy CLI

Source: https://github.com/cjpais/handy/blob/main/README.md

Use this flag to cancel the current operation of a running Handy instance.

```bash
handy --cancel
```

--------------------------------

### Register New Language Metadata

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING_TRANSLATIONS.md

Add your language's metadata, including its display name and native name, to the `LANGUAGE_METADATA` object in `src/i18n/languages.ts`.

```typescript
export const LANGUAGE_METADATA: Record<
  string,
  { name: string; nativeName: string }
> = {
  en: { name: "English", nativeName: "English" },
  es: { name: "Spanish", nativeName: "Español" },
  fr: { name: "French", nativeName: "Français" },
  vi: { name: "Vietnamese", nativeName: "Tiếng Việt" },
  de: { name: "German", nativeName: "Deutsch" }, // ← Add your language
};
```

--------------------------------

### Use i18next Translation in React Component

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

Demonstrates how to use the `useTranslation` hook from i18next to access translation keys within a React component. Ensure translation keys are added to the appropriate JSON locale file.

```typescript
import { useTranslation } from "react-i18next";

function MyComponent() {
  const { t } = useTranslation();

  return (
    <div>
      {t('greeting.message')}
    </div>
  );
}
```

--------------------------------

### Disable GTK Layer Shell on Linux

Source: https://github.com/cjpais/handy/blob/main/AGENTS.md

Environment variable to disable the GTK layer shell for the overlay on Linux. This is a platform-specific configuration for Wayland compatibility.

```bash
HANDY_NO_GTK_LAYER_SHELL=1
```

--------------------------------

### Handle Variables in Translations

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING_TRANSLATIONS.md

Ensure that variables enclosed in double curly braces, like `{{error}}`, are kept exactly as they appear in the original English string. Do not translate or modify these variables.

```json
// English
"downloadModel": "Failed to download model: {{error}}"

// French (correct)
"downloadModel": "Échec du téléchargement du modèle : {{error}}"

// French (incorrect - don't translate the variable!)
"downloadModel": "Échec du téléchargement du modèle : {{erreur}}"
```

--------------------------------

### Type Checking

Source: https://github.com/cjpais/handy/blob/main/CRUSH.md

Performs type checking on the TypeScript code without emitting JavaScript files. Ensures code quality and catches type-related errors.

```bash
bunx tsc --noEmit
```

--------------------------------

### Translate JSON Values

Source: https://github.com/cjpais/handy/blob/main/CONTRIBUTING_TRANSLATIONS.md

When translating, only modify the string values on the right side of the colon. Do not change the keys on the left, preserve `{{variables}}`, and maintain the JSON structure.

```json
{
  "sidebar": {
    "general": "General",      // ← Translate this value
    "advanced": "Advanced",    // ← Translate this value
    ...
  }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.