AI-powered file organizer using local Ollama inference — no cloud, no subscriptions.
- Scans directories and classifies files using local AI (Ollama) or rule-based heuristics
- Detects duplicates by content hash and semantic similarity
- Organizes files into category folders automatically
- Automates with watch mode and scheduled scans
- Runs offline — no data leaves your machine
pip install fileforge
git clone https://github.com/bitsandbots/fileforge.git
cd fileforge
bash scripts/install.shRequirements: Python 3.11+, Ollama (optional, for AI classification).
# Pull required Ollama models ollama pull qwen3:4b ollama pull nomic-embed-text # Scan a directory fileforge scan ~/Documents # Preview organization (dry-run) fileforge organize ~/Downloads --dry-run # Find duplicates fileforge dupes ~/Documents
| Command | Description |
|---|---|
fileforge scan <dirs> |
Scan and classify files |
fileforge organize <dirs> |
Move files to categorized folders |
fileforge dupes <dirs> |
Find and manage duplicates |
fileforge watch <dirs> |
Monitor for changes |
fileforge schedule <dirs> |
Schedule automated scans |
fileforge status |
Show session info |
fileforge server |
Start the web UI server |
Run fileforge --help for full options.
FileForge includes a web interface for visualizing scan results:
# Start the server (runs on http://localhost:8082) fileforge server # Development mode with auto-reload fileforge server --reload
Run fileforge server --help for full options.
Monitor directories and scan on changes:
fileforge watch ~/Documents ~/Downloads --phase-2
Run daily scans automatically:
# Daily at 2 AM fileforge schedule ~/Documents --cron "0 2 * * *" # Or use systemd (Linux) — scan timer + web UI server bash src/fileforge/systemd/install.sh # both (default) bash src/fileforge/systemd/install.sh --scan # scan timer only bash src/fileforge/systemd/install.sh --server # web UI on http://127.0.0.1:8082
Copy the example config and edit to suit:
cp fileforge.toml.example fileforge.toml
Create .forgeignore files in any directory to exclude patterns:
*.log
node_modules/
*.tmp
bash scripts/install.sh # editable install + dev deps bash scripts/check.sh # tests + lint + formatting python -m pytest -q # run tests
- Blueprint Overview — Single-page HTML reference (open in browser)
- Overview — Project goals and capabilities
- Architecture — Design and data flow
- Setup Guide — Detailed installation and usage
- Tech Stack — Dependencies and requirements
- API Reference — Python API + REST endpoints
- Gap Analysis — Known gaps between docs and code
MIT — see LICENSE.
A CoreConduit Consulting Services open-source tool. Issues and contributions welcome.