Usage Guide

The interface

File Hunter uses a three-panel layout similar to a desktop file manager:

Left panel — Navigation tree with locations and folders
Center panel — File list for the selected folder
Right panel — Detail view (file preview, stats, or dashboard)

Panel widths are resizable by dragging the dividers and persist across sessions. The toolbar at the top provides actions, and the status bar at the bottom shows connection and scan status. Click the “Locations” header at the top of the tree panel to return to the dashboard view at any time.

Adding locations

Click the + button in the toolbar or press N. Enter a name and browse to the folder path. The location appears in the tree immediately. A location can be any accessible directory — USB drives, network mounts, local folders.

You can add multiple locations from the same physical disk. Each is tracked independently.

Scanning

Right-click a location in the tree and choose “Scan”, or select a location and press S. The scan runs as a background task — you can close the browser and it keeps going.

Scanning progresses through three stages:

Walk — Discovers all files and folders
Partial hash — Computes xxHash64 on the first 64KB of each file
Full hash — Computes SHA-256 on files that share a partial hash

Incremental rescans are fast — only new or modified files (detected by size and modification time) are re-hashed. Files that have been deleted since the last scan are marked stale.

Scan queue

You can queue multiple location scans. They run one after another in FIFO order. All connected browsers see real-time progress via WebSocket.

Scheduled scans

Right-click a location and choose “Schedule”. Pick days of the week and a time. Scans enqueue automatically at the scheduled time. Offline locations are silently skipped.

Browsing files

Click a location or folder in the tree to see its files in the center panel. Click a file to see its details in the right panel, including preview (images, video, audio, text, PDF), metadata, hash values, tags, and description.

The tree loads lazily — expanding a node fetches only its immediate children. This keeps the UI responsive even with millions of files.

Offline browsing

When a location’s underlying media is disconnected, the location shows an “offline” badge. You can still browse the full folder tree, see all file metadata, search, and review duplicates. Only operations that require physical file access (preview, download, delete, move) are blocked.

Search

Press / or click the search icon. The search panel provides several filters that can be combined:

Name — match anywhere in the filename (default), or choose “Starts with”, “Ends with”, or “Exact” from the dropdown for precise matching
Type — filter by file type (image, video, audio, document, text, etc.)
Description / Tags — search within file metadata
Size range — minimum and maximum file size (supports KB, MB, GB suffixes)
Date range — filter by modification date
Include files / Include folders — search files, folders, or both. Uncheck “Include files” and check “Include folders” to find folders by name
Duplicates only — restrict results to files that have at least one duplicate elsewhere in the catalog

Results span all locations — online and offline — and are paged and sortable by name, type, size, date, or duplicate count.

Click a file in the results and use Show in Folder to navigate the tree to its containing folder with the file selected and scrolled into view, regardless of which page it falls on.

Duplicate detection

After scanning, files with matching SHA-256 hashes are identified as duplicates across all locations — local and remote. Duplicate counts are computed live so they are always accurate, even immediately after a scan completes.

Files with duplicates show a badge in the file list with the number of other copies. Click the badge to see all copies in a paged, sortable list. The detail panel shows up to ten duplicates with their locations and paths. When more than ten exist, an “and N more…” link opens the full list.

Consolidation

Consolidation deduplicates files on disk. Select duplicates and choose a consolidation mode:

Keep in place — The first copy stays, all others are replaced with .moved stubs
Copy to destination — The canonical copy is moved to a chosen destination folder, all copies (including the original) are stubbed

Every consolidation creates a .sources file alongside the kept copy, recording every original path. Stubs are tiny text files that record where the canonical copy now lives.

If any duplicates are on offline locations, their stubs are queued and written automatically the next time that location is scanned.

Merge folders

Merge an entire location or folder into another. Unique files are copied preserving directory structure. Duplicates at the source are stubbed. Filename collisions are handled with safe renaming. The operation runs as a background task with cancel support.

File management

Upload — Drag and drop or use the upload button. Files are hashed on arrival.
Move — Move files and folders within or across locations.
Rename — Rename files and folders inline.
Delete — Delete files and folders. Confirmation required.
Download — Download individual files or entire folders as ZIP.
New folder — Create folders in any location.

Batch operations

Multi-select files with checkboxes, Shift+click for range selection, or Ctrl/Cmd+click for individual selection. Batch actions include delete, move, tag, and download as ZIP.

Tags and descriptions

Select a file and use the detail panel to add free-text descriptions and tags. Both are searchable and persist in the catalog even when the drive is offline.

Storage treemap

Right-click a location and choose “Storage Map”. An interactive squarified treemap shows disk usage by folder size. Click to drill into subfolders, click a file to navigate to it in the main UI. Colours adapt to your chosen theme.

Themes

File Hunter ships with 17 themes: Cyber, C64, Neon, Light, Black, Red, Girly, Amber Monitor, Solaris, Solaris Light, Green Monitor, Blue, Aqua, Light Blue, Corporate, Default Light, and Default. Switch themes at runtime from Settings. Themes affect the entire UI including treemap colours.

Authentication

File Hunter uses token-based authentication. On first run, create an admin account. Additional users can be added from Settings. All users share full access — there are no permission levels. Passwords are hashed with PBKDF2-HMAC-SHA256.

Keyboard shortcuts

N — New location
S — Scan selected location
/ — Focus search
Esc — Clear search / close modal
↑ ↓ — Navigate tree and file list
Enter — Expand/collapse tree node, open file
Tab — Cycle panels
Delete — Delete selected file(s)