Overview

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.

Demo

Highlights

Screenshots

Browse	Search

Organize	Duplicates

AI Summary	Index

Quick Start

Requirements

• 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

Install and Run

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

Development Setup

pip install -e ".[test,dev]"
pytest
ruff check .
ruff format --check .
mypy

CLI Examples

# 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

AI Providers

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.

Cloud providers only receive the content you choose to summarize. Local scanning, indexing, organization, and duplicate detection do not require AI.

Project Structure

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

Architecture

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)"]

Security and Privacy

Quality Gates

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.

Build (Cross-Platform)

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

CI Pipeline

The GitHub Actions workflow (.github/workflows/ci.yml) automatically builds all three platforms:

Each CI run produces SHA256 checksums alongside the artifacts.

Auto-Update

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

Documentation

See docs/README.md for the full documentation index.

Roadmap

• Application screenshots and demo GIFs
• Summary cache with invalidation
• Large-folder indexing performance tuning
• More organization templates
• More end-to-end packaging tests

Contributing

Contributions are welcome. See CONTRIBUTING.md for environment setup, style rules, and pull request guidance.

License

FilePilot AI is released under the MIT License.