How rian445/macasc works
Purpose and Runtime
Mac ASC is a native macOS menu-bar utility combining disk insight, shell-command execution, notes, and on-demand AI CLI workflows. It is a Swift Package/AppKit + SwiftUI application, distributed as a DMG or Homebrew cask. Primary launch and panel lifecycle are in Sources/MacStorageUtilityApp.swift; packaging is driven by build.sh and Package.swift.
Application Shell and UI Boundary
The app exposes a status-bar item that controls a floating panel rather than a conventional web or document app window. The primary SwiftUI dashboard, tab switching, settings UI, and feature surfaces are centralized in Sources/DropdownView.swift. Native blur/glass treatment crosses into AppKit through Sources/VisualEffectView.swift, isolating platform-specific visual effects from the SwiftUI interface.
State Coordination
Sources/StorageViewModel.swift is the central application state coordinator. It bridges UI actions to storage scans, command state, notes, settings, tab customization, backup/restore, and AI workflow state. This is the primary control boundary between Sources/DropdownView.swift and system-facing operations in Sources/StorageManager.swift or native process execution.
Disk Insight Pipeline
Storage discovery and categorization are system-facing operations implemented by Sources/StorageManager.swift, with presentation and user interaction in Sources/DropdownView.swift. The pipeline scans directory sizes asynchronously, aggregates categories such as applications, developer caches, documents, media, and system files, and reads mounted/external volumes for display and ejection actions. Results flow back through Sources/StorageViewModel.swift to avoid making view code the source of scanning state.
Local Automation and Filesystem Features
Custom commands are user-defined shell scripts organized in nested paths. They can be handed to Terminal.app for visible execution or launched headlessly through Swift Process, with running-state and stop controls coordinated by Sources/StorageViewModel.swift and rendered in Sources/DropdownView.swift. Notes, pinned folders, local settings, sort structures, and JSON backup/import are likewise local-data features managed through the view model; no server-side application component is present.
AI CLI Integration
AI is intentionally an on-demand subprocess integration, not a resident model runtime: installed opencode, OpenAI codex, and Google antigravity/agy CLIs are invoked only when used, preserving zero idle AI memory. The execution/session orchestration belongs to Sources/StorageViewModel.swift; UI chat and Terminal handoff belong to Sources/DropdownView.swift. AI_ARCHITECTURE.md defines the intended multi-agent execution, workspace, and session-persistence model.
External Dependencies, Security, and Delivery
Material external boundaries are macOS/AppKit, filesystem and mounted-volume APIs, Terminal.app, local shell processes, and separately installed AI command-line tools. The stated privacy model is local-first with no analytics or telemetry; related constraints are documented in PRIVACY.md. Release delivery uses a bundled DMG via build.sh, while Casks/macasc.rb provides Homebrew installation metadata.
Main entry points: DropdownView.swift Dashboard & Feature UI · StorageViewModel.swift Application State · MacStorageUtilityApp.swift Menu Bar App · StorageManager.swift Storage Discovery
Components 17
App Shell & UI
- Menu Bar App · Owns status item and floating panel lifecycle.
Sources/MacStorageUtilityApp.swift - Dashboard & Feature UI · Hosts tabs, settings, storage, commands, notes, and AI surfaces.
Sources/DropdownView.swift - Native Glass Effects
Sources/VisualEffectView.swift
State & Local Features
- Application State · Coordinates UI state, local data, processes, scans, and AI sessions.
Sources/StorageViewModel.swift - Storage Discovery · Asynchronously scans sizes, categories, and mounted volumes.
Sources/StorageManager.swift - Local User Data · Notes, pinned folders, settings, sort data, and JSON backup/import.
- Command Runtime · Runs user shell scripts headlessly and tracks stop/running state.
- AI Workflow Sessions · Starts on-demand AI CLI workflows and preserves session state.
System Integrations
- Filesystem & Volumes · Directory metadata, mounted/external volumes, and ejection.
- Terminal.app · Receives visible command and AI handoffs.
- Local Shell Processes
- Installed AI CLIs · opencode, codex, and antigravity/agy run only on demand.
Architecture & Delivery
- AI Execution Design · Defines multi-agent execution, workspaces, and session persistence.
AI_ARCHITECTURE.md - Privacy Model · Documents local-first operation with no analytics or telemetry.
PRIVACY.md - Swift Package
Package.swift - DMG Build · Builds the bundled DMG distribution.
build.sh - Homebrew Cask
Casks/macasc.rb
Connections 17
- Menu Bar App → Dashboard & Feature UI: hosts floating panel
- Dashboard & Feature UI → Native Glass Effects: uses
- Dashboard & Feature UI → Application State: binds actions and state
- Application State → Storage Discovery: requests scans
- Storage Discovery → Filesystem & Volumes: scans directories and volumes
- Application State → Local User Data: manages
- Application State → Command Runtime: coordinates
- Command Runtime → Local Shell Processes: launches headlessly
- Dashboard & Feature UI → Terminal.app: hands off visible commands
- Application State → AI Workflow Sessions: coordinates
- AI Workflow Sessions → Installed AI CLIs: invokes on demand
- Dashboard & Feature UI → Terminal.app: hands off AI sessions
- AI Workflow Sessions → AI Execution Design: follows design
- Swift Package → Menu Bar App: builds
- DMG Build → Swift Package: packages
- Homebrew Cask → DMG Build: distributes DMG
- Privacy Model → Local User Data: documents local-first boundary