ai-file-sorter

AI File Sorter

AI File Sorter is a cross-platform desktop application that uses AI to organize files and suggest cleaner, more consistent names for images, documents, and supported audio/video files. It is designed to reduce clutter, improve consistency, and make files easier to find later, whether for review, archiving, or long-term storage.

The app can analyze picture files locally with built-in visual LLM backends and suggest meaningful, human-readable names. For example, a generic file like IMG_2048.jpg can be renamed to something descriptive such as clouds_over_lake.jpg. It can also analyze supported document files and propose clearer names based on their text content. AI File Sorter can also clean up messy audio and video filenames by using the metadata already stored inside supported media files. If tags such as year, artist, album, or title are available, the app can turn them into a clear suggestion like 2024_artist_album_title.mp3, which you can review, edit, or ignore before any change is applied.

AI File Sorter helps tidy up cluttered folders such as Downloads, external drives, or NAS storage by grouping files based on their names, file types, folder context, and past sorting results.

Instead of relying only on fixed rules, the app combines AI suggestions with optional whitelists, recent similar results, and your approved review decisions. This helps keep sorting more consistent over time while still letting you review and adjust everything before anything is changed.

Categories (and optional subcategories) are suggested for each file, and for supported file types, rename suggestions are provided as well. Once you confirm, the required folders are created automatically and files are sorted accordingly.

Privacy-first by design: AI File Sorter can run entirely on your device. When you use a local model, your files, filenames, images, and metadata stay on your computer, and no telemetry is sent. An internet connection is only needed if you choose to use a remote model.

---

How It Works

1. Point the app at a folder or drive
2. Files (and image content, when applicable) are analyzed using the selected local or remote model
3. Category and rename suggestions are generated
4. You review and adjust if needed before anything is changed

---

Safe First Run

If you are trying AI File Sorter for the first time, start with a small test folder instead of a full archive or drive. Copy 20-50 files from Downloads, screenshots, photos, or documents into a temporary folder, run the analysis, and inspect the review table before applying anything.

This keeps the first run low risk: your files stay on your computer when you use local models, the AI only suggests categories and filenames, and no move or rename happens until you approve it. If you do apply changes and then want to reverse them, use Edit -> Undo last run.

---

---

• AI File Sorter
  • Safe First Run
  • Technical reference
  • Changelog
  • Features
  • Categorization
    • Categorization modes
    • Category language selection
    • Category whitelists
  • Image analysis (Visual LLM)
    • Required visual LLM files
    • Main window options
  • Document analysis (Text LLM)
    • Supported document formats
    • Main window options (documents)
  • Audio/video metadata filename suggestions
    • Supported audio/video formats
  • System compatibility check
  • Requirements
  • Installation
    • Linux
    • macOS
    • Windows
  • Categorization cache and learned behavior
  • Uninstallation
  • Using your OpenAI API key
  • Using your Gemini API key
  • Using a custom OpenAI-compatible API
  • Testing
    • Optional headless live LLM tests
  • Diagnostics
  • Help and onboarding
  • How to Use
  • Sorting a Remote Directory (e.g., NAS)
  • Contributing
  • Credits
  • License
  • Donation

---

Technical reference

The main README stays focused on installation, features, and normal everyday use. For contributor-facing and integration-facing details that are too deep for the main entry page, use these technical references:

• Architecture
• Headless runtime contract
• Configuration and environment
• Categorization behavior
• Testing
• Updater contract

---

Changelog

[1.9.2] - 2026-08-14

• Fixed a Windows startup crash in Qt GUI theme refresh handling.

[1.9.1] - 2026-08-06

• Fixed bundled Windows local-LLM runtime builds so the packaged GGML libraries run on generic SSE4.2-capable x64 CPUs instead of requiring AVX2.
• Fixed embedded CA bundle staging for packaged and Microsoft Store builds by writing the certificate bundle under writable app data instead of the read-only install directory.

[1.9.0] - 2026-07-03

• Added smart branching whitelists so categories can have their own allowed subcategories, with an improved whitelist editor that keeps global and category-specific subcategory modes mutually exclusive.
• Added structured project-folder protection for recursive scans, covering Unity, Unreal, Godot, Blender, Git repositories, and common source-code project layouts.
• Added file preview support in the Categorization Review dialog and improved accessibility labels/progress announcements for screen readers.
• Added custom visual model support, configurable local model storage, and improved reuse of already-downloaded Gemma 3 4B model files.
• Improved category and filename consistency by localizing suggested filenames, preserving UTF-8 metadata, stripping inline subcategory artifacts, and keeping date suffixes out of canonical cache labels.
• Improved remote LLM handling with rate-limit/backoff parsing and optional request pacing.
• Improved local runtime and release packaging reliability across Windows, Linux, and macOS, including safer backend probing, CUDA/Vulkan fallback handling, RPM packaging, and verified macOS release helpers.

[1.8.0] - 2026-05-10

• Added backend status indicator to the status bar.
• The app now runs as a single instance - opening it again brings the existing window to the front instead of starting a second copy.
• Restored the app launcher for the non-Microsoft Store versions of the app and improved GPU selection, now preferring CUDA over Vulkan when both are available.
• Improved local GPU startup and local visual model handling for better reliability and compatibility.
• Added Gemma 3 4B IT and set it as the default visual model.
• Added Gemma 3 4B IT and Gemma 1.1 7B as built-in local categorization model choices, replacing LLaMa 3B.
• Improved image categorization quality and consistency by preserving image descriptions, using richer prompt context, adding special handling for screenshots and UI captures, and reducing drift between category labels.
• Improved image analysis stability, fallback behavior, and model-download validation.
• Added options to clear categorization and app caches, including a deeper reset of stored categorization state.
• Added local learning from your review decisions to improve future suggestions.
• Added localized Quick Start help, an FAQ link, and additional interface languages including Hindi, Swedish, Icelandic, Norwegian, Finnish, Danish, and Simplified Chinese.

See CHANGELOG.md for the full history.

---

Features

• AI-powered categorization: Sort files using either local AI models on your computer or remote models with your own API key.
• Offline-Friendly: Use a local LLM to categorize files entirely - no internet or API key required.
• Robust categorization: Built-in rules and category matching help keep results more consistent across runs.
• Configurable categorization controls: Use whitelists, taxonomy normalization, consistency modes, and review-time edits to steer categories and subcategories.
• Two categorization modes: Pick More Refined for more specific labels with less pressure to stay in broad default categories, or More Consistent for steadier top-level categories across similar files.
• Category whitelists: Define named whitelists of allowed categories/subcategories, including smart branching lists where each main category has its own allowed subcategories. Manage them under Settings → Manage category whitelists…, then toggle/select them in the main window when you want to constrain model output for a session.
• Category and rename languages: Categories are chosen in English behind the scenes and then shown in your selected category language. Suggested filenames for images, documents, and supported audio/video files are localized the same way. The available languages depend on the selected local model.
• Custom local LLMs: Register your own local GGUF models directly from the Select LLM dialog. Add a matching MMProj file to make a custom model available for image analysis as well.
• Image content analysis (Visual LLM): Analyze supported picture files with built-in visual backends such as the default Gemma 3 4B IT and LLaVA 1.6 Mistral 7B, with special handling for screenshots and UI captures so categories describe on-screen content more accurately (rename-only mode supported).
• Image date-to-category suffix (optional): Append image creation date metadata to image category names when available.
• Document content analysis (Text LLM): Analyze supported document files to summarize content and suggest filenames; uses the same selected LLM (local or remote).
• Audio/video metadata filename suggestions: Turn embedded media tags into clean, library-style filenames for supported audio and video files, with full review before anything is renamed.
• Sortable review: Sort the Categorization Review table by file name, category, or subcategory to triage faster.
• Qt6 Interface: Lightweight and responsive UI with refreshed menus and icons.
• Interface languages: English, Danish, Dutch, Finnish, French, German, Hindi, Icelandic, Italian, Korean, Norwegian, Simplified Chinese, Spanish, Swedish, and Turkish.
• Cross-Platform Compatibility: Works on Windows, macOS, and Linux.
• Local Database Caching: Speeds up repeated categorization, preserves approved labels and rename suggestions, and provides recent-category hints for consistency.
• Local learning from approved reviews: Approved category decisions can be stored locally and reused as hints for future runs without modifying the underlying model.
• Cache maintenance tools: Use Settings → Clear cache… to inspect and clear categorization cache, image location cache, and logs, or Settings → Reset learned behavior… to remove the separate learned-review database.
• Sorting Preview: See how files will be organized before confirming changes.
• Dry run / preview-only mode to inspect planned moves without touching files.
• Persistent Undo ("Undo last run") even after closing the sort dialog.
• Project-folder protection: Recursive scans skip recognized structured project roots such as Unity, Unreal, Godot, Blender project folders, Git repositories, and common source-code projects so files that depend on project-relative paths are not moved independently.
• Bring your own remote credentials: Store your OpenAI key, Gemini key, or custom OpenAI-compatible endpoint details locally for reuse in later runs.
• Update Notifications: Get notified about updates - with optional or required update flows.
• Storage plugin support: Install provider-specific compatibility modes from the Plugins menu when the app detects supported cloud-backed folders.
• In-app help: Open the localized Help → Quick Start Guide for a guided walkthrough or Help → FAQ for troubleshooting and common questions.

---

Categorization

Categorization modes

• More refined: The flexible, detail-oriented mode. It is less tied to the default category structure, so it can choose a more specific top-level category when that fits better. For example: Security / PCI DSS, Manuals / Camera Guides, or Wildlife / Lions. This works well for mixed, specialized, or long-tail folders.
• More consistent: The uniform mode. It uses recent similar results to favor stable broad folder categories, so related files are more likely to land under the same top-level folders. For example: Documents / PCI DSS, Documents / Camera Guides, or Images / Lions. This works well when you want a cleaner, more uniform folder layout.
• Switch between the two via the Categorization type radio buttons on the main window; your choice is saved for the next run.

Example without a whitelist:

More refined
- pci_dss_quick_reference.pdf -> Security / PCI DSS
- camera_setup_manual.pdf -> Manuals / Camera Guides
- lion_photo.jpg -> Wildlife / Lions

More consistent
- pci_dss_quick_reference.pdf -> Documents / PCI DSS
- camera_setup_manual.pdf -> Documents / Camera Guides
- lion_photo.jpg -> Images / Lions

Category language selection

• Category labels are chosen in English first behind the scenes, then shown in the category language you selected under Settings → Category language.
• Suggested filenames for image, document, and supported audio/video rename flows are also localized into the selected Settings → Category language target before review/apply.
• The list is model-dependent for built-in local models. Gemma 3 4B IT and Custom local models expose the full app-supported category-language list, Mistral 7B exposes a smaller supported subset, and Gemma 1.1 7B stays English-only.
• When the supported list is long, the menu is grouped into alphabetical submenus to keep it usable on smaller screens.

Category whitelists

• Enable Use a whitelist to apply the selected category list during categorization; disable it to let the model choose more freely.
• Manage lists (add, edit, remove) under Settings → Manage category whitelists…. Built-in Default and Documents lists are auto-created only when no lists exist, and multiple named lists can be kept for different projects.
• The whitelist editor has three sections. Main categories / top-level folders defines the destination category folders. Global subcategories defines subcategories that may be used under any main category. Category-specific subcategories defines smart branching rows where each main category has its own allowed subcategories.
• Global subcategories and Category-specific subcategories are alternatives. If you enter values in one section, the other section is disabled/ignored for that whitelist so the app does not mix two incompatible constraint styles.
• Smart branching is useful when the same broad top-level folders should contain different allowed subfolders. For example, Documents -> Invoices, Receipts, Taxes and Images -> Screenshots, Photos tells the app that Screenshots is valid under Images, but not under Documents.
• The built-in Documents whitelist uses smart branching: the only top-level category is Documents, while topics such as invoices, receipts, taxes, contracts, reports, and notes are stored as Documents subcategories.
• Narrow whitelists are still easiest for smaller local models, but large whitelists no longer need to dump every label into every prompt. When needed, the app reduces large and smart branching whitelists to relevant candidates plus valid category/subcategory pair guidance.
• Whitelists apply in either categorization mode; pair them with More consistent when you want the strongest adherence to a constrained vocabulary.

---

Image analysis (Visual LLM)

Image analysis can run locally to understand what a picture shows and suggest a better category or filename. It does not require an API key.

As of 1.9.0, Gemma 3 4B IT is the default visual backend. The app also gives screenshots, webpage captures, dashboards, forms, mockups, and other UI-like images extra prompt guidance so categories describe what is shown on screen instead of misclassifying the image as the software artifact itself.

The app currently exposes two built-in visual backends: the default Gemma 3 4B IT and LLaVA 1.6 Mistral 7B. In the current embedded runtime, all supported local visual backends require two GGUF files: the main text model and a matching mmproj projector file.

The Gemma 3 4B IT GGUF is also available as a built-in local text/categorization model. When used only for categorization or document analysis, it runs as a normal text model and does not need mmproj. If you already downloaded the Gemma 3 text GGUF for image analysis, the local text-model entry reuses that same file automatically. The extra mmproj file is only required for visual image analysis.

Custom local GGUF models can also be used for image analysis when their custom LLM entry includes a matching MMProj file. Those entries appear in the Visual model selector as custom visual backends and use the files you selected instead of the built-in download controls.

Required visual LLM files

The Select LLM dialog includes an "Image analysis models" section with backend-specific downloads:

• Visual text model (GGUF): The language model that produces the description and the filename suggestion.
• Matching mmproj file (GGUF): The multimodal projector that maps image embeddings into the model token space so the backend can accept images.

Both files are required for the selected backend. If either one is missing, image analysis is disabled and the app will prompt to open the Select LLM dialog to download them. The download URLs can be overridden with backend-specific environment variables such as LLAVA_MODEL_URL / LLAVA_MMPROJ_URL or GEMMA3_4B_MODEL_URL / GEMMA3_4B_MMPROJ_URL (see Environment variables).

The same dialog also includes Model storage, which changes where built-in local text and visual model downloads are stored. Leave it empty to use the platform default.

Main window options

Image analysis adds six related checkboxes to the main window:

• Analyze picture files by content: Runs the visual LLM on supported picture files and reports progress in the analysis dialog.
• Process picture files only (ignore any other files): Restricts the run to supported picture files and disables the categorization controls while active.
• Add image creation date (if available) to category name: Appends YYYY-MM-DD from image metadata to the category label when available. Disabled when rename-only is enabled.
• Add photo date and place to filename (if available): Adds metadata-based date/place prefixes to suggested image filenames when available.
• Offer to rename picture files: Shows a Suggested filename column in the Review dialog with the visual LLM proposal. You can edit it before confirming.
• Do not categorize picture files (only rename): Skips text categorization for images and keeps them in place while applying (optional) renames.

The separate top-level checkbox Add audio/video metadata to file name (if available) controls metadata-based rename suggestions for supported audio/video files. See Audio/video metadata filename suggestions.

---

Document analysis (Text LLM)

Document analysis uses the same selected LLM (local or remote) to extract text from supported document files, summarize content, and optionally suggest a better filename. No extra model downloads are required.

Supported document formats

• Plain text: .txt, .md, .rtf, .csv, .tsv, .json, .xml, .yml/.yaml, .ini/.cfg/.conf, .log, .html/.htm, .tex, .rst
• PDF: .pdf (embedded PDFium by default; CLI fallback via pdftotext is available only if you explicitly configure -DAI_FILE_SORTER_REQUIRE_EMBEDDED_PDF_BACKEND=OFF)
• Office/OpenOffice: .docx, .xlsx, .pptx, .odt, .ods, .odp (embedded libzip+pugixml in bundled builds; CLI fallback uses unzip if you build without vendored libs)
• Legacy binary formats like .doc, .xls, .ppt are not currently supported.

Source builds: embedded extractors are used by default. If the vendored PDFium artifacts are missing for your target platform, CMake now fails loudly instead of silently disabling PDF content extraction. You can opt back into the old CLI fallback with -DAI_FILE_SORTER_REQUIRE_EMBEDDED_PDF_BACKEND=OFF.

Main window options (documents)

• Analyze document files by content: Extracts document text and feeds it into the LLM for summary + rename suggestion.
• Process document files only (ignore any other files): Restricts the run to supported document files and disables the categorization controls while active.
• Offer to rename document files: Shows a Suggested filename column in the Review dialog with the LLM proposal. You can edit it before confirming.
• Do not categorize document files (only rename): Skips text categorization for documents and keeps them in place while applying (optional) renames.
• Add document creation date (if available) to category name: Appends YYYY-MM from metadata when available. Disabled when rename-only is enabled.

---

Audio/video metadata filename suggestions

Let AI File Sorter turn embedded media tags into clean, consistent filenames for your music and video library. When enabled, the app reads supported metadata fields and builds a polished suggested name in the format year_artist_album_title.ext. As with all rename suggestions, nothing is changed until you review and confirm it.

Supported audio/video formats

• Audio extensions: .aac, .aif, .aiff, .alac, .ape, .flac, .m4a, .mp3, .ogg, .oga, .opus, .wav, .wma
• Video extensions: .3gp, .avi, .flv, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .m2ts, .ts, .webm, .wmv
• Built-in tag readers currently cover MP3 (ID3v1/ID3v2), FLAC (Vorbis comments), OGG/OGA/Opus (Vorbis comments), and MP4-family containers such as .m4a, .mp4, .m4v, .mov, and .3gp (MP4/MOV metadata atoms).
• When compiled with package-managed MediaInfoLib, the same rename flow can also use metadata exposed by MediaInfo for additional supported containers when available.

---

System compatibility check

The System compatibility check runs a quick benchmark that estimates how well your system can handle:

• Categorization with the selected local LLMs
• Document analysis by content
• Image analysis (visual LLM)

You can launch it from the menu (File → System compatibility check…). It only runs if at least one local or visual LLM is downloaded, and it won’t auto-rerun if it's already been run.

What it does:

• Detects available CPU threads and GPU backends (e.g., Vulkan/CUDA)
• Times a small categorization and document-analysis workload per default model
• Times a single image-analysis pass if visual LLM files are present
• Reports speed tiers (optimal / acceptable / a bit long) and suggests a recommended local LLM

Tip: quit CPU/GPU‑intensive apps before running the check for more accurate results.

---

Requirements

• Operating System: Linux, macOS, or Windows. Linux/macOS source builds use the Makefile flow below; Windows source builds use the native Qt/MSVC + CMake flow in the Windows section.
• Compiler: A C++20-capable compiler (g++ or clang++ on Linux/macOS, MSVC 2022 on Windows).
• Qt 6: Core, Gui, Widgets modules and the Qt resource compiler (qt6-base-dev / qt6-tools on Linux, brew install qt on macOS, or a Qt 6 MSVC kit / qtbase via vcpkg on Windows).
• Libraries: curl, sqlite3, fmt, spdlog, libmediainfo (required for full source builds), and the prebuilt llama libraries shipped under app/lib/precompiled on Linux/Windows or app/lib/precompiled-* for macOS variant builds. On Windows, these non-Qt libraries are supplied through the app/vcpkg.json manifest.
• MediaInfo policy: MediaInfo must be installed through a package manager (apt/dnf/pacman/brew/vcpkg). The build rejects vendored MediaInfo submodules and checked-in binaries.
• Document analysis libraries (vendored): PDFium, libzip, and pugixml. PDFium is required by default so packaged/source builds keep PDF extraction embedded on Windows, macOS, and Linux; set -DAI_FILE_SORTER_REQUIRE_EMBEDDED_PDF_BACKEND=OFF only if you intentionally want the pdftotext fallback.
• Optional GPU backends: CUDA 12.x for NVIDIA cards or a Vulkan 1.2+ runtime. On Windows installer/standalone builds, aifilesorter.exe auto-detects the best available backend and now prefers CUDA over Vulkan when both are available, falling back to CPU/OpenBLAS automatically. On Linux, the same applies through run_aifilesorter.sh; when a dedicated CPU runtime bundle is absent, the launcher can also reuse the staged Vulkan payload for CPU/OpenBLAS fallback, so CUDA is never required to run the app.
• Git (optional): For cloning this repository. Archives can also be downloaded.
• Remote model credentials (optional): Required only when using ChatGPT, Gemini, or a custom OpenAI-compatible API endpoint.

---

Installation

File categorization with local LLMs is completely free of charge. If you prefer to use a remote workflow (ChatGPT, Gemini, or a custom OpenAI-compatible endpoint) you will need your own API credentials or endpoint configuration with a suitable quota or local server setup (see Using your OpenAI API key, Using your Gemini API key, or Using a custom OpenAI-compatible API).

Linux

Prebuilt Debian/Ubuntu package

1. Install runtime prerequisites (Qt6, networking, database, math libraries):
   • Ubuntu 24.04 / Debian 12:

     sudo apt update && sudo apt install -y \
       libqt6widgets6 libcurl4 libjsoncpp25 libfmt9 libopenblas0-pthread \
       libvulkan1 mesa-vulkan-drivers patchelf
     

   • Debian 13 (trixie):

     sudo apt update && sudo apt install -y \
       libqt6widgets6 libcurl4t64 libjsoncpp26 libfmt10 libopenblas0-pthread \
       libvulkan1 mesa-vulkan-drivers patchelf
     

   If you build the Vulkan backend from source, install glslc (Debian/Ubuntu package: glslc; on some distros: shaderc or shaderc-tools). On Debian 13, use libjsoncpp26, libfmt10, and libcurl4t64 (APT may auto-select libcurl4t64 if libcurl4 is not available). Ensure that the Qt platform plugins are installed (on Ubuntu 22.04 this is provided by qt6-wayland). GPU acceleration additionally requires either a working Vulkan 1.2+ stack (Mesa, AMD/Intel/NVIDIA drivers) or, for NVIDIA users, the matching CUDA runtime (nvidia-cuda-toolkit or vendor packages). The launcher automatically prefers CUDA when both are present and falls back to CPU if neither is available.
2. Install the package

   sudo apt install ./aifilesorter_*.deb
   

   Using apt install (rather than dpkg -i) ensures any missing dependencies listed above are installed automatically.

Build from source

1. Install dependencies

   • Debian / Ubuntu:

   sudo apt update && sudo apt install -y \
     build-essential cmake git qt6-base-dev qt6-base-dev-tools qt6-l10n-tools qt6-tools-dev-tools \
     libcurl4-openssl-dev libjsoncpp-dev libsqlite3-dev libssl-dev libfmt-dev libspdlog-dev libmediainfo-dev \
     zlib1g-dev patchelf
   

   • Fedora / RHEL:

   export PATH="/usr/lib64/qt6/libexec:$PATH"
   sudo dnf install -y gcc-c++ cmake git pkgconf-pkg-config qt6-qtbase-devel qt6-qttools-devel \
     libcurl-devel jsoncpp-devel sqlite-devel openssl-devel fmt-devel spdlog-devel libmediainfo-devel openblas-devel patchelf
   

   openblas-devel provides the OpenBLAS headers/libs used for the CPU baseline and for explicit blas=on llama builds on Fedora.

   If you plan to build the Vulkan llama runtime on Fedora, also install the Vulkan tools and shader compiler, plus a working Vulkan driver/runtime:

   sudo dnf install -y vulkan-tools glslc
   # AMD / Intel / Mesa-based Vulkan runtime
   sudo dnf install -y mesa-vulkan-drivers
   # NVIDIA proprietary driver users should install the vendor Vulkan runtime instead
   vulkaninfo >/dev/null
   

   If you plan to build the CUDA llama runtime on Linux, install an NVIDIA driver plus the full NVIDIA CUDA Toolkit (not just Python wheels/runtime packages), then verify both the driver and compiler in the same shell you will use for the build:

   export PATH="/usr/local/cuda/bin:$PATH"
   nvidia-smi
   nvcc --version
   

   Debian/Ubuntu users can use the distro-packaged toolkit (nvidia-cuda-toolkit) if it matches the driver/runtime they intend to build against. The Linux helper can also fall back to the toolkit's libcuda stubs when libcuda.so.1 is not on the default linker path, which is useful on CI or build-only hosts, but running the CUDA backend still requires a real NVIDIA driver installation. Fedora/RHEL users should use a supported CUDA Toolkit install from NVIDIA's Linux installation guide because the NVIDIA CUDA repository setup varies by release. On Fedora, enable the NVIDIA CUDA repository first or sudo dnf install cuda-toolkit will fail with "No match for argument":

   distro="fedora$(rpm -E %fedora)"
   sudo dnf install -y dnf-plugins-core
   sudo dnf config-manager addrepo \
     --from-repofile="https://developer.download.nvidia.com/compute/cuda/repos/${distro}/x86_64/cuda-${distro}.repo"
   sudo dnf clean expire-cache
   

   Once that repository is enabled for your Fedora release, the toolkit install itself is:

   sudo dnf install -y cuda-toolkit
   

   If you also want NVIDIA's packaged driver path from the same guide rather than a separately installed proprietary driver, the documented Fedora command is:

   sudo dnf module install -y nvidia-driver:latest-dkms
   

   The official Fedora instructions, including repo enablement and RPMFusion caveats, are: https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html

   On Linux, the helper also needs a CUDA-supported g++ host compiler. It auto-selects /usr/bin/g++-15, g++-14, g++-13, g++-12, g++-11, g++-10, then g++, and will stop with an error if none of those are suitable. Current CUDA 13.2 supports GCC 6.x through 15.x. If your installed CUDA release supports an older range than your distro default compiler, install a compatibility package such as Fedora gcc14-c++ or gcc13-c++ and rerun with NVCC_CCBIN=/usr/bin/g++-14 or NVCC_CCBIN=/usr/bin/g++-13 in the same shell.

   • Arch / Manjaro:

    sudo pacman -S --needed base-devel git cmake qt6-base qt6-tools curl jsoncpp sqlite openssl fmt spdlog mediainfo patchelf
   

   Optional GPU acceleration also requires either the distro Vulkan 1.2+ driver/runtime (Mesa, AMD, Intel, NVIDIA) or CUDA packages for NVIDIA cards. Install whichever stack you plan to use; the app will fall back to CPU automatically if none are detected. MediaInfo is enforced as package-managed only; vendored MediaInfoLib folders or repo-local binaries are rejected by the build.

2. Clone the repository

   git clone https://github.com/hyperfield/ai-file-sorter.git
   cd ai-file-sorter
   git submodule update --init --recursive
   

   Submodule tip: If you previously downloaded llama.cpp or Catch2 manually, remove or rename app/include/external/llama.cpp and external/Catch2 before running the git submodule command. Git needs those directories to be empty so it can populate them with the tracked submodules.

3. Build vendored libzip (generates zipconf.h and libzip.a)

   cmake -S external/libzip -B external/libzip/build \
    -DBUILD_SHARED_LIBS=OFF \
    -DBUILD_DOC=OFF \
    -DENABLE_BZIP2=OFF \
    -DENABLE_LZMA=OFF \
    -DENABLE_ZSTD=OFF \
    -DENABLE_OPENSSL=OFF \
    -DENABLE_GNUTLS=OFF \
    -DENABLE_MBEDTLS=OFF \
    -DENABLE_COMMONCRYPTO=OFF \
    -DENABLE_WINDOWS_CRYPTO=OFF
   
   cmake --build external/libzip/build
   

   On Ubuntu/Debian you will also need the Zlib development headers (zlib1g-dev) or the libzip configure step will fail.

   If you prefer system headers instead, install libzip-dev and ensure zipconf.h is on your include path.

4. Build the llama runtime variants (run once per backend you plan to ship/test)

   The Linux helper accepts either cuda=on / vulkan=on / blas=on or the GNU-style --cuda=on / --vulkan=on / --blas=on forms.

   # CPU / OpenBLAS
   ./app/scripts/build_llama_linux.sh cuda=off vulkan=off
   # CUDA (optional; runtime use requires NVIDIA driver + full CUDA Toolkit; verify
   # `nvidia-smi` and `nvcc --version` first. If `nvcc` is not on PATH after install,
   # run `export PATH=/usr/local/cuda/bin:$PATH` in this shell. The Linux helper can
   # use toolkit libcuda stubs on build-only hosts, and it also needs a CUDA-supported
   # g++ host compiler, preferring /usr/bin/g++-15 first.)
   ./app/scripts/build_llama_linux.sh cuda=on vulkan=off
   # Vulkan (optional; requires a working Vulkan 1.2+ stack and glslc; on Fedora install
   # vulkan-tools + glslc and ensure `vulkaninfo` succeeds. Mesa-based systems also need
   # mesa-vulkan-drivers.)
   ./app/scripts/build_llama_linux.sh cuda=off vulkan=on
   

   Each invocation stages the corresponding llama/ggml libraries under app/lib/precompiled/<variant> and the runtime DLL/SO copies under app/lib/ggml/w<variant>. On x64 Linux, the helper now keeps the shared ggml runtime generic and SSE4.2-safe instead of forcing AVX, F16C, FMA, AVX2, or BMI2 across every packaged backend. The script refuses to enable CUDA and Vulkan simultaneously, so run it separately for each backend. Shipping both directories lets the launcher pick CUDA when available, then Vulkan, and otherwise stay on CPU. If you only ship the Vulkan payload, the Linux launcher can reuse its bundled CPU/OpenBLAS libraries as the CPU fallback, matching the Windows launcher behavior.

5. Compile the application

   cd app
   make -j4
   

   The binary is produced at app/bin/aifilesorter. The Makefile requires pkg-config + package-managed libmediainfo; it intentionally rejects vendored MediaInfo copies.

6. Install system-wide (optional)

   sudo make install
   

7. Build a Debian package (optional)

   ./app/scripts/package_deb.sh
   

   The packaging script always bundles the CPU runtime and auto-includes any staged GPU variants already present under app/lib/precompiled (for example vulkan after ./app/scripts/build_llama_linux.sh cuda=off vulkan=on). Use ./app/scripts/package_deb.sh --cpu-only for a smaller CPU-only package, or --include-vulkan / --include-cuda if you want the script to fail when a specific staged variant is missing.

8. Build an RPM package (optional; Fedora / RHEL)

   ./app/scripts/create_rpm.sh
   

   The RPM packaging script follows the same runtime-selection model as the Debian packager: CPU is always bundled, staged CUDA/Vulkan runtime dirs are auto-included when present, and the installed run_aifilesorter.sh launcher chooses CUDA first, then Vulkan, then CPU at runtime. Use ./app/scripts/create_rpm.sh --cpu-only for a smaller CPU-only package, or --include-vulkan / --include-cuda if you want the script to fail when a specific staged variant is missing. The RPM payload is built under dist/aifilesorter_rpm/.

macOS

Apple Silicon Macs running macOS 15 or later are supported for macOS source builds and release bundles.

1. Install Xcode command-line tools (xcode-select --install).

2. Install Homebrew (if required).

3. Install dependencies

   brew install qt curl jsoncpp sqlite openssl fmt spdlog mediainfo cmake git pkgconfig libffi
   

   Add Qt to your environment if it is not already present:

   export PATH="$(brew --prefix)/opt/qt/bin:$PATH"
   export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$(brew --prefix)/share/pkgconfig:$PKG_CONFIG_PATH"
   

4. Clone the repository and submodules (same commands as Linux).

   The macOS build pins MACOSX_DEPLOYMENT_TARGET=15.0 so the Mach-O LC_BUILD_VERSION matches the supported Apple Silicon floor. Raise it if you intentionally want a newer floor.

5. Build vendored libzip (generates zipconf.h and libzip.a)

   cmake -S external/libzip -B external/libzip/build \
     -DBUILD_SHARED_LIBS=OFF \
     -DBUILD_DOC=OFF \
     -DENABLE_BZIP2=OFF \
     -DENABLE_LZMA=OFF \
     -DENABLE_ZSTD=OFF \
     -DENABLE_OPENSSL=OFF \
     -DENABLE_GNUTLS=OFF \
     -DENABLE_MBEDTLS=OFF \
     -DENABLE_COMMONCRYPTO=OFF \
     -DENABLE_WINDOWS_CRYPTO=OFF
   cmake --build external/libzip/build
   

6. Build the llama runtime

   ./app/scripts/build_llama_macos.sh
   

   Architecture-specific examples:

   ./app/scripts/build_llama_macos.sh --arm64   # Apple Silicon
   

   The macOS app and .app bundles use the runtime staged under app/lib/precompiled*; they do not need Homebrew ggml or llama.cpp libraries. If you have older ggml / llama.cpp copies installed in generic library locations, prefer unlinking or removing them instead of relying on them implicitly.

7. Compile the application

   cd app
   make -j8                 # use -jN to control parallelism
   sudo make install   # optional
   

   The default build places the binary at app/bin/aifilesorter.

   Variant targets:

   make -j8 MACOS_LLAMA_M1    # outputs app/bin/m1/aifilesorter
   make -j8 MACOS_LLAMA_M2    # outputs app/bin/m2/aifilesorter
   

   These targets rebuild the llama.cpp runtime before compiling the app. sudo make install places the macOS runtime libraries under /usr/local/lib/aifilesorter to avoid collisions with unrelated system or Homebrew ggml libraries. The commands above build the raw executable only; they do not currently create a distributable .app bundle or .dmg. This repository does not yet ship a documented or automated macOS bundle/DMG packaging target in README.md, so any .app / .dmg release packaging must be handled as a separate macOS-hosted release step. Each variant uses distinct build directories to avoid cross-arch collisions:

   • llama.cpp libs: app/lib/precompiled-m1, app/lib/precompiled-m2
   • object files: app/obj/arm64

Windows

Build now targets native MSVC + Qt6 without MSYS2. Two options are supported; the vcpkg route is simplest.

Option A - CMake + vcpkg (recommended)

1. Install prerequisites:

   • Visual Studio 2022 or newer with Desktop C++ workload

   • CMake 3.21+ (Visual Studio ships a recent version)

   • vcpkg: https://github.com/microsoft/vcpkg (clone and bootstrap)

   • package-managed libmediainfo via vcpkg manifest (no vendored MediaInfo submodule/binaries)

   • MSYS2 UCRT64 or MINGW64 + OpenBLAS: install MSYS2 from https://www.msys2.org, open either an MSYS2 UCRT64 or MSYS2 MINGW64 shell, and run pacman -S --needed mingw-w64-ucrt-x86_64-openblas or pacman -S --needed mingw-w64-x86_64-openblas. The build_llama_windows.ps1 script probes C:\msys64\ucrt64 and C:\msys64\mingw64 automatically, and also supports overriding the location with openblasroot=<path> or OPENBLAS_ROOT.

   • If you plan to build the CUDA runtime on Windows: install the current NVIDIA driver and the full NVIDIA CUDA Toolkit from https://developer.nvidia.com/cuda-downloads. After installation, open a fresh x64 Native Tools / Visual Studio Developer PowerShell and verify the toolkit/driver before running the helper:

     $env:CUDA_PATH
     nvcc --version
     nvidia-smi
     

     The Windows helper expects a full toolkit install with nvcc, headers, and libraries. Conda or pip CUDA runtime packages are not enough for building the bundled llama.cpp CUDA variant. NVIDIA's official Windows installation guide is here: https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html

2. Clone repo and submodules:

   git clone https://github.com/hyperfield/ai-file-sorter.git
   cd ai-file-sorter
   git submodule update --init --recursive
   

3. Build vendored libzip (generates zipconf.h and libzip.lib)

   Run from the same x64 Native Tools / Visual Studio Developer PowerShell you will use to build the app:

   cmake -S external\libzip -B external\libzip\build -A x64 `
     -DBUILD_SHARED_LIBS=OFF `
     -DBUILD_DOC=OFF `
     -DENABLE_BZIP2=OFF `
     -DENABLE_LZMA=OFF `
     -DENABLE_ZSTD=OFF `
     -DENABLE_OPENSSL=OFF `
     -DENABLE_GNUTLS=OFF `
     -DENABLE_MBEDTLS=OFF `
     -DENABLE_COMMONCRYPTO=OFF `
     -DENABLE_WINDOWS_CRYPTO=OFF
   cmake --build external\libzip\build --config Release
   

4. Determine your vcpkg root only if auto-discovery does not find it. The Windows helper scripts look in this order: VCPKG_ROOT / VPKG_ROOT, vcpkg / vpkg on PATH, then common writable locations such as <repo-drive>:\dev\vcpkg, <repo-drive>:\vcpkg, %SystemDrive%\dev\vcpkg, and %SystemDrive%\vcpkg.

   • If vcpkg is on your PATH, run this command to print the location:

     Split-Path -Parent (Get-Command vcpkg).Source
     

   • Otherwise use the directory where you cloned vcpkg, or pass it explicitly to the helper scripts.

   MediaInfo note: you do not manually add MediaInfoLib include/lib paths on Windows. The project already declares libmediainfo in app/vcpkg.json, and app\build_windows.ps1 configures CMake with the vcpkg toolchain + manifest so find_package(MediaInfoLib ...) resolves it automatically. If you want to preinstall or verify it explicitly, run vcpkg install libmediainfo:x64-windows.

5. Build the bundled llama.cpp runtime variants (run from the same x64 Native Tools / Visual Studio Developer PowerShell shell). Invoke the script once per backend you need. The script accepts cuda=on|off, vulkan=on|off, blas=on|off, vcpkgroot=<path>, openblasroot=<path>, and cudaarch=<value>. vcpkgroot=<path> is optional and only needed when auto-discovery misses your install. blas defaults to AUTO: it is enabled automatically for CPU-only builds and disabled automatically for CUDA/Vulkan builds unless you force it on. For Windows builds, the helper now keeps the shared ggml runtime generic and SSE4.2-safe instead of forcing AVX2 across every DLL. For CUDA builds, the helper prefers a valid CUDA_PATH and otherwise auto-selects the newest installed toolkit it can validate under C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA. Make sure nvcc --version and nvidia-smi succeed in this same shell before running cuda=on. Make sure the MSYS2 OpenBLAS install from step 1 is present before running the CPU-only variant (or pass openblasroot=<path> explicitly):

   # CPU / OpenBLAS only
   app\scripts\build_llama_windows.ps1 cuda=off vulkan=off
   # CUDA (requires matching NVIDIA toolkit/driver)
   app\scripts\build_llama_windows.ps1 cuda=on vulkan=off
   # CUDA + OpenBLAS (optional override if you want that combination explicitly)
   app\scripts\build_llama_windows.ps1 cuda=on vulkan=off blas=on
   # Vulkan (requires LunarG Vulkan SDK or vendor Vulkan 1.2+ runtime)
   app\scripts\build_llama_windows.ps1 cuda=off vulkan=on
   

Each run emits the appropriate llama.dll / ggml*.dll pair under app\lib\precompiled\<cpu|cuda|vulkan|vulkan-blas> and copies the runtime DLLs into the Windows runtime directories used by the app (app\lib\ggml\wocuda, app\lib\ggml\wcuda, or app\lib\ggml\wvulkan). The helper also stages OpenSSL runtime DLLs and, for OpenBLAS-backed builds, the MinGW companion DLLs needed beside libopenblas.dll. Windows ggml runtimes built by this helper target SSE4.2 and leave AVX, AVX2, BMI2, and newer x86 extensions disabled so the packaged DLLs remain usable on older x64 CPUs. If the vendored llama.cpp UI assets are missing, the helper downloads a prebuilt UI bundle before configuring and removes the temporary extracted assets after the build completes. For Vulkan builds, install the latest LunarG Vulkan SDK (or the vendor's runtime), ensure vulkaninfo succeeds in the same shell, and then run the script. The Windows launcher aifilesorter.exe auto-selects the best backend at launch: CUDA is preferred, Vulkan is used when CUDA is unavailable, and CPU remains the fallback.

6. Build the Qt6 application using the helper script (still in the VS shell). The helper stages runtime DLLs via windeployqt and shares one dependency install tree across builds:

   # One-time per shell if script execution is blocked:
   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
   
   app\build_windows.ps1 -Configuration Release
   

   • Pass -VcpkgRoot <path> only if auto-discovery misses your vcpkg install. The path must contain scripts\buildsystems\vcpkg.cmake.
   • Pass -Generator <name> only if you need to override the auto-selected CMake generator. By default the helper picks the newest installed Visual Studio generator it can validate and can fall back to the Visual Studio-bundled cmake.exe when needed.
   • The main bundled output is staged under app\build-windows\Release.
   • aifilesorter.exe is the Windows entry point for the bundled build and launches aifilesorter-bin.exe.
   • -VcpkgRoot is optional if VCPKG_ROOT/VPKG_ROOT is set or vcpkg/vpkg is on PATH.
   • Pass -SkipDeploy if you only want the binaries without bundling runtime DLLs.
   • Pass -Parallel <N> to override the default "all cores" parallel build behaviour (for example, -Parallel 8). By default the script invokes cmake --build ... --parallel <core-count> and ctest -j <core-count> to keep both MSBuild and Ninja fully utilized.

Option B - CMake + Qt online installer

1. Install prerequisites:

   • Visual Studio 2022 or newer with Desktop C++ workload
   • Qt 6.x MSVC kit via Qt Online Installer (e.g., Qt 6.6+ with MSVC 2019/2022)
   • CMake 3.21+
   • vcpkg (for non-Qt libs): curl, jsoncpp, sqlite3, openssl, fmt, spdlog, gettext, libmediainfo

2. Build vendored libzip (generates zipconf.h and libzip.lib)

   Run from the same x64 Native Tools / Visual Studio Developer PowerShell you will use to build the app:

   cmake -S external\libzip -B external\libzip\build -A x64 `
     -DBUILD_SHARED_LIBS=OFF `
     -DBUILD_DOC=OFF `
     -DENABLE_BZIP2=OFF `
     -DENABLE_LZMA=OFF `
     -DENABLE_ZSTD=OFF `
     -DENABLE_OPENSSL=OFF `
     -DENABLE_GNUTLS=OFF `
     -DENABLE_MBEDTLS=OFF `
     -DENABLE_COMMONCRYPTO=OFF `
     -DENABLE_WINDOWS_CRYPTO=OFF
   cmake --build external\libzip\build --config Release
   

3. Build the bundled llama.cpp runtime (same VS shell). The helper resolves cURL and OpenSSL from vcpkg, and OpenBLAS from an MSYS2 UCRT64 or MINGW64 install:

   pwsh .\app\scripts\build_llama_windows.ps1 [cuda=on|off] [vulkan=on|off] [blas=on|off] [vcpkgroot=<path>] [openblasroot=C:\msys64\ucrt64] [cudaarch=<value>]
   

   blas defaults to AUTO, which means ON for CPU-only builds and OFF for CUDA/Vulkan builds unless you force it. This is required before configuring the GUI because the build links against the produced llama import libraries and runtime DLLs.

4. Configure CMake from the repo root so CMake sees both the Qt install and the app's vcpkg manifest (adapt CMAKE_PREFIX_PATH to your Qt install):

   $env:VCPKG_ROOT = "D:\path\to\vcpkg"
   $qt = "C:\Qt\6.6.3\msvc2019_64"  # example
   cmake -S app -B build -G "Ninja" `
     -DCMAKE_PREFIX_PATH=$qt `
    -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT\scripts\buildsystems\vcpkg.cmake `
    -DVCPKG_MANIFEST_DIR=app `
    -DAI_FILE_SORTER_REQUIRE_MEDIAINFOLIB=ON `
    -DVCPKG_TARGET_TRIPLET=x64-windows
   cmake --build build --config Release
   

   This configure step enables vcpkg manifest mode, so libmediainfo is installed/resolved from app\vcpkg.json automatically. No manual linker or include-path edits are needed for MediaInfo on Windows.

Notes

• To rebuild from scratch, run .\app\build_windows.ps1 -Clean. The script removes the Windows build directories used by the helper and the shared app\build-windows-vcpkg_installed dependency tree before configuring.
• Runtime DLLs are copied automatically via windeployqt after each successful build; skip this step with -SkipDeploy if you manage deployment yourself.
• If Visual Studio sets VCPKG_ROOT to its bundled copy under Program Files, point VCPKG_ROOT to a writable clone or pass vcpkgroot=<path> when running build_llama_windows.ps1. The script skips the bundled Visual Studio copy during auto-discovery because it is usually read-only.
• If a Windows build directory was previously configured with a different generator, platform, or Visual Studio instance, app\build_windows.ps1 now detects the stale cache and recreates that build directory automatically before configuring.
• If you plan to ship CUDA or Vulkan acceleration, run the build_llama_* helper for each backend you intend to include before configuring CMake so the libraries exist. The runtime can carry both and auto-select at launch, so CUDA remains optional.
• -BuildTests and -RunTests are intended for the primary bundled Windows build configuration.

Running tests

Catch2-based unit tests are optional. Enable them via CMake:

cmake -S app -B build-tests -DAI_FILE_SORTER_BUILD_TESTS=ON -DAI_FILE_SORTER_REQUIRE_MEDIAINFOLIB=ON
cmake --build build-tests --parallel $(nproc)
ctest --test-dir build-tests --output-on-failure -j $(nproc)

On macOS, replace $(nproc) with $(sysctl -n hw.ncpu).

On Windows (PowerShell), use:

$env:VCPKG_ROOT = "D:\path\to\vcpkg"
$qt = "C:\Qt\6.6.3\msvc2019_64"  # example
$toolchain = Join-Path $env:VCPKG_ROOT "scripts\buildsystems\vcpkg.cmake"
cmake -S app -B build-tests -G "Ninja" `
  -DCMAKE_PREFIX_PATH=$qt `
  "-DCMAKE_TOOLCHAIN_FILE=$toolchain" `
  -DVCPKG_MANIFEST_DIR=app `
  -DVCPKG_TARGET_TRIPLET=x64-windows `
  -DAI_FILE_SORTER_BUILD_TESTS=ON `
  -DAI_FILE_SORTER_REQUIRE_MEDIAINFOLIB=ON
cmake --build build-tests --config Release `
  --target ai_file_sorter_tests ai_file_sorter_updater_notify_only_tests ai_file_sorter_updater_disabled_tests `
  --parallel $env:NUMBER_OF_PROCESSORS
ctest --test-dir build-tests -C Release --output-on-failure -j $env:NUMBER_OF_PROCESSORS

Notes

• The easiest Windows path is still app\build_windows.ps1 -Configuration Release -BuildTests -RunTests, which wires up the same vcpkg manifest/toolchain expectations for the main bundled build.
• To register the optional live LLM CTest suite from the Windows helper, use .\app\build_windows.ps1 -Configuration Release -Variants Standard -BuildTests -EnableLiveLlmTests in PowerShell or app\build_windows.cmd -Configuration Release -Variants Standard -BuildTests -EnableLiveLlmTests in cmd.exe. Add -RunTests only if you want the full registered CTest set to run immediately.
• If you use a Visual Studio multi-config build tree such as build-tests-vs, building only --target aifilesorter produces Release\aifilesorter-bin.exe. The launcher Release\aifilesorter.exe belongs to the StartAiFileSorter target, so build StartAiFileSorter explicitly or omit --target if you want the launcher too.
• If CMake reports a missing hardcoded Visual Studio instance for build-tests, the path is coming from the existing build tree's CMakeCache.txt, not from this repo. Use cmake --fresh, delete/recreate that build directory, or choose a new build directory before changing generators or Visual Studio installations.
• List individual Catch2 cases: ./build-tests/ai_file_sorter_tests --list-tests
• Print each case name (including successes): ./build-tests/ai_file_sorter_tests --verbosity high --success

On Windows you can pass -BuildTests (and -RunTests to execute ctest) to app\build_windows.ps1:

.\app\build_windows.ps1 -Configuration Release -Variants Standard -BuildTests -RunTests

From cmd.exe, use app\build_windows.cmd -Configuration Release -Variants Standard -BuildTests -RunTests instead.

The current suite (under tests/unit) focuses on core utilities; expand it as new functionality gains coverage.

Optional headless live LLM tests

The normal Catch2/CTest suite does not launch a real local model against real files. For that purpose, use the opt-in live runner at tests/live_llm/headless_live_llm_tests.py. It invokes the production headless command, seeds an isolated app config with your local GGUF model, creates per-run fixture folders, downloads/caches a few small public PDF/image fixtures, and validates status JSON plus filesystem effects.

These tests are intentionally not enabled by default because they are slow, model-dependent, and partly nondeterministic. Missing live-test prerequisites return exit code 77, which CTest treats as skipped.

Run sequence with CTest:

# 1. Windows recommended path from PowerShell: configure/build with stale-cache detection.
.\app\build_windows.ps1 -Configuration Release -Variants Standard -BuildTests -EnableLiveLlmTests

# 2. Point the runner at a local text GGUF model.
#    You can skip this if the normal AI File Sorter settings already select
#    an available local/custom GGUF model.
$env:AI_FILE_SORTER_LIVE_LLM_MODEL = "C:\models\text-model.gguf"

# 3. Optional: enable image-content rename cases with a visual model pair.
$env:AI_FILE_SORTER_LIVE_VISUAL_MODEL = "C:\models\vision-model.gguf"
$env:AI_FILE_SORTER_LIVE_VISUAL_MMPROJ = "C:\models\mmproj-model.gguf"

# 4. Optional: force a backend. Values: auto, cpu, cuda, vulkan.
$env:AI_FILE_SORTER_LIVE_BACKEND = "cuda"

# 5. Run only the live LLM suite from the helper's Standard build directory.
ctest --test-dir app\build-windows -C Release -L live-llm --output-on-failure

# Use -V instead when you want live per-case progress in the terminal.
ctest --test-dir app\build-windows -C Release -L live-llm -V

From cmd.exe, use app\build_windows.cmd -Configuration Release -Variants Standard -BuildTests -EnableLiveLlmTests for step 1.

On bundled Windows builds, the live suite runs through aifilesorter.exe, not aifilesorter-bin.exe, so backend DLL selection matches the normal non-Store launcher. If an older CTest file still passes aifilesorter-bin.exe, the Python runner automatically switches to the sibling launcher when it exists. Use AI_FILE_SORTER_LIVE_BACKEND=cuda to validate CUDA specifically, leave it unset for the launcher's normal CUDA -> Vulkan -> CPU selection, or use cpu for deterministic CPU/OpenBLAS runs.

CTest suppresses passing-test output unless -V is used. The runner also writes a live progress log and a pointer file, so a second PowerShell can tail progress while a non-verbose CTest run is active:

$work = Get-Content "$env:TEMP\aifs-live-llm-latest.txt"
Get-Content (Join-Path $work "progress.log") -Wait

Verbose progress includes the backend environment received by the headless text LLM client, for example Local text LLM backend request: AI_FILE_SORTER_GPU_BACKEND=cuda. If that line says cpu, clear any stale AI_FILE_SORTER_LIVE_BACKEND=cpu setting and rebuild after stopping old test processes that may still hold aifilesorter-bin.exe.

The live runner colorizes terminal output by default: failures are red, warnings/skips are yellow, progress/info is blue, and passes are green. Set AI_FILE_SORTER_LIVE_COLOR=never or pass --color never for plain output. Long-running cases refresh an inline elapsed=NNNs counter on the active RUN line instead of printing heartbeat lines; set `AI_FILE_SORTER_LIVE_INLINE_PROGRESS