Watch Folders
Automatically import files from designated folders. Set up watch folders to capture screenshots, downloads, or any files as they appear.
Overview
Watch folders monitor directories on your system:
- New files are automatically imported as clips
- Configure filters to import only specific file types
- Optionally auto-archive imported files
- Pause watching per-folder or globally
Setting Up a Watch Folder
- Open the menu drawer and click Watch
- Click Add Folder
- Select a folder using the file picker
- Configure filter and options
- Click Save
mahpastes immediately starts watching the folder.

Configuration Options
Filter Mode
Control which files are imported:
| Mode | Description |
|---|---|
| All Files | Import every file (default) |
| Presets | Import files matching preset categories |
| Custom Regex | Import files matching a regex pattern |
Presets
When using preset mode, select one or more categories:
| Preset | File Extensions |
|---|---|
| Images | jpg, jpeg, png, gif, webp, heic, bmp, tiff, svg |
| Documents | pdf, doc, docx, txt, md, rtf, odt, xls, xlsx |
| Videos | mp4, mov, avi, mkv, webm, m4v, wmv |
Multiple presets can be selected (e.g., Images + Documents).
Custom Regex
For precise control, use a regular expression:
# Only PNG files
\.png$
# PNG and JPG
\.(png|jpe?g)$
# Files starting with "screenshot"
^screenshot.*
# Any image file
\.(png|jpe?g|gif|webp)$
The regex matches against the filename (not the full path).
Auto-Archive
Enable to automatically move imported files to archive:
- Keeps main gallery clean
- Good for background collection
- Find imports in Archive view
Auto-Tag
Automatically apply a tag to all imported files:
- Select a tag from the Auto-tag dropdown
- Every file imported from this folder gets that tag
- Select "None" to disable
Process Existing Files
When adding a new watch folder:
- Enabled: Import all existing files in the folder immediately. Source files are removed after import, the same as with live watching. Hidden files, downloads still in progress and empty files are skipped, as they are for new files.
- Disabled: Only import new files going forward
Managing Watch Folders
Pause/Resume
Per-Folder
- Open Watch view (menu drawer → Watch)
- Toggle the pause button for a specific folder
- Paused folders stop importing (but remain configured)
Global Pause
- Click the global pause button
- All watching stops
- Click again to resume all
Edit Configuration
- Open Watch view (menu drawer → Watch)
- Click the folder card you want to edit
- Modify filter or options
- Save changes
Remove
- Open Watch view (menu drawer → Watch)
- Click the delete button on a folder
- Confirm removal
The folder is no longer watched. Existing imported clips remain.
Notifications While in the Background
Imports and failed imports show as in-app toasts. To also get a native notification while mahpastes is minimised or behind other windows, turn on System Notifications in Settings; a sync of many files shows as one notification ("Imported 12 clips").
Watch Status
The dot on the Watch tab, and the dot on the menu button, are green while folders are being watched and turn amber when a folder that should be watched is not (it is missing, its volume is unmounted, or the operating system refused to watch it). mp watch status reports the same counts as Active and Unavailable.
A folder that disappears while it is watched (deleted, moved, or on a drive that was unplugged) is reported with a notification. mahpastes checks every 30 seconds and starts watching it again as soon as it is back, with a "Watching … again" notification; there is no need to restart the app. Files that arrived in the folder while it was not watched are not imported automatically; run mp watch process <id> (or POST /api/v1/watch/{id}/process) if you want them.
Folder Status Indicators
| Indicator | Meaning |
|---|---|
| Full opacity card | Actively watching |
| Dimmed card (50% opacity) + Paused text label | Paused |
| Folder not found amber badge | Watched folder no longer exists on disk (or its volume is not mounted) |
| Not watching amber badge | The folder exists but is not being watched right now; hover it for the reason (for example the system's file-watch limit) |
Use Cases
Screenshots Folder
Automatically capture all screenshots:
Folder: ~/Desktop or ~/Screenshots
Filter: Images preset
Auto-archive: Optional
Every screenshot you take appears in mahpastes.
Downloads Monitoring
Import specific download types:
Folder: ~/Downloads
Filter: Custom regex \.pdf$
Auto-archive: Yes
PDFs are imported and archived automatically.
Design Assets
Collect exported design files:
Folder: ~/Design/Exports
Filter: Images preset
Auto-archive: No
Design exports appear in main gallery for quick access.
Recording Outputs
Capture screen recordings:
Folder: ~/Movies
Filter: Videos preset
Auto-archive: Yes
Videos are imported and archived for later review.
Technical Details
How It Works
- mahpastes uses filesystem events (fsnotify) to monitor each folder
- Only file Create and Write events trigger imports -- a file renamed into the folder counts as created; other events (chmod, remove) are ignored
- Hidden files (filenames starting with
.) and downloads still in progress are automatically skipped (see below) - Events are debounced: the file must go 500ms without a change event, and its size and modification time must not have changed in that time, before it is imported
- Empty (zero-byte) files are skipped
- The file is read and stored as a clip
- If auto-archive or auto-tag is configured, those are applied to the new clip
- The original file is deleted from the watched folder after successful import, unless it changed while it was being read or a backup restore replaced the library in the meantime
Imported files are automatically removed from the watched folder after they are successfully stored in mahpastes. The file is only deleted once the database commit is confirmed. This prevents duplicate imports and keeps the watched folder clean.
Debouncing
Files are imported after 500ms of stability:
- Prevents importing partially-written files
- Waits for large files to finish writing (a file whose size or modification time is still changing gets another 500ms, even if the system sent no event for the change)
- On macOS, also waits while another program still has the file open for writing, so a copy or download that pauses is not imported half-written. The file is imported as soon as that program closes it; if it is still open after a minute, a notice says why the file has not been imported
- Handles rapid file creation gracefully
Downloads in Progress
Browsers and download tools write a download under a temporary name and rename it when it is complete. Files ending in .crdownload, .part, .partial, .download, .opdownload, .tmp, .!qb, .aria2 or .filepart, and files ending in ~, are never imported, whatever the folder's filter. The finished file is imported once it appears under its final name.
A tool that writes straight to the final name (curl -o, scp, a copy from a slow drive) is only covered by the checks under Debouncing. Where mahpastes cannot see the writer — on Windows and Linux, or on macOS when the writer runs as another user or on another machine (a network share) — a file whose writer pauses for longer than 500ms can be imported short and removed. Prefer tools that write to a temporary name and rename.
Firefox also creates an empty placeholder under the final name while it downloads. Empty files are never imported, so the placeholder is left alone and the real file is imported when the download completes. If you really want an empty file stored, add it with drag and drop or mp instead.
Folders That Disappear
A watch is tied to the folder that existed when watching started. If the folder is deleted and recreated, moved away, or is on a drive or network share that is disconnected, mahpastes notices (immediately when the system reports it, otherwise within 30 seconds), marks the folder as not watched, and starts watching it again once a folder is back at that path. A drive that was ejected and reconnected is picked up within 30 seconds; files that arrived in between are not imported, like files already in a folder when you add it. Restoring a backup also restarts watching; restored folders come back paused until you resume them.
Plugin Events
Watch folders emit two plugin events during the import lifecycle:
watch:file_detected-- fires before the file is imported, with the file path and folder IDwatch:import_complete-- fires after the clip is stored (and auto-archived/auto-tagged if applicable), with the new clip ID, source path, and folder ID
Plugins that subscribe to these events in their manifest can react to watch folder imports, for example to run image processing or apply additional tags.
Error Handling
If a file can't be imported:
- An error notification is shown
- Other files continue to be processed
- Check file permissions and format
Tips
Best Folder Choices
Good watch folders:
- Screenshot destinations
- Download folders (with filters)
- Export directories
- Drop zones you create
Avoid watching:
- System folders
- Very active directories (hundreds of files)
- Network drives (may be slow or unreliable)
Filter Strategy
- Start with presets for common use cases
- Use regex for precise matching
- Test regex on a few files first
- Combine with auto-archive for background collection
Performance
- Watch folders add minimal overhead
- Many watched folders are fine
- Very large folders may slow initial scan (if processing existing)
- Binary files are stored as-is (no processing)
Troubleshooting
Folder Not Watching
- Check the folder card for a Folder not found or Not watching badge (hover Not watching for the reason)
- Verify it's not paused
- Check global pause is off
- A missing folder is picked up again within 30 seconds of reappearing; to retry at once, pause and resume it
- On Linux, a "no space left on device" reason means the system's inotify watch limit is reached; raise
fs.inotify.max_user_watches(andfs.inotify.max_user_instancesfor "too many open files")
Files Not Importing
- Check filter settings
- Test filter regex against filename
- Verify file permissions
- Check for error notifications
- Files with a download-in-progress name (
.part,.crdownload,.tmp, ...) and empty files are skipped on purpose
High Resource Usage
- Reduce number of watched folders
- Use more specific filters
- Disable "process existing" for large folders
- Avoid watching very active directories
REST API & CLI
You can manage watch folders programmatically through the REST API or the mp CLI:
# List watch folders
mp watch list
# Add a new watch folder
mp watch add ~/Screenshots --filter-mode presets --presets images
# Pause a folder
mp watch pause <id>
# Process existing files in a folder
mp watch process <id>
See the REST API reference for the full set of watch folder endpoints.