Skip to main content

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​

  1. Open the menu drawer and click Watch
  2. Click Add Folder
  3. Select a folder using the file picker
  4. Configure filter and options
  5. Click Save

mahpastes immediately starts watching the folder.

Watch folders view

Configuration Options​

Filter Mode​

Control which files are imported:

ModeDescription
All FilesImport every file (default)
PresetsImport files matching preset categories
Custom RegexImport files matching a regex pattern

Presets​

When using preset mode, select one or more categories:

PresetFile Extensions
Imagesjpg, jpeg, png, gif, webp, heic, bmp, tiff, svg
Documentspdf, doc, docx, txt, md, rtf, odt, xls, xlsx
Videosmp4, 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:

  1. Select a tag from the Auto-tag dropdown
  2. Every file imported from this folder gets that tag
  3. 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​

  1. Open Watch view (menu drawer → Watch)
  2. Toggle the pause button for a specific folder
  3. Paused folders stop importing (but remain configured)

Global Pause​

  1. Click the global pause button
  2. All watching stops
  3. Click again to resume all

Edit Configuration​

  1. Open Watch view (menu drawer → Watch)
  2. Click the folder card you want to edit
  3. Modify filter or options
  4. Save changes

Remove​

  1. Open Watch view (menu drawer → Watch)
  2. Click the delete button on a folder
  3. 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​

IndicatorMeaning
Full opacity cardActively watching
Dimmed card (50% opacity) + Paused text labelPaused
Folder not found amber badgeWatched folder no longer exists on disk (or its volume is not mounted)
Not watching amber badgeThe 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​

  1. mahpastes uses filesystem events (fsnotify) to monitor each folder
  2. Only file Create and Write events trigger imports -- a file renamed into the folder counts as created; other events (chmod, remove) are ignored
  3. Hidden files (filenames starting with .) and downloads still in progress are automatically skipped (see below)
  4. 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
  5. Empty (zero-byte) files are skipped
  6. The file is read and stored as a clip
  7. If auto-archive or auto-tag is configured, those are applied to the new clip
  8. 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
Source File Removal

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:

  1. watch:file_detected -- fires before the file is imported, with the file path and folder ID
  2. watch: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​

  1. Check the folder card for a Folder not found or Not watching badge (hover Not watching for the reason)
  2. Verify it's not paused
  3. Check global pause is off
  4. A missing folder is picked up again within 30 seconds of reappearing; to retry at once, pause and resume it
  5. On Linux, a "no space left on device" reason means the system's inotify watch limit is reached; raise fs.inotify.max_user_watches (and fs.inotify.max_user_instances for "too many open files")

Files Not Importing​

  1. Check filter settings
  2. Test filter regex against filename
  3. Verify file permissions
  4. Check for error notifications
  5. Files with a download-in-progress name (.part, .crdownload, .tmp, ...) and empty files are skipped on purpose

High Resource Usage​

  1. Reduce number of watched folders
  2. Use more specific filters
  3. Disable "process existing" for large folders
  4. 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.