FilePilot AI is a local-first desktop file manager that helps you inspect, index, search, deduplicate, summarize, and organize your local storage — all through a preview-first workflow.
Your files stay on your machine unless you explicitly choose a cloud AI provider for summarization.
Recursive directory scanning with depth controls
File type, category, MIME, and hash detection
Rich metadata: size, date, dimensions, duration
Respects hidden-file and .gitignore filters
Whoosh-powered full-text index
Keyword, fuzzy, and boolean queries
Filter by type, date range, and file size
Export results to CSV
Built-in extractors for PDF, Markdown, code, images, DOCX, XLSX, and PPTX
Local (Ollama, llama.cpp) or cloud AI providers (OpenAI, Anthropic)
Batch summary workflow for multi-file processing
Pluggable provider interface with unified API
Size-bucket grouping for first pass
Fast partial-hash pre-filter
Full SHA-256 content verification
Safe deletion via system Recycle Bin (send2trash)
Organize by file type, date, extension, or size range
Custom rename templates with variables
Preview changes before applying
Undo-log support for rollback
Native PySide6 desktop interface
Light and dark theme support
System tray integration with background file watcher
Toast notifications and 18 UI languages
Browse
Search
Organize
Duplicates
AI Summary
Index
Python 3.10 or newer
Windows, macOS, or Linux
Optional: Ollama, llama.cpp, or LM Studio for local AI
Optional: OpenAI, Anthropic, or any OpenAI-compatible endpoint for cloud AI
git clone https://github.com/cuiheng511/filepilot-ai.git
cd filepilot-ai
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -r requirements.txt
python -m filepilot.main
pip install -e “.(test,dev)”
pytest
ruff check .
ruff format –check .
mypy
# Scan a folder
python -m filepilot.cli scan ~/Documents
# Find duplicate files
python -m filepilot.cli duplicates ~/Downloads
# Export an inventory report
python -m filepilot.cli export ~/Projects –format csv -o report.csv
# Analyze disk usage
python -m filepilot.cli disk-usage ~/
# Search indexed files
python -m filepilot.cli search ~/Documents “machine learning”
# Preview an organization plan before moving anything
python -m filepilot.cli organize ~/Downloads ~/Sorted –dry-run –rules category date
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.
Provider
Mode
Default URL
Ollama
Local
http://localhost:11434
llama.cpp / vLLM
Local
http://localhost:8080
LM Studio
Local
http://localhost:1234
OpenAI
Cloud
https://api.openai.com/v1
Anthropic
Cloud
https://api.anthropic.com
Custom endpoint
Cloud / Local
User-defined
Cloud providers only receive the content you choose to summarize. Local scanning, indexing, organization, and duplicate detection do not require AI.
filepilot-ai/
|– filepilot/
| |– ai/ # AI providers and summarization
| |– core/ # Scanner, indexer, organizer, duplicates, watcher
| |– extractors/ # PDF, Markdown, code, image, DOCX, XLSX, PPTX
| |– resources/ # Application icons
| |– styles/ # Theme manager and QSS themes
| |– ui/ # PySide6 panels, tray, settings, notifications
| |– app.py # Application bootstrap
| |– cli.py # Command-line interface
| |– i18n.py # Translation catalog
| `– main.py # GUI entry point
|– tests/ # Unit and UI tests
|– scripts/ # Build scripts (Windows/macOS/Linux installers)
|– .github/workflows/ # CI pipeline (3-platform builds)
|– FilePilot.spec # PyInstaller build config (Windows)
|– pyproject.toml # Package metadata and tooling
`– requirements.txt # Runtime dependencies
flowchart LR
UI(“PySide6 UI”) –> Core(“Core services”)
CLI(“CLI”) –> Core
Core –> Scanner(“File scanner”)
Core –> Indexer(“Whoosh indexer”)
Core –> Duplicates(“Duplicate finder”)
Core –> Organizer(“Organizer”)
Core –> Watcher(“Directory watcher”)
Scanner –> Extractors(“Content extractors”)
Extractors –> Summarizer(“AI summarizer”)
Summarizer –> Providers(“Local and cloud AI providers”)
Duplicates –> send2trash(“send2trash”)
send2trash –> RecycleBin(“System Recycle Bin (safe deletion)”)
Loading
Area
Design
Local-first workflow
File scanning, indexing, duplicate detection, and organization run locally
Optional AI
Summarization can use local models or explicit cloud providers
Key storage
API keys use OS keyring when available, with encrypted fallback storage
Deletion safety
Duplicate removal uses the system recycle bin through send2trash
Telemetry
No analytics, tracking, or background phone-home behavior
The CI pipeline runs:
pytest — unit and UI tests
ruff check . — linting
ruff format –check . — formatting
mypy — static type checking
pip check — dependency consistency
Run the same checks locally before pushing.
FilePilot AI is packaged with PyInstaller on all three platforms. See docs/BUILD.md for complete build instructions, prerequisites, and troubleshooting.
# Quick build (auto-detect platform)
./scripts/build.sh
The GitHub Actions workflow (.github/workflows/ci.yml) automatically builds all three platforms:
Job
Platform
Runner
Artifact
Retention
build-windows
Windows
windows-latest
.exe installer
30 days
build-linux
Linux
ubuntu-latest
.AppImage
30 days
build-macos
macOS
macos-latest
.dmg
30 days
Each CI run produces SHA256 checksums alongside the artifacts.
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.
Background check every 24 hours (1 hour on failure)
Results cached to ~/.filepilot/update_check_cache.json
Fully thread-safe — runs in a daemon thread
See docs/README.md for the full documentation index.
Application screenshots and demo GIFs
Summary cache with invalidation
Large-folder indexing performance tuning
More organization templates
More end-to-end packaging tests
Contributions are welcome. See CONTRIBUTING.md for environment setup, style rules, and pull request guidance.
FilePilot AI is released under the MIT License.
Source link
Leave a Reply