Local AI file organizer. Point it at a directory — it categorizes and moves your files using a model running on your own machine. Local by default: Ollama runs on-device, no API key required. Cloud providers are optional extras.
-
Python 3.11 or later — check with
python3 --version -
Ollama — install from ollama.ai, then start it:
ollama serve
pip install fo-coreThen pull the default AI model (first-time only, ~3 GB):
ollama pull gemma3:4bVerify optional deps for your files:
fo doctor ~/Downloads# Preview what would happen — no files are moved
fo organize ~/Downloads ~/Organized --dry-run
# Run it for real
fo organize ~/Downloads ~/Organized
# Changed your mind?
fo undo| Command | What it does |
|---|---|
fo organize [SRC] [DEST] |
Organize files using AI categorization |
fo preview [SRC] |
Dry-run preview without moving files |
fo search [QUERY] |
Full-text search across files |
fo analyze [DIR] |
File statistics and analysis |
fo dedupe |
Find and remove duplicate files |
fo suggest |
AI-powered organization suggestions |
fo autotag |
Auto-tag files based on content |
fo copilot |
Natural-language assistant |
fo rules |
Manage organization rules (YAML) |
fo config show|list|edit |
View or update configuration |
fo doctor [DIR] |
Scan a directory and recommend optional deps |
fo daemon start|stop |
Background file watcher |
fo undo / redo / history |
Operation history and rollback |
fo model |
Select or inspect AI models |
fo benchmark |
Performance benchmarks |
fo setup |
Interactive setup wizard |
Full flag documentation: docs/cli-reference.md
Default: Ollama — runs entirely on your machine, no API key needed.
Cloud providers are optional extras:
| Provider | Install | Works with |
|---|---|---|
| OpenAI-compatible | pip install "fo-core[cloud]" |
OpenAI, LM Studio, vLLM, Groq |
| Anthropic Claude | pip install "fo-core[claude]" |
Claude text + vision models |
| llama.cpp | pip install "fo-core[llama]" |
GGUF models — no Ollama required |
| MLX (Apple Silicon) | pip install "fo-core[mlx]" |
MLX-optimized local models |
Core file types (PDF, DOCX, XLSX, PPTX, EPUB, ZIP) work out of the box. RAR also works but requires a system-level unrar or unar binary. Install extras for additional capabilities:
| Pack | Install | Adds |
|---|---|---|
media |
pip install "fo-core[media]" |
Audio transcription (faster-whisper) + video scene detection. Use fo organize --transcribe-audio for content-aware audio categorization, or verify the install with fo benchmark run --suite audio --transcribe-smoke. |
dedup-text |
pip install "fo-core[dedup-text]" |
TF-IDF/cosine text deduplication |
dedup-image |
pip install "fo-core[dedup-image]" |
Image similarity deduplication |
scientific |
pip install "fo-core[scientific]" |
HDF5, NetCDF, MATLAB formats |
cad |
pip install "fo-core[cad]" |
DXF/DWG CAD files |
search |
pip install "fo-core[search]" |
BM25 + vector search |
all |
pip install "fo-core[all]" |
All of the above |
Config lives in ~/.config/fo/config.yaml. Override the location with the FO_CONFIG environment variable.
fo config show # view all settings
fo config edit --text-model gemma3:4b # change text model
fo config edit --device auto # change deviceFull configuration reference: docs/CONFIGURATION.md
| Doc | Contents |
|---|---|
| Getting Started | Installation options, first run, platform notes |
| CLI Reference | Every command and flag |
| Configuration | All config keys explained |
| FAQ | Common questions and troubleshooting |
| Troubleshooting | Diagnosing connection and model issues |
See DEVELOPER.md for architecture, local setup, testing, and contribution guidelines.
Currently 2.0.0-beta.7. The acceptance criteria that were required for this
promotion and the contract with public pre-release testers are documented in
docs/release/beta-criteria.md.
MIT OR Apache-2.0