ShelfMate

A lightweight, open-source macOS utility app. ShelfMate lets you shake your cursor while dragging files to spawn a floating "shelf" where you can temporarily collect files before dropping them to their final destination.

Features

Core Features

• Shake to Create Shelf: While dragging files, quickly shake your cursor to spawn a floating shelf
• Global Keyboard Shortcut: Press ⌘⇧D to create a new shelf instantly
• Multi-File Collection: Drop multiple files onto the shelf from any application
• Drag Back Out: Easily drag collected files from the shelf to any destination
• Floating Window: The shelf stays on top of all windows for easy access
• Menu Bar App: Runs quietly in your menu bar, no dock icon clutter

Sharing & Actions

• Share Files: AirDrop, Mail, Messages via system share sheet
• Quick Look: Press Space to preview selected files
• Create ZIP: Archive multiple files into a ZIP
• Compress Images: Reduce image file sizes with quality options
• Batch Rename: Rename multiple files with patterns ({name}, {n}, {date})
• Clipboard Support: Cmd+C to copy, Cmd+V to paste files

Advanced Features

• Recent Shelves: Reopen previously closed shelves from menu bar
• Pinned Shelves: Persist important shelves across app restarts
• Edge Docking: Minimize shelves to screen edge, expand on hover
• iCloud Drive: Upload files to iCloud Drive for easy sharing
• Google Drive: Upload files and get shareable links

Installation

Requirements

• macOS 13.0 (Ventura) or later
• Xcode 15.0 or later (for building)

Download

Download the latest release from the Releases page.

Building from Source

1. Clone the repository:

   git clone https://github.com/stoimeniliev/shelfmate.git
   cd shelfmate

2. Open the project in Xcode:

   open ShelfMate.xcodeproj

3. Build and run (⌘R)

Permissions

ShelfMate requires Accessibility permissions to detect cursor shake gestures globally. On first launch, you'll be prompted to grant these permissions:

1. Go to System Settings → Privacy & Security → Accessibility
2. Enable the toggle for ShelfMate

Usage

Basic Usage

1. Start the app: ShelfMate runs in your menu bar (look for the stack icon)
2. Create a shelf: Either:
   • Start dragging files and rapidly shake your cursor left-right
   • Press ⌘⇧D (configurable)
   • Click menu bar → New Shelf
3. Drop files onto the shelf: Add files from Finder or any app
4. Use file actions: Click ⋯ for ZIP, compress, rename, cloud upload
5. Share files: Click the share button for AirDrop, Mail, Messages
6. Preview files: Press Space for Quick Look
7. Drag to destination: Drag files from the shelf to their final location
8. Close the shelf: Click X or press Escape

Keyboard Shortcuts

Shortcut	Action
⌘⇧D	Create new shelf (global)
Space	Quick Look preview
⌘A	Select all items
⌘D	Deselect all items
⌘C	Copy files to clipboard
⌘V	Paste files from clipboard
Escape	Close shelf

Menu Bar Options

Click the menu bar icon to:

• Create a new shelf
• Access recent shelves
• View pinned shelves
• Open Settings
• Quit the app

Settings

Access settings from the menu bar to configure:

• General: Shake sensitivity, launch at login
• Cloud: iCloud Drive and Google Drive configuration
• Shortcuts: Global keyboard shortcut configuration

Cloud Upload Setup

ShelfMate supports two cloud storage options:

iCloud Drive (Easiest)

Works out of the box if you're signed into iCloud:

1. Files are uploaded to iCloud Drive → ShelfMate Uploads
2. Share via Finder's Share button, iCloud.com, or AirDrop
3. Files sync automatically to your other Apple devices

Google Drive

Requires one-time setup:

1. Go to Google Cloud Console
2. Create a project and enable "Google Drive API"
3. Create OAuth 2.0 credentials (choose "Desktop app")
4. In ShelfMate, go to Settings → Cloud → Google Drive
5. Enter your Client ID and Client Secret
6. Click "Start Authentication" and authorize in browser
7. Paste the authorization code back into the app
8. Now you can upload files and get shareable links!

Architecture

ShelfMate/
├── ShelfMateApp.swift           # App entry point
├── AppDelegate.swift            # Menu bar setup, global coordination
├── Core/
│   ├── GlobalEventMonitor.swift # Monitors mouse events globally
│   ├── ShakeDetector.swift      # Shake gesture detection algorithm
│   ├── ShelfManager.swift       # Manages shelf window lifecycle
│   ├── QuickLookManager.swift   # Quick Look preview integration
│   ├── HotkeyManager.swift      # Global keyboard shortcuts
│   ├── ShelfHistory.swift       # Recent shelves persistence
│   └── EdgeDockManager.swift    # Screen edge docking
├── Actions/
│   ├── ShareManager.swift       # System share sheet integration
│   ├── FileActions.swift        # ZIP, compress, rename operations
│   └── CloudUploadManager.swift # iCloud & Google Drive integration
├── UI/
│   ├── ShelfWindow.swift        # Floating NSPanel window
│   ├── ShelfView.swift          # Main shelf SwiftUI view
│   ├── FileItemView.swift       # Individual file display
│   ├── DropZoneView.swift       # Drop target component
│   ├── RenameView.swift         # Batch rename dialog
│   └── CloudSettingsView.swift  # Settings tabs
└── Models/
    ├── ShelfItem.swift          # File item data model
    └── PinnedShelf.swift        # Pinned shelf persistence

How Shake Detection Works

1. Global Event Monitoring: Uses NSEvent.addGlobalMonitorForEvents to track mouse movements across all apps
2. Position History: Maintains a rolling history of mouse positions with timestamps
3. Direction Analysis: Detects rapid horizontal direction reversals within a time window
4. Debouncing: Prevents multiple triggers with a cooldown period

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Test thoroughly on macOS
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Code Style

• Follow Swift conventions and Apple's Human Interface Guidelines
• Use meaningful variable and function names
• Add comments for complex logic
• Keep functions focused and concise

Known Limitations

• Accessibility permissions must be granted for shake detection to work
• Some applications may not support standard drag-and-drop protocols
• The shelf window might not appear in full-screen applications

Roadmap

• Custom keyboard shortcut to create shelf
• File actions (compress, share, ZIP, rename)
• Multiple shelf support
• Quick Look preview
• Cloud upload with shareable links
• Recent shelves history
• Pinned shelves
• Edge docking
• Custom themes
• OCR text extraction from images
• Image format conversion
• Folder observation (auto-show shelf when files added)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with ❤️ by Stoimen Iliev
• Built with SwiftUI and AppKit

Support

If you find this project useful, please consider:

• Starring the repository ⭐
• Sharing it with others
• Contributing to the codebase

---

Made with ❤️ for the macOS community