FileForge

AI-powered file organizer using local Ollama inference — no cloud, no subscriptions.

What it does

• 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

Install

From PyPI (coming soon)

pip install fileforge

From source

git clone https://github.com/bitsandbots/fileforge.git
cd fileforge
bash scripts/install.sh

Requirements: Python 3.11+, Ollama (optional, for AI classification).

Quick start

# 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

Commands

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.

Web UI

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.

Background Automation

Watch mode

Monitor directories and scan on changes:

fileforge watch ~/Documents ~/Downloads --phase-2

Scheduled scans

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

Configuration

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

Development

bash scripts/install.sh       # editable install + dev deps
bash scripts/check.sh         # tests + lint + formatting
python -m pytest -q           # run tests

Documentation

• 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

License

MIT — see LICENSE.

---

A CoreConduit Consulting Services open-source tool. Issues and contributions welcome.