\n<\/p>\n
FilePilot AI is a local-first desktop file manager that helps you inspect, index, search, deduplicate, summarize, and organize your local storage \u2014 all through a preview-first workflow.
\nYour files stay on your machine unless you explicitly choose a cloud AI provider for summarization.<\/p>\n
Recursive directory scanning with depth controls
\nFile type, category, MIME, and hash detection
\nRich metadata: size, date, dimensions, duration
\nRespects hidden-file and .gitignore filters<\/p>\n
Whoosh-powered full-text index
\nKeyword, fuzzy, and boolean queries
\nFilter by type, date range, and file size
\nExport results to CSV<\/p>\n
Built-in extractors for PDF, Markdown, code, images, DOCX, XLSX, and PPTX
\nLocal (Ollama, llama.cpp) or cloud AI providers (OpenAI, Anthropic)
\nBatch summary workflow for multi-file processing
\nPluggable provider interface with unified API<\/p>\n
Size-bucket grouping for first pass
\nFast partial-hash pre-filter
\nFull SHA-256 content verification
\nSafe deletion via system Recycle Bin (send2trash)<\/p>\n
Organize by file type, date, extension, or size range
\nCustom rename templates with variables
\nPreview changes before applying
\nUndo-log support for rollback<\/p>\n
Native PySide6 desktop interface
\nLight and dark theme support
\nSystem tray integration with background file watcher
\nToast notifications and 18 UI languages<\/p>\n
Browse
\nSearch<\/p>\n
Organize
\nDuplicates<\/p>\n
AI Summary
\nIndex<\/p>\n
Python 3.10 or newer
\nWindows, macOS, or Linux
\nOptional: Ollama, llama.cpp, or LM Studio for local AI
\nOptional: OpenAI, Anthropic, or any OpenAI-compatible endpoint for cloud AI<\/p>\n
git clone https:\/\/github.com\/cuiheng511\/filepilot-ai.git
\ncd filepilot-ai<\/p>\n
python -m venv .venv<\/p>\n
# Windows
\n.venv\\Scripts\\activate<\/p>\n
# macOS \/ Linux
\nsource .venv\/bin\/activate<\/p>\n
pip install -r requirements.txt
\npython -m filepilot.main<\/p>\n
pip install -e “.(test,dev)”
\npytest
\nruff check .
\nruff format –check .
\nmypy<\/p>\n
# Scan a folder
\npython -m filepilot.cli scan ~\/Documents<\/p>\n
# Find duplicate files
\npython -m filepilot.cli duplicates ~\/Downloads<\/p>\n
# Export an inventory report
\npython -m filepilot.cli export ~\/Projects –format csv -o report.csv<\/p>\n
# Analyze disk usage
\npython -m filepilot.cli disk-usage ~\/<\/p>\n
# Search indexed files
\npython -m filepilot.cli search ~\/Documents “machine learning”<\/p>\n
# Preview an organization plan before moving anything
\npython -m filepilot.cli organize ~\/Downloads ~\/Sorted –dry-run –rules category date<\/p>\n
FilePilot AI supports both local and cloud AI providers through a unified interface. See docs\/AI-PROVIDERS.md for setup guides, configuration reference, and privacy details for each provider.<\/p>\n
Provider
\nMode
\nDefault URL<\/p>\n
Ollama
\nLocal
\nhttp:\/\/localhost:11434<\/p>\n
llama.cpp \/ vLLM
\nLocal
\nhttp:\/\/localhost:8080<\/p>\n
LM Studio
\nLocal
\nhttp:\/\/localhost:1234<\/p>\n
OpenAI
\nCloud
\nhttps:\/\/api.openai.com\/v1<\/p>\n
Anthropic
\nCloud
\nhttps:\/\/api.anthropic.com<\/p>\n
Custom endpoint
\nCloud \/ Local
\nUser-defined<\/p>\n
Cloud providers only receive the content you choose to summarize. Local scanning, indexing, organization, and duplicate detection do not require AI.<\/p>\n
filepilot-ai\/
\n|– filepilot\/
\n| |– ai\/ # AI providers and summarization
\n| |– core\/ # Scanner, indexer, organizer, duplicates, watcher
\n| |– extractors\/ # PDF, Markdown, code, image, DOCX, XLSX, PPTX
\n| |– resources\/ # Application icons
\n| |– styles\/ # Theme manager and QSS themes
\n| |– ui\/ # PySide6 panels, tray, settings, notifications
\n| |– app.py # Application bootstrap
\n| |– cli.py # Command-line interface
\n| |– i18n.py # Translation catalog
\n| `– main.py # GUI entry point
\n|– tests\/ # Unit and UI tests
\n|– scripts\/ # Build scripts (Windows\/macOS\/Linux installers)
\n|– .github\/workflows\/ # CI pipeline (3-platform builds)
\n|– FilePilot.spec # PyInstaller build config (Windows)
\n|– pyproject.toml # Package metadata and tooling
\n`– requirements.txt # Runtime dependencies<\/p>\n
flowchart LR
\n UI(“PySide6 UI”) –> Core(“Core services”)
\n CLI(“CLI”) –> Core
\n Core –> Scanner(“File scanner”)
\n Core –> Indexer(“Whoosh indexer”)
\n Core –> Duplicates(“Duplicate finder”)
\n Core –> Organizer(“Organizer”)
\n Core –> Watcher(“Directory watcher”)
\n Scanner –> Extractors(“Content extractors”)
\n Extractors –> Summarizer(“AI summarizer”)
\n Summarizer –> Providers(“Local and cloud AI providers”)
\n Duplicates –> send2trash(“send2trash”)
\n send2trash –> RecycleBin(“System Recycle Bin (safe deletion)”)<\/p>\n
Loading<\/p>\n
Area
\nDesign<\/p>\n
Local-first workflow
\nFile scanning, indexing, duplicate detection, and organization run locally<\/p>\n
Optional AI
\nSummarization can use local models or explicit cloud providers<\/p>\n
Key storage
\nAPI keys use OS keyring when available, with encrypted fallback storage<\/p>\n
Deletion safety
\nDuplicate removal uses the system recycle bin through send2trash<\/p>\n
Telemetry
\nNo analytics, tracking, or background phone-home behavior<\/p>\n
The CI pipeline runs:<\/p>\n
pytest \u2014 unit and UI tests
\nruff check . \u2014 linting
\nruff format –check . \u2014 formatting
\nmypy \u2014 static type checking
\npip check \u2014 dependency consistency<\/p>\n
Run the same checks locally before pushing.<\/p>\n
FilePilot AI is packaged with PyInstaller on all three platforms. See docs\/BUILD.md for complete build instructions, prerequisites, and troubleshooting.
\n# Quick build (auto-detect platform)
\n.\/scripts\/build.sh<\/p>\n
The GitHub Actions workflow (.github\/workflows\/ci.yml) automatically builds all three platforms:<\/p>\n
Job
\nPlatform
\nRunner
\nArtifact
\nRetention<\/p>\n
build-windows
\nWindows
\nwindows-latest
\n.exe installer
\n30 days<\/p>\n
build-linux
\nLinux
\nubuntu-latest
\n.AppImage
\n30 days<\/p>\n
build-macos
\nmacOS
\nmacos-latest
\n.dmg
\n30 days<\/p>\n
Each CI run produces SHA256 checksums alongside the artifacts.<\/p>\n
FilePilot AI includes a threaded auto-update checker that queries GitHub Releases for new versions. See docs\/AUTO-UPDATE.md for the full API reference and configuration details.<\/p>\n
Background check every 24 hours (1 hour on failure)
\nResults cached to ~\/.filepilot\/update_check_cache.json
\nFully thread-safe \u2014 runs in a daemon thread<\/p>\n
See docs\/README.md for the full documentation index.<\/p>\n
Application screenshots and demo GIFs
\nSummary cache with invalidation
\nLarge-folder indexing performance tuning
\nMore organization templates
\nMore end-to-end packaging tests<\/p>\n
Contributions are welcome. See CONTRIBUTING.md for environment setup, style rules, and pull request guidance.<\/p>\n