🤗 HugBrowse

A beautiful desktop app for browsing Hugging Face models — with hardware compatibility checks and plain-English ML explanations.

📸 Screenshots

☀️ Home — Trending models in light mode

🌙 Home — Dark mode for late-night browsing

📖 Model detail — README, files, and usage tabs

🖥️ "Can It Run?" — Hardware compatibility check

⚙️ Settings — Token, theme, and MCP configuration

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Rust 1.77+ and Cargo (for desktop builds)
• Visual Studio Build Tools 2022 with C++ workload (Windows only)

Run in Browser

1. Clone the repository and navigate to the hugbrowse folder
2. Install dependencies:

   npm install

3. Start the dev server:

   npm run dev

4. Open http://localhost:5173 in your browser

Run as Desktop App

npm run tauri:dev

This compiles the Rust backend and opens a native window (~10MB app).

✨ Features

⌨️ Keyboard Shortcuts

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   Tauri 2 Shell                      │
│  ┌───────────────────────────────────────────────┐  │
│  │              React Frontend                    │  │
│  │  ┌─────────┐ ┌──────────┐ ┌───────────────┐  │  │
│  │  │ Search  │ │  Detail  │ │   Settings    │  │  │
│  │  │  Page   │ │  Page    │ │    Page       │  │  │
│  │  └────┬────┘ └────┬─────┘ └──────┬────────┘  │  │
│  │       └────────┬───┘              │           │  │
│  │           TanStack Query Cache    │           │  │
│  │                │                  │           │  │
│  │    ┌───────────┴──────────────┐   │           │  │
│  │    │   HF REST API Client     │   │           │  │
│  │    └───────────┬──────────────┘   │           │  │
│  └────────────────┼──────────────────┼───────────┘  │
│                   │                  │              │
│  ┌────────────────┼──────────────────┼───────────┐  │
│  │         Rust Backend              │           │  │
│  │  ┌─────────────┐  ┌──────────────┴────────┐  │  │
│  │  │ System Info  │  │   MCP Client (HTTP)   │  │  │
│  │  │ CPU/RAM/GPU  │  │   HuggingFace MCP     │  │  │
│  │  └─────────────┘  └───────────────────────┘  │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘
              │                        │
    HuggingFace REST API    HuggingFace MCP Server
    huggingface.co/api      huggingface.co/mcp

The app is split into two layers:

• React Frontend — UI, routing, API calls, caching (TanStack Query), state management (Zustand)
• Rust Backend — System hardware detection via sysinfo crate, WMI for GPU info on Windows

📁 Project Structure

⚙️ Configuration

HuggingFace API Token

1. Go to huggingface.co/settings/tokens
2. Create a token with Read permissions
3. In HugBrowse → Settings → paste your token → click Validate
4. Token is stored locally (never sent to third parties)

Without a Token

All public models are accessible. Rate limit: ~100 requests/hour. Gated and private models are hidden.

Desktop Configuration

The Tauri config lives in src-tauri/tauri.conf.json:

• Window: 1200×800 (min 800×600)
• CSP: allows huggingface.co domains
• Plugins: shell, store (secure token storage)

🔗 API Integration

HuggingFace REST API (Primary)

All requests go through src/lib/hf-api.ts. Responses are cached by TanStack Query (5–10 minute stale time).

HuggingFace MCP Server (Optional)

URL: https://huggingface.co/mcp

Uses JSON-RPC 2.0 over HTTP POST. Provides enriched model metadata when available. The app works perfectly without it.

🖥️ "Can It Run?" — How It Works

Step 1: Estimate Model Size

model_size_gb = parameters_in_billions × bytes_per_parameter

Step 2: Add Overhead

needed_gb = model_size_gb × 1.2   // 20% for KV cache + runtime

Step 3: Compare Against Your Hardware

Example

💡 Explain Mode — ML Glossary

HugBrowse includes 25 ML terms explained in plain English. Hover over any highlighted term in the app to see a tooltip.

…and 13 more terms available in the app's glossary.

🏆 Hardware Tier System V2

HugBrowse V2 automatically classifies your PC into one of five hardware tiers on first launch. This drives every recommendation and compatibility decision in the app — you never have to manually enter specs.

Auto-Detection

The Rust backend queries your OS for total RAM and GPU VRAM on startup via sysinfo (and WMI on Windows for VRAM). Detection takes <50 ms and requires no permissions.

Tier Boundaries

Classification checks VRAM first (GPU-accelerated inference is far faster), then falls back to RAM for CPU-only machines. A laptop with an eGPU is classified by eGPU VRAM, not integrated graphics.

📊 Resource Monitor V2

The Resource Monitor panel (accessible from the sidebar or Ctrl+M) gives you a live view of system headroom before and while running models.

Circular Gauges

Four SVG ring-gauges update every 2 seconds. Color transitions are threshold-based:

Usage History Canvas

Below the gauges, a <canvas>-based rolling chart shows the last 30 minutes of CPU + RAM usage sampled every 2 seconds (900 data points). Each resource gets its own colour-coded line. Hover to inspect a specific timestamp.

"What Can I Load?" Headroom Panel

This panel reads current free VRAM and RAM (not total) and dynamically shows the largest model quant you could start right now:

free_vram_gb = total_vram - used_vram
free_ram_gb  = total_ram  - used_ram
max_loadable_gb = max(free_vram_gb, free_ram_gb * 0.9)
→ show all quants where model_size ≤ max_loadable_gb

Configurable Alerts

In Settings → Alerts you can set threshold sliders for each resource (RAM, VRAM). When usage crosses your threshold, a toast notification appears and the gauge ring pulses red. Alerts are opt-in and off by default.

⭐ Recommended Models V2

The Recommended tab shows a curated shortlist tailored to your hardware tier. Models are pre-filtered so you only ever see options you can actually run — no wasted time on incompatible downloads.

How Curation Works

• A static catalogue maps each tier to a set of vetted, community-trusted models
• The catalogue is updated with each app release; no internet catalogue fetch required
• Gated models (e.g. Llama 3) only appear if your API token is validated

Task Categories

Speed Estimate Badges

Each recommended model card shows a speed estimate based on your tier's compute profile:

Speed estimates are based on community benchmarks for each tier; actual speed depends on CPU/GPU generation, RAM bandwidth, and concurrent load.

🔬 Enhanced Compatibility V2

V2 significantly upgrades the "Can It Run?" panel with a full quantization comparison table, quality ratings, tier context, and a pre-download disk check.

Quantization Comparison Table

Instead of a single quant result, V2 shows a row per quantization level so you can pick the right trade-off:

⭐ Q4_K_M is the sweet-spot pick for most users — best speed/quality ratio.

Quality Rating Scale

Tier Context Banner

Each model card now shows which tier it was designed for, so you understand at a glance whether you're running it as intended or pushing it:

Disk Space Check

Before triggering a download, HugBrowse checks available disk space on your primary drive. If the selected quantization file is larger than free space minus a 2 GB safety margin, you'll see a warning prompt rather than a failed download.

🧮 "What Can My PC Run?" Calculator V2

Enter your hardware specs below and instantly see which model sizes and quantization levels are viable — sorted by what runs on your GPU vs CPU.

🛠️ Development Guide

Install Dependencies

npm install                  # Frontend
cd src-tauri && cargo fetch  # Rust (optional, auto-fetched)

Development Server

npm run dev          # Frontend only → http://localhost:5173
npm run tauri:dev    # Full Tauri desktop app

Type Checking & Linting

npx tsc --noEmit     # TypeScript errors
npm run lint         # ESLint

Key Libraries

📦 Building for Production

Frontend Only

npm run build     # Output: dist/ (~160KB gzipped)

Tauri Desktop Installer (Windows)

# Set up MSVC environment first
$msvc = "C:\...\MSVC\14.39.33519"
$winsdk = "C:\...\Windows Kits\10"
$env:PATH = "$winsdk\bin\x64;$msvc\bin\Hostx64\x64;$env:PATH"
$env:LIB = "$winsdk\Lib\um\x64;$winsdk\Lib\ucrt\x64;$msvc\lib\x64"
$env:INCLUDE = "$winsdk\Include\ucrt;...\um;...\shared;$msvc\include"

# Build installer
npm run tauri:build     # Output: src-tauri/target/release/bundle/msi/

🔧 Troubleshooting

"linker link.exe not found"

Install Visual Studio Build Tools from visualstudio.microsoft.com. Select "Desktop development with C++".

"cannot open input file kernel32.lib"

The Windows SDK path isn't set. Run the MSVC environment setup commands from the Building section.

Models not loading

• Check your internet connection
• HuggingFace may be rate-limiting — add a token in Settings
• Check browser console (F12) for error details

Dark mode not working

Click the theme icon in the header to cycle through System → Light → Dark. Theme is stored in localStorage under hugbrowse-settings.

"Can It Run?" shows "Unknown"

The model's parameter count couldn't be determined. This happens when the model doesn't include safetensors metadata or the name doesn't contain a size indicator (e.g., "7B").