fo-core

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.

Prerequisites

1. Python 3.11 or later — check with python3 --version

2. Ollama — install from ollama.ai, then start it:

   ollama serve
   

Install

pip install fo-core

Then pull the default AI model (first-time only, ~3 GB):

ollama pull gemma3:4b

Verify optional deps for your files:

fo doctor ~/Downloads

Quick Start

# 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

Commands

Full flag documentation: docs/cli-reference.md

AI Providers

Default: Ollama — runs entirely on your machine, no API key needed.

Cloud providers are optional extras:

Optional Feature Packs

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:

Configuration

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 device

Full configuration reference: docs/CONFIGURATION.md

Documentation

Contributing / Development

See DEVELOPER.md for architecture, local setup, testing, and contribution guidelines.

Releases

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.

License

MIT OR Apache-2.0