A beautiful, highly customizable macOS app that displays rich file information when hovering over files in Finder, similar to Windows file preview behavior.
FinderHover isn't just a UI wrapper; it's a deep dive into macOS system integration. Here is how we built it:
We prioritize user privacy and system performance by utilizing the macOS Accessibility API directly (Core/FinderInteraction.swift). Unlike legacy tools that rely on slow, invasive AppleScript polling, FinderHover listens to the system's accessibility event stream.
- Zero Network Access: All processing happens locally.
- High Performance: Direct API calls minimize overhead.
- Context Awareness: Intelligently detects if you are renaming a file to avoid interrupting your workflow.
Built on top of Apple's native frameworks (AVFoundation, PDFKit, QuickLookThumbnailing), our metadata engine (Core/FileInfo.swift) is a lightweight powerhouse. It supports over 50 file formatsโfrom analyzing raw EXIF data in images to counting lines of code in source filesโwithout external heavyweight dependencies.
A smooth user experience is paramount. We leverage Combine (App/HoverManager.swift) to manage the stream of mouse events. By applying reactive operators like debounce, we ensure the UI updates fluidly only when you intend to hover, eliminating visual jitter and keeping CPU usage negligible.
- Instant Preview: Smart hover preview with adjustable delay (0.1s - 2.0s).
- QuickLook Integration: Native thumbnails for PDFs, images, and documents.
- Intelligent Context: Auto-hides when renaming files or dragging items.
- Photography (EXIF): Camera model, lens, ISO, aperture, shutter speed, GPS.
- Multimedia: Video codec, resolution, bitrate; Audio sample rate, channels.
- Development: Line counts for 25+ code languages, file encoding.
- Typography & Design: Font family/glyphs, Vector graphics (SVG/AI) dimensions.
- System: Permissions, owner, file paths, disk image compression ratios.
- Dual Personalities: Choose between a rich macOS style or a minimal Windows tooltip style.
- Full Control: Adjustable window size, opacity (70-100%), and font scaling.
- Layout Editor: Drag-to-reorder metadata fields and toggle visibility per category.
- Localization: Native support for English, Traditional Chinese (็น้ซไธญๆ), and Japanese (ๆฅๆฌ่ช).
Interested in the code? Here is how the project is structured:
App/: Application lifecycle and coordination (FinderHoverApp,HoverManager).Core/: The engine room. ContainsMouseTrackerfor event monitoring,FinderInteractionfor Accessibility API logic, andFileInfofor metadata extraction.UI/: Pure SwiftUI views.Windows/: The floating hover window and main settings container.Settings/: Modular, component-based settings pages.
Utilities/: Shared helpers for localization, logging, and formatting.
We follow Clean Code principles and SOLID architecture to ensure maintainability.
brew install koukeneko/tap/finderhover- Download
FinderHover.dmg.zipfrom Releases - Extract and move to Applications folder
- Launch FinderHover
git clone https://github.com/KoukeNeko/FinderHover.git
cd FinderHover
./scripts/build-dmg.shPermission Required: On first launch, you must grant Accessibility permission (System Settings > Privacy & Security > Accessibility). This is required to detect the file under your mouse cursor.
Settings: Press Cmd+, to access the configuration panel.
- Localization Improvements: Optimized label lengths for better layout consistency in compact modes.
- Performance: Fixed scrolling freeze in Settings view.
- Refactoring: Massive cleanup of Settings code for better stability.
Contributions are welcome! Please check out the Core/ directory if you're interested in the file detection logic, or UI/ for visual improvements.
MIT License - see LICENSE file for details.
Made with โค๏ธ and Swift