{"id":46668745,"url":"https://github.com/zen-logic/file-hunter","last_synced_at":"2026-04-24T21:01:52.754Z","repository":{"id":340257739,"uuid":"1165226353","full_name":"zen-logic/file-hunter","owner":"zen-logic","description":"File Hunter — catalog, deduplicate, and consolidate your archive storage","archived":false,"fork":false,"pushed_at":"2026-04-18T15:57:53.000Z","size":2940,"stargazers_count":56,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T17:38:16.201Z","etag":null,"topics":["deduplication","duplicate-finder","file-catalog","file-manager","homelab","python","self-hosted","sqlite","storage","web-ui"],"latest_commit_sha":null,"homepage":"https://filehunter.zenlogic.uk","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zen-logic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T00:25:10.000Z","updated_at":"2026-04-18T15:57:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zen-logic/file-hunter","commit_stats":null,"previous_names":["zen-logic/file-hunter"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/zen-logic/file-hunter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-logic%2Ffile-hunter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-logic%2Ffile-hunter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-logic%2Ffile-hunter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-logic%2Ffile-hunter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zen-logic","download_url":"https://codeload.github.com/zen-logic/file-hunter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zen-logic%2Ffile-hunter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32240613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deduplication","duplicate-finder","file-catalog","file-manager","homelab","python","self-hosted","sqlite","storage","web-ui"],"created_at":"2026-03-08T21:23:26.915Z","updated_at":"2026-04-24T21:01:52.729Z","avatar_url":"https://github.com/zen-logic.png","language":"Python","readme":"# File Hunter\n\nA self-hosted, web-based file manager that remembers everything - even drives you disconnect.\n\nCatalog files across USB drives, backup disks, DVDs, network mounts, and local folders. Browse and search them when the media is offline. Find duplicates across terabytes of archives, consolidate them with a full audit trail, and manage it all from any browser - including on headless servers with no desktop at all.\n\nBuilt for real-world scale. The UI stays responsive during scans.\n\n![File Hunter](docs/img/app-screenshot.png)\n\n## Features\n\n| Feature | Description |\n|---|---|\n| **Offline catalog** | Scan any folder and the full file tree persists in a local SQLite database. Unplug the drive, unmount the share - keep browsing, searching, and planning as if it were still there. |\n| **Duplicate detection** | Three-gate hashing (size pre-filter, xxHash64 partial on first and last 64KB, xxHash64 fast hash over the full file) identifies byte-identical files across all locations with minimal I/O. Optional SHA-256 strong hash for absolute certainty. |\n| **Consolidation** | Keep one copy, stub the rest. Copy or move mode with a preview step before execution. Hash-verified copies, `.moved` stubs, and `.sources` metadata for full provenance. |\n| **Merge folders** | Merge entire locations or folder trees. Move or copy mode with preview step. Unique files transfer preserving structure, duplicates are handled at the source. Full CSV result log. |\n| **Storage treemap** | Interactive squarified treemap per location. Drill into folders, see individual large files, click to navigate. Theme-aware colour palette. |\n| **Full file management** | Move, copy, rename, delete files and folders. Create new folders. Upload via drag-and-drop (duplicates detected on arrival). Download files or entire folders as ZIP. Cross-location operations. |\n| **Batch operations** | Multi-select with checkboxes, Shift+click, Ctrl+click. Bulk delete, move, tag, or download as ZIP. |\n| **Powerful search** | Basic mode filters by filename (with match modes), file type, tags, description, size range, and date range. Advanced mode builds complex queries with multiple include/exclude conditions. Scope to a location or folder. Save searches for reuse. Results span all locations, online and offline. \"Show in Folder\" jumps to any result. |\n| **Inline previews** | Images, video, audio, PDFs, CSV tables, hex viewer, and text files render inline in the detail panel. Full-screen slideshow for images, playlist for video. |\n| **Scheduled scans** | Per-location schedules: pick days of the week and a time. Scans enqueue automatically. Offline locations are silently skipped. |\n| **Background scanning** | Scans run as server-side tasks. Close the browser, come back later. Incremental rescans skip unchanged files. |\n| **Multi-user auth** | Token-based authentication with PBKDF2 password hashing. First-run setup wizard. All users share full access. |\n| **Tags \u0026 descriptions** | Add metadata to any file. Searchable and persistent, even when drives are offline. |\n| **Themes** | Built-in themes from retro CRT terminals to clean corporate light modes. Create and edit your own in the theme editor. Every theme controls colours, fonts, glows, and treemap palette. |\n| **Keyboard navigation** | Full keyboard support across all panels. Arrow keys, Tab cycling, Enter to activate, shortcuts for search and filters. |\n| **Scan queue** | Queue up multiple location scans and they run one after another. Close the browser, come back - the queue kept going. |\n| **Stale file detection** | Rescans detect files that have disappeared and mark them stale. Your catalog stays honest about what's actually on disk. |\n| **Real-time updates** | WebSocket connection streams scan progress, upload status, and mutations to every connected browser. |\n\n## Who is it for\n\n| | |\n|---|---|\n| **Home lab operators** | Manage files on a headless server from any browser. No desktop environment needed. |\n| **Photographers \u0026 videographers** | Catalog shoots across dozens of external drives. Find that one file even when the drive is in a drawer. |\n| **Data hoarders** | See what you have, where it is, and how much of it is duplicated. Reclaim terabytes. |\n| **Sysadmins** | Audit storage usage across backup drives and archive media. Schedule scans, review from anywhere. |\n\n## Requirements\n\n- Python 3.10+\n\n## Installation\n\n```bash\ncurl -fsSL https://filehunter.zenlogic.uk/install | bash\n```\n\nDownloads the latest release, extracts it, and you're ready to go. Works on macOS, Linux, and WSL.\n\nOr download the latest release manually from the [releases page](https://github.com/zen-logic/file-hunter/releases/latest), extract it wherever you like, and run `./filehunter`.\n\n### Install via Docker\n\nThe following project tracks this repo's releases and updates the images accordingly.  Instructions are in the project repo for setup:\n\nhttps://github.com/ikidd/file-hunter-dockerized\n\n### Install from source\n\n```bash\ngit clone https://github.com/zen-logic/file-hunter.git\ngit clone https://github.com/zen-logic/file-hunter-agent.git\ncd file-hunter\n./filehunter\n```\n\n## Usage\n\n```bash\ncd filehunter-x.x.x\n./filehunter\n```\n\nOn first run, the launcher prompts for host and port, creates a virtual environment, and installs dependencies. Then open the URL shown in your browser.\n\n### Getting started\n\n1. On first launch, create your user account in the setup screen\n2. Click **+ Add Location** and browse to a folder (a USB drive, a subfolder on a disk, a network mount, etc.)\n3. Select the location and click **Scan** - file metadata and hashes are computed and stored in the catalog\n4. Browse the location tree, search files, review duplicates, and consolidate when ready\n\nEverything is self-contained in the install directory - database, config, and virtual environment. Move the folder and it still works. Delete it and it's completely gone.\n\n## Tech stack\n\n- **Backend** - Python, Starlette, uvicorn, aiosqlite\n- **Frontend** - vanilla HTML/CSS/JavaScript (no frameworks, no build step)\n- **Database** - SQLite in WAL mode (three databases: catalog, hashes, stats)\n- **Hashing** - xxHash64 (partial + fast), optional SHA-256 strong hash\n\nNo cloud services. No telemetry. No framework dependencies. Your files never leave your machine.\n\n## File Hunter Pro\n\nFile Hunter is free, open source, and always will be. File Hunter Pro is an optional extension that adds remote agent support - install a lightweight agent on any machine on your network and its drives appear as locations in your catalog. Browse, search, scan, preview, and stream content from remote machines as if the files were local. Duplicates are detected across all machines using the same three-gate hashing strategy. Pro also includes a read-only WebDAV server for mounting your catalog as a network drive.\n\nSee [filehunter.zenlogic.uk](https://filehunter.zenlogic.uk) for details.\n\n## AI Disclosure\n\nThis application was developed with the assistance of AI tools (Claude Opus, Kimi K2.5 and Qwen3-Coder-Next). These tools were used for code linting, syntax checking, testing, performance optimisation (particularly the SQLite WAL optimisation and DB locking operations), the theme engine and code refactoring. All generated code is manually reviewed and heavily tested in real use.\n\n## Links\n\n- [Website](https://filehunter.zenlogic.uk)\n\n## License\n\nCopyright 2026 [Zen Logic Ltd.](https://zenlogic.co.uk)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzen-logic%2Ffile-hunter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzen-logic%2Ffile-hunter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzen-logic%2Ffile-hunter/lists"}