Modelshift

Modelshift is a desktop app for converting Hugging Face model checkpoints into local inference formats. It supports GGUF for llama.cpp-based runtimes and MLX for Apple Silicon workflows, with a focused UI for selecting source models, output formats, quantization options, and conversion destinations.

The project demonstrates a real developer workflow: packaging an otherwise command-line-heavy model conversion process into a desktop app with dependency isolation, progress reporting, cancellation, and update checks.

What it does

• Converts local Hugging Face model directories or Hugging Face model URLs.
• Produces GGUF files with base formats (F32, F16, BF16) and common quantization types such as Q8_0, Q6_K, Q5_K_M, Q4_K_M, Q3_K_L, and IQ4_XS.
• Supports advanced GGUF quantization options, including additional K-quants, I-quants, ternary quants, and optional imatrix input when a local llama-quantize binary is available.
• Produces MLX model directories with bf16 / fp16 output and quantized 2-bit, 3-bit, 4-bit, 6-bit, 8-bit, mxfp4, and mxfp8 formats.
• Offers MLX advanced controls for quantization group size and mixed quantization recipes.
• Installs conversion tools into an isolated app-managed Python environment instead of mutating the user's system Python.
• Streams setup and conversion logs into the UI, shows conversion stages, and supports cancellation with cleanup of partial output.
• Checks installed tool versions against PyPI and prompts when GGUF or MLX tooling can be updated.

Why it exists

Model conversion is usually a fragile sequence of shell commands, Python package installs, platform-specific wheels, and format-specific flags. Modelshift wraps that workflow in a desktop interface while keeping the important technical controls visible.

The main engineering goal was to make the conversion pipeline reproducible:

• uv is downloaded into the app data directory and used to create the virtual environment.
• Python versions are selected based on available llama-cpp-python wheels for the current platform.
• GGUF conversion uses the current llama.cpp conversion script and installs the matching gguf Python package from the same repository.
• Hugging Face downloads can be kept beside the converted output or cleaned from cache after conversion.
• Conversion subprocesses are tracked so long-running jobs can be stopped safely.

Architecture

SvelteKit UI
  - conversion form, settings, progress state, terminal output
  - persisted preferences for theme, default format, advanced mode, downloads

Tauri command layer
  - Rust commands exposed to the UI with typed request/response payloads
  - subprocess orchestration, log streaming, cancellation, cleanup
  - app data paths, manifest storage, environment status, update checks

Python toolchain
  - uv-managed virtual environment
  - huggingface-hub for model snapshots
  - llama-cpp-python, gguf, and llama.cpp conversion scripts for GGUF
  - mlx-lm for MLX conversion on supported Apple Silicon systems

Tech stack

• Svelte 5 and SvelteKit
• Vite
• Tauri 2
• TypeScript
• Rust
• Bun
• uv
• llama-cpp-python, gguf, huggingface-hub, and mlx-lm

Platform notes

• GGUF tooling is currently wired for macOS and Linux because the app-managed uv bootstrap downloads Unix release archives.
• MLX conversion requires Apple Silicon and macOS 15 or newer.
• imatrix-assisted GGUF quantization requires a llama-quantize or llama_quantize executable on PATH; otherwise Modelshift falls back to its Python ctypes quantizer without imatrix support.

Getting started

Install dependencies:

bun install

Run the desktop app in development mode:

bun run tauri dev

Build release binaries:

bun run tauri build

Run the web UI only:

bun run dev

Run Svelte and TypeScript checks:

bun run check

Project structure

src/routes/+page.svelte       Main Svelte UI and conversion workflow state
src/routes/+layout.svelte     Global layout, theme variables, and font setup
src-tauri/src/lib.rs          Tauri commands, setup pipeline, conversion orchestration
src-tauri/tauri.conf.json     Desktop app configuration and bundling metadata
static/fonts/                 Bundled Ioskeley Mono web fonts

Implementation highlights

• Designed a single-screen desktop workflow for model source selection, format selection, quantization, output routing, and execution.
• Built a Rust-backed command layer that streams subprocess output to the frontend through Tauri events.
• Added app-managed dependency isolation with a manifest that records installed package versions and tool availability.
• Implemented two GGUF paths: direct conversion for supported output types and two-step F16 conversion followed by quantization for other formats.
• Added a cancellable conversion state machine that terminates child processes and removes partial files or empty output folders.
• Gated MLX setup behind platform detection so unsupported systems do not offer unusable install paths.

License

MIT