Folder Watcher
Relevant source files
The following files were used as context for generating this wiki page:
The Folder Watcher is an automation component of the Crisp application designed to monitor specific directories for new video recordings. When a supported file is dropped into a watched folder, the system automatically triggers a background cleaning process to remove silences and filler words without requiring manual user intervention in the main GUI.
This system is implemented as a separate background executable (CrispWatcher) that runs as a macOS LaunchAgent. This architecture allows the application to monitor folders even when the main window is closed. The feature is highly integrated with the main application's settings, allowing users to configure watched paths, toggle automatic cleaning, and specify whether filler words should be removed during these background operations.
Sources: apps/desktop/Sources/Crisp/Views/SettingsView.swift:513-535, apps/desktop/build.sh:65-68, CLAUDE.md:79-84
Architecture and Components
The Folder Watcher system is split between a configuration interface in the main app and a dedicated background agent. The background agent is compiled as a separate Mach-O binary to ensure lightweight operation and persistence.
Background Executable (CrispWatcher)
The CrispWatcher binary is the core execution unit for folder monitoring. It is built alongside the main application and bundled within the app package at Contents/MacOS/CrispWatcher. It utilizes the FSEvents API (via FolderWatcher.swift) to receive low-level filesystem notifications from the operating system.
Sources: apps/desktop/build.sh:45-48, apps/desktop/Sources/CrispWatcher/main.swift
Lifecycle and LaunchAgent
To maintain persistence, Crisp registers the watcher as a LaunchAgent. The build.sh script stages a LaunchAgent.plist into the app bundle, which is later registered by the SMAppService API within the Swift code. This ensures the watcher can start at login and remain active in the background.
The diagram shows the lifecycle from app registration to background filesystem event processing.
Sources: apps/desktop/Sources/Crisp/Views/SettingsView.swift:537-550, apps/desktop/build.sh:103-108
System Logic and Data Flow
The Folder Watcher follows a specific sequence of operations when a filesystem change is detected:
- Event Detection: The
FolderWatcherclass monitors the path defined insettings.watchFolderPath. - Filtering: It identifies new file creations or moves into the directory.
- Validation: It checks if the file is a supported movie or audiovisual type.
- Execution: It shells out to the
CrispCleanCLI tool, passing the specific file path and the user's preferred cleaning parameters (e.g.,watchRemoveFillers).
Key Classes and Data Structures
| Class/Struct | Responsibility |
|---|---|
WatchAgentController | Main app service that manages the registration and status of the background agent. |
FolderWatcher | Low-level wrapper for FSEventStream that handles directory monitoring. |
EngineSettings | Provides the configuration source for watchFolderPath and watchEnabled flags. |
CrispWatcher (main.swift) | The entry point for the background process; initializes logging and services. |
Sources: apps/desktop/Sources/CrispWatcher/FolderWatcher.swift, apps/desktop/Sources/Crisp/Views/SettingsView.swift:510-525, apps/desktop/Sources/CrispWatcher/main.swift
Event Processing Sequence
Sequence illustrating the transition from an OS event to the execution of the cleaning CLI.
Sources: apps/desktop/Sources/CrispWatcher/FolderWatcher.swift, apps/desktop/Sources/CrispWatcher/main.swift
Configuration and User Interface
Users interact with the Folder Watcher primarily through the Automation tab in the Settings window (SettingsView.swift) and the Onboarding flow.
Settings and Controls
The following configuration options are available for the Folder Watcher:
| Setting | Type | Description |
|---|---|---|
watchFolderPath | String (Path) | The absolute directory path to be monitored. |
watchEnabled | Boolean | Global toggle to enable/disable the background agent. |
watchRemoveFillers | Boolean | Determines if the watcher should specifically target filler words during auto-cleans. |
Status Reporting
The WatchAgentController reports several states to the UI to help users troubleshoot:
- Active: The agent is running correctly.
- Requires Approval: The user must allow "Crisp" in System Settings > Login Items.
- Not Found: The background helper binary is missing from the bundle.
- Error: A specific error message (e.g., path permission issues).
Sources: apps/desktop/Sources/Crisp/Views/SettingsView.swift:513-560, apps/desktop/Sources/Crisp/Views/Onboarding/OnboardingView.swift:245-280
Implementation Details
Security and Permissions
Because Crisp is an ad-hoc application, it uses Automator workflows and specific LaunchAgent labels (AssociatedBundleIdentifiers) to ensure the background agent can communicate with the main app's data and settings without being suppressed by macOS security policies.
Sources: apps/desktop/Sources/Crisp/Services/QuickAction/QuickActionInstaller.swift:8-12, apps/desktop/build.sh:105-107
Background Integration
The CrispWatcher binary uses a FileLog system that is shared with the main app. This allows all cleanings—whether triggered by the GUI or the Folder Watcher—to be logged in the same daily log file located in ~/.crisp*/logs/.
Sources: CLAUDE.md:121-125, apps/desktop/Sources/CrispWatcher/main.swift
The Folder Watcher ensures a seamless, "hands-off" workflow by automating the initial editing pass for screen recordings as soon as they are saved to disk.