🖼️ Pic Organizer

AI-powered image organizer that uses local Ollama vision models to automatically categorize and rename images based on their content.

Features

• 🤖 AI-Powered Analysis: Uses Ollama with Ministral 3:14b vision model for intelligent image categorization
• 📁 Smart Organization: Automatically creates category folders and moves images
• 🏷️ Descriptive Naming: Renames images with AI-generated descriptive names
• 🔒 Privacy-First: Runs completely locally using your own Ollama instance
• ⚡ Reliable Processing: Sequential processing by default with optional concurrent mode
• 🔍 Dry Run Mode: Preview organization without making changes
• 🎯 Flexible: Supports multiple image formats and recursive directory scanning

Prerequisites

• Node.js 18 or higher
• Ollama installed and running locally
• Ministral 3:14b model pulled in Ollama

Install Ollama and Model

# Install Ollama (macOS)
brew install ollama

# Start Ollama server
ollama serve

# Pull the Ministral 3:14b model
ollama pull ministral-3:14b

Installation

Option 1: Install from source

# Clone or download the repository
cd pic-organizer

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Option 2: Run directly with tsx

npm install
npm run dev -- organize /path/to/images

Usage

Basic Usage

# Organize images in a directory
pic-organizer organize /path/to/images

# Organize images in current directory
pic-organizer organize

# Preview organization without moving files (dry run)
pic-organizer organize /path/to/images --dry-run

# Or use the preview command
pic-organizer preview /path/to/images

# Preview current directory
pic-organizer preview

Advanced Options

# Organize with custom concurrency
pic-organizer organize /path/to/images --concurrency 5

# Organize recursively (include subdirectories)
pic-organizer organize /path/to/images --recursive

# Use a different model
pic-organizer organize /path/to/images --model llava:13b

# Process only first N images
pic-organizer organize /path/to/images --limit 10

# Combine options
pic-organizer organize /path/to/images --dry-run --recursive --concurrency 3 --limit 20

Analyze Single Image

# Analyze a single image without organizing
pic-organizer analyze /path/to/image.jpg

Commands

organize

Organize images in a directory by content.

pic-organizer organize [directory] [options]

If no directory is specified, uses the current directory.

Options:

• -d, --dry-run: Preview organization without moving files
• -c, --concurrency <number>: Number of concurrent API requests (default: 1)
• -r, --recursive: Search for images recursively in subdirectories
• -m, --model <name>: Ollama model to use (default: ministral-3:14b)
• -l, --limit <number>: Limit processing to first N images

preview

Preview organization without moving files (alias for organize --dry-run).

pic-organizer preview [directory] [options]

If no directory is specified, uses the current directory.

analyze

Analyze a single image and show categorization results.

pic-organizer analyze <image> [options]

Options:

• -m, --model <name>: Ollama model to use (default: ministral-3:14b)

How It Works

1. Discovery: Scans directory for supported image formats (JPG, PNG, GIF, WebP, BMP, TIFF)
2. Optimization: Resizes large images to 1024px max dimension for faster processing
3. Analysis: Sends images to Ollama for AI-powered content analysis
4. Categorization: AI suggests category names based on image content
5. Organization: Creates category folders and moves images with descriptive names
6. Reporting: Displays summary with statistics and any errors

File Naming Convention

Images are renamed using the format: {suggested-name}_{timestamp}.{ext}

Examples:

animals/golden-retriever-playing-fetch_20260123-143022.jpg
landscapes/mountain-sunset-clouds_20260123-143045.jpg
food/chocolate-cake-with-berries_20260123-143108.jpg

If a filename already exists, a counter is appended: ...-1.jpg, ...-2.jpg, etc.

Configuration

Configure via environment variables:

# Ollama host (default: http://localhost:11434)
export OLLAMA_HOST=http://localhost:11434

# Default model (default: ministral-3:14b)
export OLLAMA_MODEL=ministral-3:14b

# Default concurrency (default: 1)
export CONCURRENCY=1

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• GIF (.gif)
• WebP (.webp)
• BMP (.bmp)
• TIFF (.tiff)

Examples

Organize Photos from Camera

pic-organizer organize ~/Pictures/Camera-Import --dry-run
# Review the proposed organization
pic-organizer organize ~/Pictures/Camera-Import

Organize Screenshots

pic-organizer organize ~/Desktop/Screenshots --recursive

# Or navigate to the directory first
cd ~/Desktop/Screenshots
pic-organizer organize --recursive

Fast Processing with Higher Concurrency

# Process up to 5 images simultaneously
pic-organizer organize ~/Pictures --concurrency 5

Test on First Few Images

# Test organization on first 5 images before processing all
pic-organizer organize ~/Pictures --limit 5 --dry-run
# If results look good, process first 10 for real
pic-organizer organize ~/Pictures --limit 10

Performance Notes

• First Analysis: The first image analysis may be slow as Ollama loads the model into memory
• Subsequent Analyses: Faster once the model is loaded
• GPU Recommended: A GPU significantly improves inference speed
• Concurrency: Processes one image at a time by default for reliability. You can increase concurrency for faster processing:
  • Default: 1 (sequential processing)
  • For faster systems: 2-3 concurrent requests
  • With powerful GPU: 5-10 is safe

Troubleshooting

"Cannot connect to Ollama server"

Make sure Ollama is running:

ollama serve

"Model not found"

Pull the model first:

ollama pull ministral-3:14b

"Failed to analyze image"

• Check if the image file is valid and not corrupted
• Ensure you have enough disk space for temporary files
• Try reducing concurrency with --concurrency 1

Images Not Being Found

• Check if the directory path is correct
• Use --recursive flag to search subdirectories
• Verify images have supported file extensions

Development

Project Structure

pic-organizer/
├── src/
│   ├── index.ts                 # CLI entry point
│   ├── cli.ts                   # Command-line interface
│   ├── config.ts                # Configuration
│   ├── services/
│   │   ├── ollama.service.ts    # Ollama API integration
│   │   ├── image.service.ts     # Image file operations
│   │   └── organizer.service.ts # Main orchestration
│   ├── utils/
│   │   └── file.utils.ts        # File system utilities
│   └── types/
│       └── index.ts             # TypeScript types
├── package.json
├── tsconfig.json
└── README.md

Build and Run

# Install dependencies
npm install

# Run in development mode
npm run dev -- organize /path/to/images

# Build for production
npm run build

# Run built version
npm start organize /path/to/images

# Type check
npm run type-check

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Acknowledgments

• Ollama - Local LLM runtime
• Mistral AI - Ministral vision models
• Sharp - High-performance image processing
• Commander.js - CLI framework
• Ora - Terminal spinners
• Chalk - Terminal colors