📁 File Arranger

Terminal UI file organizer with real-time folder monitoring, 100+ file type categories, and configurable conflict strategies. Built with OpenTUI.

✨ Features

• 📂 Folder selection - Choose any folder to organize
• 🔄 Real-time monitoring - Watches the folder and auto-organizes new files
• 📊 Live counters - Total, organized, and pending file counts
• 🏷️ 100+ file types - Documents, Images, Videos, Audio, Code, Archives, Executables, Fonts, Books, Data, Downloads, and more
• ⚙️ Flexible config:
  • Destination folder - Same folder or a different one
  • Conflict strategy - Rename (default), Skip, or Overwrite
• 📝 Scrollable logs - Full history of organized files with vertical scroll

🚀 Quick Start

Prerequisites

• Bun installed (required by OpenTUI runtime)

Usage

# Run without installing
npx file-arranger

# Or install globally
npm install -g file-arranger
file-arranger

🎮 Controls

1. Type or edit the folder path in the input field
2. Press Tab to navigate between controls
3. Press Enter on the Start button to begin monitoring
4. Watch files being organized in real-time
5. Use Tab to reach the Stop button and press Enter to stop
6. Press Ctrl+C to exit

⚙️ Configuration

Conflict Strategy

When a file with the same name already exists in the destination:

• Rename (default): file.pdf → file (1).pdf
• Skip: The file is not moved
• Overwrite: Replaces the existing file

Destination Folder

By default, category folders are created inside the source folder. You can set a different destination in the Config panel on the left sidebar.

Categories

File categories and extensions are bundled into the application. The supported categories include:

| Category | Examples | |----------|----------| | Documents | .pdf, .doc, .docx, .xls, .xlsx, .ppt | | Images | .jpg, .png, .gif, .svg, .webp, .avif, .psd | | Videos | .mp4, .avi, .mkv, .mov, .m3u8, .mts | | Audio | .mp3, .wav, .flac, .aac, .ogg | | Code | .js, .ts, .py, .java, .cpp, .cs, .html, .css | | Archives | .zip, .rar, .7z, .tar, .gz, .iso | | Executables | .exe, .msi, .dmg, .pkg, .jar, .dll, .appimage | | Fonts | .ttf, .otf, .woff, .woff2 | | Books | .epub, .mobi, .azw, .cbr, .cbz | | Data | .db, .json, .xml, .csv, .sql, .bacpac | | Downloads | .torrent | | Others | Everything else |

🏗️ Architecture

The project follows a decoupled architecture:

• Core (src/core/): Business logic — file organization, extension mapping, folder watching, and config. Zero UI imports.
• UI (src/ui/): OpenTUI visual interface only. Consumes Core via callbacks.
• Main (src/main.ts): Orchestrates Core and UI connection.

📝 License

MIT