Sortora

Smart offline file organizer with AI-powered classification

Features • Installation • Quick Start • Commands • Docs

---

What is Sortora?

Sortora is an intelligent CLI tool that automatically organizes your files using smart filename analysis and optional AI classification. It works 100% offline - no cloud services, no data leaving your machine.

   ███████╗ ██████╗ ██████╗ ████████╗ ██████╗ ██████╗  █████╗
   ██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝██╔═══██╗██╔══██╗██╔══██╗
   ███████╗██║   ██║██████╔╝   ██║   ██║   ██║██████╔╝███████║
   ╚════██║██║   ██║██╔══██╗   ██║   ██║   ██║██╔══██╗██╔══██║
   ███████║╚██████╔╝██║  ██║   ██║   ╚██████╔╝██║  ██║██║  ██║
   ╚══════╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝

   Smart Offline File Organizer
   ───────────────────────────────────────────────────────

# Organize your Downloads folder
sortora organize ~/Downloads

# Preview what will happen (dry run)
sortora organize ~/Downloads --dry-run

Before:

~/Downloads/
├── Contract_Acme_Inc_2025.pdf
├── Invoice_GlobalTech_January_2025.pdf
├── John-Smith-Resume.docx
├── react-components.tsx
├── api-server.py
├── Screenshot_2025-01-15.png
└── ... 50 more files

After:

~/Downloads/
├── Contracts/
│   └── Acme Inc/
│       └── 2025/
│           └── Contract_Acme_Inc_2025.pdf
├── Finance/
│   └── Invoices/
│       └── GlobalTech/
│           └── Invoice_GlobalTech_January_2025.pdf
├── Documents/
│   └── Resumes/
│       └── John Smith/
│           └── John-Smith-Resume.docx
├── Code/
│   ├── React/
│   │   └── Components/
│   │       └── react-components.tsx
│   └── Python/
│       └── api-server.py
└── Screenshots/
    └── 2025-01/
        └── Screenshot_2025-01-15.png

Features

Beautiful CLI Experience

• Animated startup banner with gradient colors
• Progress indicators for all operations
• Colored output for easy reading
• Interactive mode with intuitive prompts

Smart Filename Analysis

• Extracts company names: Contract_Acme_Inc.pdf → Contracts/Acme Inc/
• Extracts person names: John-Smith-Resume.pdf → Resumes/John Smith/
• Detects document types: contracts, invoices, resumes, reports
• Recognizes dates: organizes by year/month from filename

Code File Organization

• Groups by language: Python, JavaScript, Go, Rust, etc.
• Detects file type: components, configs, utils, tests, styles
• Framework awareness: React, Vue, Svelte components

AI Classification (Optional)

• Zero-shot classification using MobileBERT
• Semantic embeddings using MiniLM
• OCR support for scanned documents
• 100% offline - models run locally

Safe Operations

• Dry run mode - preview changes before applying
• Interactive mode - confirm each action
• Undo support - rollback any operation
• Trash integration - deleted files go to trash

Installation

# Install globally
npm install -g sortora

# Run setup to download AI models (optional)
sortora setup

Requirements

• Node.js 18 or higher
• ~100 MB disk space for AI models (optional)

Quick Start

1. Run Sortora

# Just run sortora to see the animated banner and help
sortora

2. Scan a directory

sortora scan ~/Downloads

3. Preview organization

sortora organize ~/Downloads --dry-run

4. Organize files

# Interactive mode (confirm each action)
sortora organize ~/Downloads -i

# Auto mode (apply all suggestions)
sortora organize ~/Downloads --auto

Commands

Command	Description
sortora	Show animated banner and help
sortora setup	Initial setup, download AI models
sortora scan <path>	Scan and analyze files
sortora organize <path>	Organize files based on rules
sortora watch <path>	Watch folder and auto-organize
sortora duplicates <path>	Find duplicate files
sortora undo	Undo last operation
sortora rules list	List all rules

Organize Options

sortora organize <path> [options]

Options:
  -d, --deep          Scan subdirectories recursively
  --dry-run           Preview changes without applying
  -i, --interactive   Confirm each action
  --auto              Apply all suggestions automatically
  --global            Move files to global destinations (~/Documents, etc.)
  --confidence <n>    Minimum confidence for auto mode (0-1)

Organization Modes

Local Mode (default) Files are organized within the target directory:

sortora organize ~/Downloads
# Creates: ~/Downloads/Documents/, ~/Downloads/Code/, etc.

Global Mode Files are moved to system directories:

sortora organize ~/Downloads --global
# Moves to: ~/Documents/, ~/Pictures/, ~/Projects/, etc.

Supported File Types

Documents

Type	Extensions	Smart Sorting
Contracts	pdf, docx	Contracts/{Company}/{Year}/
Invoices	pdf	Finance/Invoices/{Company}/
Resumes	pdf, docx	Documents/Resumes/{Name}/
Reports	xlsx, pdf	Documents/Reports/{Year}/
Presentations	pptx, key	Documents/Presentations/

Code

Language	Extensions	Smart Sorting
JavaScript/TypeScript	js, ts, jsx, tsx	Code/{Language}/{Type}/
Python	py	Code/Python/
Go	go	Code/Go/
Vue/React/Svelte	vue, jsx, tsx	Code/{Framework}/Components/
Config	json, yaml, toml	Code/Config/
SQL	sql	Code/Database/

Media

Type	Extensions	Smart Sorting
Screenshots	png, jpg	Screenshots/{Year}-{Month}/
Photos	jpg, heic, raw	Photos/{Year}/{Month}/
Music	mp3, flac	Music/{Artist}/{Album}/
Video	mp4, mkv	Videos/{Year}/

Configuration

Config file location: ~/.config/sortora/config.yaml

version: 1

settings:
  mode: suggest  # or 'auto'
  confirmDestructive: true
  ignoreHidden: true
  ignorePatterns:
    - "*.tmp"
    - ".DS_Store"

destinations:
  photos: ~/Pictures/Sorted
  documents: ~/Documents/Sorted
  code: ~/Projects
  music: ~/Music/Sorted

Documentation

• Installation Guide
• CLI Usage Guide
• Configuration
• Rules System
• AI Features
• API Reference
• FAQ

Why Sortora?

Feature	Sortora	Others
Works offline	Yes	Often require cloud
Smart filename analysis	Yes	Basic patterns
AI classification	Yes (optional)	Rarely
Code file support	Yes	No
Multi-language filenames	Yes	Often EN only
Undo support	Yes	Rarely
Beautiful CLI	Yes	Basic
Open source	Yes	Often paid

Contributing

Contributions are welcome! Please read our Contributing Guide.

# Clone the repo
git clone https://github.com/d1maash/sortora.git

# Install dependencies
npm install

# Run in development
npm run dev

# Build
npm run build

# Test
npm test

License

MIT License - see LICENSE for details.

---

Made with care for your messy folders