Modern dual-panel file manager for macOS built with SwiftUI
Features • What's New • Screenshots • Installation • Architecture • Development • Contributing • Roadmap
I am not an architecture expert and do not claim to be one. If you notice mistakes or disagree with my methods, reasoning, or learning process, I welcome your feedback via email or social media. Much of what follows represents my first attempts in this area, so I ask for your patience and indulgence.
I openly acknowledge that I have used AI assistants to help clarify the philosophies and implementations of different architectures.
- Overview
- What's New in v0.9.1.1
- Why MiMiNavigator?
- Features
- Screenshots
- Requirements
- Installation
- Quick Start
- Architecture
- Development
- Technologies & Patterns
- Performance
- Roadmap
- Contributing
- CI/CD
- FAQ
- License
- Acknowledgments
MiMiNavigator is a modern dual-panel file manager for macOS, designed to explore advanced SwiftUI patterns while providing an efficient file management experience. Inspired by classic dual-panel file managers like Total Commander and Norton Commander, MiMiNavigator reimagines the concept using native macOS technologies and modern Swift concurrency.
- Native macOS Experience: Built entirely with SwiftUI for seamless integration with macOS design language
- Performance First: Leveraging Swift's modern concurrency model (async/await, actors) for responsive UI
- Clean Architecture: Clear separation of concerns with well-defined layers and responsibilities
- Developer-Friendly: Comprehensive logging, extensive documentation, and code quality tools
- Educational Resource: Demonstrating modern SwiftUI patterns and best practices for macOS development
- Modern UI: Implementing macOS 26 liquid-glass design language with authentic visual effects
👉 Source Code: Gui/Sources
Complete visual redesign following macOS Finder conventions:
- Clean selection: Solid blue fill without borders or rounded corners
- Standard fonts: System fonts (SF Pro) instead of custom styling
- Proper icons: 16pt icons matching Finder's compact view
- Zebra stripes: Alternating row colors using system colors
- Symlink display: Shows "Alias" for symlinks (Finder terminology)
Extended file information display:
- Permissions: Unix-style permissions (rwxr-xr-x) in monospaced font
- Owner: File owner username
- All columns sortable: Click any column header to sort
- Visual sort indicators: All columns show sort chevrons, active column highlighted
- Fixed header row: Column headers stay visible while scrolling
- Clear separators: Vertical dividers between columns
- Sort feedback: Active sort column highlighted with accent color
- Reduced logging: Removed verbose sorting/formatting logs
- Type-check optimization: Split complex SwiftUI views for faster compilation
- Clean architecture: Extracted view modifiers for better maintainability
Full drag-and-drop functionality between panels:
- Drag files and folders from any panel
- Drop on directories — highlighted with blue border on hover
- Drop on panel — transfers to current directory of that panel
- Confirmation dialog — macOS HIG-compliant with Move/Copy/Cancel buttons
- ESC cancels — Cancel is default, safe operation
- Visual feedback — drop targets highlight during drag
Complete implementation of a professional menu bar inspired by Total Commander with 8 fully structured menu categories:
| Menu | Description |
|---|---|
| Files | Rename/Move, Pack/Unpack archives, Compare, Sync directories |
| Mark | Select/Unselect groups, Select All, Invert selection |
| Commands | Command Prompt, CD Tree, Branch View |
| Net | FTP Connect/Disconnect, Network Neighborhood |
| Show | Full/Brief View, Hidden Files toggle |
| Configuration | Options, Customize Toolbar |
| Start | Tab management (New, Duplicate, Close) |
| Help | Index, Keyboard, About, Check for Updates |
- New glass-morphic menu bar with authentic Apple design:
- Ultra-thin material background with gradient overlays
- Crisp hairline borders with highlight/shadow effects
- Subtle top glow and bottom separator
- Multi-layered shadow system for depth
- Pixel-perfect rendering with
backingScaleFactorawareness
- HistoryPopoverView: Scrollable history of visited directories
- Per-panel navigation with quick-jump functionality
- Delete individual history items with swipe gesture
- Empty state with visual feedback
- Filtering directories only (excludes files from history)
- File Copy: F5 hotkey now copies selected file to opposite panel
- Automatic refresh after operations
- Conflict detection (skip if destination exists)
- Full logging of all file operations
- Modular menu architecture with
MenuCategoryandMenuItemmodels TopMenuBarViewwith proper accessibility labels- Compact fonts in tree views for better information density
- Updated app icons with new design
- Improved preview rendering
- Efficient Workflow: Navigate two directories simultaneously without switching tabs or windows
- Native Integration: Seamless integration with macOS Finder, Quick Look, and system services
- Real-time Updates: Instant synchronization with file system changes
- Keyboard-First: Designed for productivity with comprehensive keyboard shortcuts
- Total Commander Familiarity: Menu structure familiar to TC users
- Modern Swift Showcase: Real-world examples of Swift 6.2 features and concurrency patterns
- SwiftUI Best Practices: Demonstrating advanced SwiftUI techniques for complex macOS applications
- Clean Codebase: Well-structured, documented code with consistent style and patterns
- Learning Resource: Explore AppKit bridging, state management, and performance optimization
- Glass UI Implementation: Reference implementation of macOS 26 design language
- ✨ Actor-based concurrency for thread-safe directory scanning
- 🎯 Observable pattern with modern
@Observablemacro - 🔄 Real-time file system monitoring with FileManager events
- 🎨 Custom SwiftUI components including split view divider with hover effects
- 📝 Comprehensive logging with SwiftyBeaver for debugging and analysis
- 🧪 Quality tools integration (SwiftLint, Swift-format, Periphery)
- 🔐 Security-scoped bookmarks for sandbox-compliant file access
- 🎬 Animated toolbar buttons with visual feedback
- 🪟 Liquid-glass UI following macOS 26 design guidelines
- 📜 Navigation history with per-panel tracking
- 📦 Modular architecture with reusable Swift Packages (FavoritesKit)
- 🖱️ Drag-n-Drop with Transferable protocol and HIG confirmation dialogs
- Dual File Panels: Two independent file panels with synchronized navigation and operations
- Finder-Style Table: Clean UI following macOS Finder conventions
- Extended Columns: Name, Size, Date, Permissions, Owner, Type — all sortable
- Sticky Headers: Column headers remain visible during scroll
- Drag-n-Drop: Full drag-and-drop support between panels and into directories with confirmation dialog
- Real-time Monitoring: Automatic directory updates using FileManager's file system events
- Breadcrumb Navigation: Interactive path navigation with click-to-navigate functionality
- Quick Access Sidebar: Finder-like favorites and frequently used locations
- File Operations: Copy files between panels (F5), context menus for common operations
- Custom Split View: Adjustable panel divider with smooth dragging and hover feedback
- Security-Scoped Bookmarks: Persistent file access permissions for sandboxed operation
- Navigation History: Per-panel history with quick navigation popover
- Files Menu: Rename/Move (F6), Pack/Unpack archives, Compare, Sync directories, Quit
- Mark Menu: Select/Unselect groups, Select All, Invert Selection
- Commands Menu: Command Prompt, Desktop Folder, CD Tree, Branch View
- Net Menu: FTP Connect/Disconnect, Network Neighborhood
- Show Menu: Full/Brief View, Hidden Files toggle
- Configuration Menu: Options, Customize Toolbar
- Start Menu: New Tab, Duplicate Tab, Close Tab
- Help Menu: Index, Keyboard, Registration, Website, Updates, About
- Refresh Button (
⌘R): Animated refresh of both file panels with rotation and color change - Hidden Files Toggle (
⌘.): Show/hide hidden files with persistent preference - Open With (
⌘O): Opens files with default app, shows Finder Get Info for directories (centered on window) - Dev Build Badge: Shows current version with visual indicator
- macOS 26 Glass Design: Liquid-glass menu bar with authentic Apple styling
- Native macOS Design: Following Apple Human Interface Guidelines (HIG)
- Dynamic Type Support: Accessibility-ready with scalable fonts
- Context Menus: Rich context menus for files and directories
- Keyboard Navigation: Arrow keys, Enter, Tab panel switching, and command shortcuts
- Visual Feedback: Hover states, selection highlighting, animated buttons
- Auto-scroll Selection: Selected items always remain visible in long lists
- Compact Tree Fonts: Optimized for information density
- Thread-safe Operations: Actor-based directory scanning for concurrent file access
- State Management: Modern Observable pattern with proper isolation
- Memory Efficient: Lazy loading and efficient memory management
- Structured Logging: Multi-channel logging (console, file) with SwiftyBeaver
- Persistence Ready: UserDefaults integration for settings and bookmarks
- Permission Handling: Automatic permission request dialogs for restricted directories
- Pixel-Perfect Rendering:
backingScaleFactorawareness for Retina displays
- Multi-selection support with keyboard and mouse
- Search and filter functionality within panels
- File preview with Quick Look integration
- Drag & drop between panels
- Delete operations with confirmation dialogs
- Move/Rename operations (F6)
- Three-panel layout option
- Tabbed interface for multiple navigation contexts
- Advanced sorting and grouping options
- Custom themes and color schemes
- Terminal integration (open Terminal at current path)
- Archive support (zip, tar, etc.)
- FTP/SFTP connectivity
- Cloud storage integration (iCloud, Dropbox, etc.)
- Network file system support (SMB)
- Advanced file comparison tools
- Batch rename functionality
- Plugin system for extensibility
- Sync and backup features
See our Roadmap section for detailed planning.
File: Gui/Docs/Preview3.png
File: Gui/Docs/Preview2.png
File: Gui/Docs/Preview1.png
- macOS: 26.0 (Sequoia) or later
- Architecture: Apple Silicon (M1/M2/M3/M4) or Intel x86_64
- Xcode: 16.0 or later
- Swift: 6.2 or later
- Command Line Tools: Xcode Command Line Tools installed
- SwiftLint: For code style enforcement
- Swift-format: For automatic code formatting
- Periphery: For dead code detection
Note: The project uses Swift 6.2 strict concurrency mode with actor isolation.
🚧 Coming Soon: Pre-built binaries will be available in the Releases section once the project reaches beta status.
# Clone via HTTPS
git clone https://github.com/senatov/MiMiNavigator.git
# Or clone via SSH
git clone git@github.com:senatov/MiMiNavigator.git
# Navigate to project directory
cd MiMiNavigator# Open the Xcode project
open MiMiNavigator.xcodeprojAlternatively, you can open Xcode and use File → Open to select the project.
Option A: Using Xcode
- Select the "MiMiNavigator" scheme in the toolbar
- Choose your Mac as the destination
- Press
⌘Ror click the Run button
Option B: Using Command Line
# Build debug version
xcodebuild -scheme MiMiNavigator \
-configuration Debug \
-destination 'platform=macOS' \
CODE_SIGNING_ALLOWED=NO \
build
# Run the application
open build/Debug/MiMiNavigator.appFor convenient development builds, use the provided build script:
# Make script executable (first time only)
chmod +x Scripts/build_debug.zsh
# Build debug version
./Scripts/build_debug.zshBuild logs are automatically saved to build-logs/ directory with timestamps.
- Grant Permissions: On first launch, macOS may ask for file access permissions. Grant access to directories you want to navigate.
- Explore Interface:
- Left and right panels show your home directory by default
- Use the breadcrumb navigation at the top to navigate
- Click on folders to open them in the active panel
- Try Features:
- Right-click files/folders for context menus
- Use the divider between panels to resize them
- Click favorites in the sidebar for quick navigation
- Open Folder: Double-click or press
↵ Enter - Go Back: Click on parent folders in breadcrumb
- Switch Panels: Press
Tabor click on the panel you want to make active - Context Menu: Right-click on files or folders
- Resize Panels: Drag the divider between panels
- Navigation History: Click history button to see visited directories
| Shortcut | Action |
|---|---|
↑/↓ |
Navigate file list |
↵ Enter |
Open selected file/folder |
Tab |
Switch between panels |
⌘R |
Refresh both panels |
⌘. |
Toggle hidden files |
⌘O |
Open file / Get Info for directory |
F5 |
Copy selected file to other panel |
⌘W |
Close window |
⌘Q |
Quit application |
Home/PageUp |
Jump to first item |
End/PageDown |
Jump to last item |
MiMiNavigator follows modern Swift and SwiftUI architectural patterns with clear separation of concerns.
MiMiNavigator/
├── Gui/
│ ├── Sources/
│ │ ├── App/ # Application Core
│ │ │ ├── MiMiNavigatorApp.swift # App entry point, toolbar & window setup
│ │ │ ├── FileScanner.swift # File system scanning utilities
│ │ │ ├── LogMan.swift # SwiftyBeaver logging configuration
│ │ │ └── ConsoleCurrPath.swift # Debug path utilities
│ │ │
│ │ ├── AppGelegates/ # Application Lifecycle
│ │ │ └── AppDelegate.swift # AppDelegate for system events & bookmarks
│ │ │
│ │ ├── States/ # State Management Layer
│ │ │ ├── AppState.swift # Global app state (@Observable)
│ │ │ ├── DualDirectoryScanner.swift # Actor for concurrent file scanning
│ │ │ ├── FActions.swift # File operation action handlers
│ │ │ ├── SelectionsHistory.swift # Selection state tracking
│ │ │ ├── StableBy.swift # Stable identity wrapper for views
│ │ │ └── AppCommands.swift # Menu command handlers
│ │ │
│ │ ├── FilePanel/ # File Panel Components
│ │ │ ├── FilePanelView.swift # Panel container view
│ │ │ ├── FilePanelViewModel.swift # Panel state & business logic
│ │ │ ├── FileTableView.swift # File table with scroll management
│ │ │ ├── FileTableRowsView.swift # Table rows with stable IDs
│ │ │ ├── FileRow.swift # Individual file row view
│ │ │ ├── PanelFileTableSection.swift # File table section wrapper
│ │ │ └── PanelFocusModifier.swift # Focus management modifier
│ │ │
│ │ ├── Menus/ # Menu System (NEW)
│ │ │ ├── TopMenuBarView.swift # Glass-style menu bar container
│ │ │ ├── TopMenuItemView.swift # Individual menu item renderer
│ │ │ ├── MenuCategory.swift # Menu category model
│ │ │ ├── MenuItem.swift # Menu item model
│ │ │ ├── MenuItemContent.swift # Menu item content wrapper
│ │ │ └── HelpPopup.swift # Help popup view
│ │ │
│ │ ├── MenuMeta/ # Menu Definitions (NEW)
│ │ │ ├── TopMnuMetas.swift # All menu categories data
│ │ │ ├── FileContextMenu.swift # File context menu actions
│ │ │ ├── DirectoryContextMenu.swift # Directory context menu actions
│ │ │ ├── FileAction.swift # File action enum
│ │ │ └── DirectoryAction.swift # Directory action enum
│ │ │
│ │ ├── History/ # Navigation History
│ │ │ ├── HistoryPopoverView.swift # History popover component
│ │ │ └── HistoryItemRow.swift # Individual history item
│ │ │
│ │ ├── DragDrop/ # Drag-n-Drop System (NEW)
│ │ │ ├── DragDropManager.swift # Coordinator for drag-drop operations
│ │ │ ├── FileTransferOperation.swift # Transfer operation model
│ │ │ ├── FileTransferConfirmationDialog.swift # HIG confirmation dialog
│ │ │ └── CustomFileTransferable.swift # Transferable protocol conformance
│ │ │
│ │ ├── Favorite/ # Favorites Integration
│ │ │ ├── ButtonFavTopPanel.swift # Navigation panel with favorites button
│ │ │ └── FavoritesNavigationAdapter.swift # Adapter for FavoritesKit
│ │ │
│ │ ├── Config/ # Configuration & Preferences
│ │ │ ├── DesignTokens.swift # Design system tokens
│ │ │ ├── UserPreferences.swift # User settings (@Observable)
│ │ │ ├── PreferencesSnapshot.swift # Settings snapshot
│ │ │ └── PrefKey.swift # Preference key definitions
│ │ │
│ │ ├── Bubble/ # UI Components (NEW)
│ │ │ └── ToolTipMod.swift # Tooltip modifier
│ │ │
│ │ └── ... # Other modules
│ │
│ ├── MiMiNavigator.entitlements # App sandbox & permissions
│ └── Info.plist # App configuration
│
├── Packages/ # Swift Packages
│ └── FavoritesKit/ # Reusable Favorites module (.dylib)
│ ├── Package.swift # Package manifest (type: .dynamic)
│ └── Sources/FavoritesKit/
│ ├── FavoritesKit.swift # Package entry point
│ ├── FavoritesProtocols.swift # Public protocols
│ ├── FavoriteItem.swift # Favorite item model
│ ├── FavoritesBookmarkStore.swift # Security-scoped bookmarks
│ ├── FavoritesScanner.swift # Directory scanner
│ ├── FavoritesTreeView.swift # Main popup view
│ └── FavoritesRowView.swift # Tree row view
│
├── Scripts/ # Build & Development Scripts
└── .github/workflows/ # CI/CD Pipeline
@MainActor
@Observable
final class AppState {
var focusedPanel: PanelSide = .left
var selectedLeftFile: CustomFile?
var selectedRightFile: CustomFile?
var scanner: DualDirectoryScanner!
let selectionsHistory = SelectionsHistory()
}actor DualDirectoryScanner {
func refreshFiles(currSide: PanelSide) async {
let showHidden = await MainActor.run {
UserPreferences.shared.snapshot.showHiddenFiles
}
let scanned = try FileScanner.scan(url: url, showHiddenFiles: showHidden)
// ...
}
}actor BookmarkStore {
func requestAccessPersisting(for url: URL) async -> Bool {
// Shows NSOpenPanel, saves security-scoped bookmark
// Persists across app launches
}
func restoreAll() async -> [URL] {
// Restores saved bookmarks on app launch
}
}@MainActor
let filesMenuCategory = MenuCategory(
title: "Files",
items: [
MenuItem(title: "Rename/Move", action: { ... }, shortcut: "F6"),
MenuItem(title: "Pack...", action: { ... }, shortcut: "Alt+F5"),
// ...
])RoundedRectangle(cornerRadius: MenuBarMetrics.corner, style: .continuous)
.fill(.ultraThinMaterial)
.overlay(
RoundedRectangle(cornerRadius: MenuBarMetrics.corner, style: .continuous)
.strokeBorder(
LinearGradient(
colors: [
Color.white.opacity(0.30),
Color.blue.opacity(0.08),
Color.black.opacity(0.12),
],
startPoint: .top,
endPoint: .bottom
),
lineWidth: px
)
)-
Install Xcode 16.0+ from the Mac App Store or Apple Developer website
-
Install Command Line Tools:
xcode-select --install
-
Install Code Quality Tools (optional but recommended):
brew install swiftlint brew install swift-format brew install peripheryapp/periphery/periphery
-
Clone and Setup:
git clone https://github.com/senatov/MiMiNavigator.git cd MiMiNavigator
The app uses SwiftyBeaver for structured logging:
log.verbose("Detailed information")
log.debug("Debug information")
log.info("General information")
log.warning("Warning messages")
log.error("Error messages")Log Tags Used:
[SELECT-FLOW]— Selection change tracking[SCROLL]— Scroll position management[NAV]— Keyboard navigation[DOUBLE-CLICK]— File/folder openingMenu >— Menu item activation
Log Location: ~/Library/Logs/MiMiNavigator.log
| Technology | Purpose | Version |
|---|---|---|
| SwiftUI | UI Framework | macOS 15+ |
| Swift | Programming Language | 6.2 |
| AppKit | System Integration | macOS 15+ |
| SwiftyBeaver | Logging Framework | 2.0+ |
| FavoritesKit | Favorites module (dynamic library) | 1.0.0 |
- Strict Concurrency: Full actor isolation compliance
- @Observable Macro: Modern observation without Combine
- Async/Await: Clean asynchronous code
- Actors: Thread-safe state management
- Sendable: Cross-isolation data transfer
- ScrollViewReader: Programmatic scroll control
- PreferenceKeys: Child-to-parent communication
- NSViewRepresentable: AppKit bridging (NSOpenPanel, NSPathControl)
- View Modifiers: Reusable styling and behavior
- Materials:
.ultraThinMaterialfor glass effects - Gradients: Multi-stop gradients for depth
- Dual-panel file navigation
- Breadcrumb navigation
- Real-time directory monitoring
- Context menus
- Custom split view divider
- Logging infrastructure
- Security-scoped bookmarks (sandbox support)
- Hidden files toggle with persistence
- Open With / Get Info functionality
- Animated toolbar buttons
- Auto-scroll to selection
- Tab panel switching
- Finder-style file table UI
- Permissions and Owner columns
- All columns sortable with visual indicators
- Sticky column headers
- Reduced verbose logging
- Type-check optimizations
- Drag & drop between panels with confirmation dialog
- Drop target highlighting
- HIG-compliant confirmation dialog
- Total Commander-style menu system
- macOS 26 liquid-glass UI
- Navigation history with popover
- File copy operation (F5)
- Modular menu architecture
- Compact tree fonts
- Updated app icons
- Drag & drop between panels with confirmation dialog
Target: Q1 2025
- Multi-selection support
- Search functionality
- Quick Look integration
- Delete with confirmation
- Move/Rename (F6)
- Column width persistence
Target: Q2 2025
- Three-panel layout option
- Tabbed interface
- Custom themes
- Terminal integration
- Archive support
- FTP/SFTP support
- App Store submission
This project is licensed under the MIT License - see the LICENSE file for details.
Iakov Senatov Senior Java/Swift Developer
- 💼 LinkedIn:
- 🐙 GitHub: @senatov
- SwiftyBeaver: Excellent logging framework - GitHub
- Total Commander: The legendary dual-panel file manager inspiration
- Apple HIG: Human Interface Guidelines for macOS design
- Apple Figma Kit: macOS 26 design reference
Made with ❤️ for macOS
Building the future of file management, one commit at a time


