A Plum Amazing guide for Mac and iOS

Disk Cataloger

DiskCataloger™ catalogs hard drives, optical discs, disk images, and network shares. Search your archive offline, inspect metadata, verify files for bit rot, and find the drive you need.

App version 1.0 (pre-release) Updated 2026-11-12

1. Scan Drives & Discs100% read-only · Quick to Deep2. Search Offline AnytimePlain English · OCR · Meaning3. Pull, Verify & PackShelf checklist · Bit-rot guard

How Catalogger works: scan any drive, disc, folder, or network share once (read-only), then search, inspect, verify integrity, and plan retrievals even while your drives sit unplugged on the shelf.

DiskCataloger turns your external hard drives, SSDs, optical discs, SD cards, disk images, and network shares into one searchable catalog. The pre-release app and screenshots use the name Catalogger. Search across unplugged drives in milliseconds, inspect EXIF metadata, OCR text, and spoken transcripts offline, verify drives against silent bit rot, and plan exactly which shelf box to pull when you need your files back.

Read-only by design. Catalogger never creates, modifies, renames, or deletes any file on any volume you scan. No hidden dot-files or index folders are ever written to your drives. Every index, thumbnail, transcript, and backup lives exclusively inside Catalogger's own catalog folder on your Mac.

Choose a starting point:

1. Overview and Edition Guide#

Most creative professionals, families, and researchers eventually accumulate a closet or drawer full of external drives: photo archives from five years ago, client project SSDs, Time Machine backups, burned DVDs, SD cards, and a network NAS. Finding a single contract, RAW photo, or video clip usually means plugging drives in one by one and waiting for Spotlight or Finder to wake up.

Catalogger solves the unplugged-drive problem. You scan each drive once while it is connected, record a plain-English note about where it lives in the real world (such as "Shelf B, box 3" or "Media cabinet, Case 14"), and unplug it. From that moment on, you can browse its folders, search its filenames and document text, read its camera EXIF or audio tags, search words spoken inside its videos, and test what would be lost if that drive failed - all while the drive sits safely powered off on the shelf.

The Catalogger Dashboard showing six cataloged devices, single-copy risk counts, Needs Attention health alerts, Space Map entry, and the What If This Drive Dies simulator
The Catalogger Dashboard showing six cataloged devices, single-copy risk counts, Needs Attention health alerts, Space Map entry, and the What If This Drive Dies simulator

Four ways to use Catalogger#

DiskCataloger is built around a shared Swift engine (CataloggerCore). The table describes the four ways to use it:

Feature / Capability Catalogger Direct (macOS) Catalogger Mac App Store Catalogger for iOS (iPhone & iPad) catalogger CLI & MCP (macOS)
Primary role Full desktop cataloger, scanner, verifier, and organizer Sandboxed desktop cataloger and scanner Read-only pocket companion for exported catalogs Terminal automation, scripts, and AI agent MCP server
System requirements macOS 14.0 Sonoma or later (Apple silicon or Intel) macOS 14.0 Sonoma or later (Apple silicon or Intel) iOS 17.0 / iPadOS 17.0 or later (native iOS, not Catalyst) macOS 14.0+ (bundled with Direct edition)
Scan drives, folders, optical discs & shares Automatic or manual Prompted via security-scoped bookmarks (Grant Access...) Read-only browser (imports backups/catalogs from Mac) Reads and verifies existing Mac catalog
Mount & scan disk images (.dmg, .iso, .sparsebundle) Yes (read-only -readonly -nobrowse via hdiutil) Mount in Finder first, then scan as a connected volume Browse already-cataloged disk image contents Yes (via catalog queries)
Inspect busy processes blocking Eject Yes (names open apps and PIDs via lsof, offers Quit/Force Eject) Standard macOS unmount error reporting N/A N/A
Global hotkey from any app (Control-Option-Space) Yes (with optional Accessibility permission) In-app Command-K palette In-app search bar N/A
On-device meaning search (Apple NaturalLanguage) Included (no download required) Included (no download required) Queries precomputed Apple vectors Included (meaning: queries)
Optional stronger meaning model (EmbeddingGemma 2 GGUF) Optional user download (llama.cpp helper) Not offered in App Store build Not offered on iOS Supported when configured in Direct build

The read-only safety guarantee#

Archival drives often hold irreplaceable family photos, master audio sessions, or legal records. Catalogger enforces a strict read-only contract:

  1. Zero writes to scanned media: Catalogger never opens any file on a scanned drive for writing, never modifies extended attributes, and never drops .catalogger or metadata files onto your disks.
  2. Read-only disk image mounting: When you drop a .dmg, .iso, or .sparsebundle onto the Direct edition, Catalogger mounts it with hdiutil attach -readonly -nobrowse -nautoopen and detaches it automatically when the scan finishes.
  3. Read-only bit-rot verification: Even when verifying terabytes of files for silent corruption, Catalogger only streams bytes from the volume to compute SHA-256 digests in memory and writes the health summary to its own local SQLite database.

2. Installation, Permissions, and First Launch#

Installing Catalogger on your Mac#

  1. Direct Edition: When the Direct edition becomes available, download it from the Plum Amazing Store, open the disk image or archive, and drag Catalogger.app into your /Applications folder.
  2. Mac App Store Edition: When the Mac App Store edition becomes available, install Catalogger from the Mac App Store.
  3. Launch Catalogger from /Applications, Spotlight, or Launchpad. On first launch, a brief four-step Welcome to Catalogger tour introduces scanning, physical shelf labels, the Wanted List, and automatic backups. Click Get Started to enter the main workspace.

Understanding macOS privacy permissions#

Catalogger asks only for the permissions needed for the features you actually use, and every operation runs 100% on your Mac:

Permission When macOS prompts for it Where to manage it in System Settings
Removable Volumes The first time you scan an external USB/Thunderbolt drive, SD card, or optical disc Privacy & Security → Files and Folders → Catalogger
Network Volumes The first time you scan an SMB, AFP, or NFS network share Privacy & Security → Files and Folders → Catalogger
Desktop / Documents / Downloads Only if you explicitly choose File → Add Folder to Catalog... inside those folders Privacy & Security → Files and Folders → Catalogger
Full Disk Access (optional, Direct edition) Recommended if you want to catalog Time Machine .backupdb / APFS snapshot histories or protected system folders without per-folder prompts Privacy & Security → Full Disk Access
Speech Recognition (optional) Only if you turn on Transcribe speech in audio and video (on-device) in Settings → Metadata or in a Deep/Custom scan Privacy & Security → Speech Recognition
Accessibility (optional, Direct edition) Only if you enable the global Control-Option-Space Command Palette shortcut while working in other apps Privacy & Security → Accessibility

Mac App Store sandbox note: In the Mac App Store edition, macOS requires you to confirm folder access once per volume using a standard open panel (Grant Access...). Catalogger saves a read-only security-scoped bookmark so it can rescan that drive automatically whenever you reconnect it.

3. Quick Start: Your First Five Minutes#

You can experience the complete Catalogger workflow in five minutes - either with a real USB drive or SD card on your desk, or with Catalogger's built-in sample archive.

Step 1: Connect a drive (or load the sample archive)#

  • With a real drive: Plug in any external hard drive, SSD, USB stick, or SD card. A banner appears at the top of the Catalogger window: "<Volume Name>" connected - Add to Catalog.... Click Add to Catalog... (or click the drive under Connected on the Dashboard).
  • Without a drive handy: Open Settings → Advanced (Command-,) or the Debug menu in development builds and load the Sample Data set, which populates six realistic drives (Sample - Photo Archive 2019, Sample - Music Backup, Sample - MacBook Time Machine, Sample - Wedding DVD, Sample - NAS Media, and Sample - Work Docs USB).

Step 2: Name the drive and record its physical shelf location#

When the Add Drive to Catalog sheet opens:

  1. Give the drive a recognizable Name (for example, Blue Photo Archive 2019).
  2. Confirm its Device Type (such as External HDD, External SSD, USB Stick, SD Card, or Optical DVD).
  3. Fill in Physical location with where your hands will find this disk when it is unplugged - for example: Shelf B, box 3 or Studio closet, top bin.
  4. Choose a Scan Profile. Leave it on Standard for a great balance of speed and detail (thumbnails, EXIF/ID3/PDF metadata, document snippets, Archive contents, Vision image labels, and a fast partial fingerprint).
  5. Click Add & Scan.

Step 3: Watch the live progress and eject the drive#

While scanning, the top banner and sidebar show the live file count, byte total, and current path. You can start browsing and searching immediately while the scan is still running.

When the scan completes:

  1. Select your drive under Devices in the left sidebar.
  2. Press Command-E (or click the Eject button next to the drive).
  3. Once macOS says the drive is safe to disconnect, unplug it and put it back on your shelf. Notice the status dot next to the drive turns from green (Online) to gray (Offline).

Step 4: Find a file while the drive is unplugged#

  1. Press Command-F to focus the toolbar search field.
  2. Type a plain-English question or filename, such as: photos from 2019 or Contract pdf
  3. Click any result in the list and press Option-Command-I to open the right-hand Inspector.
  4. Even though the drive is unplugged, you can see the file's thumbnail, exact byte size, creation and modification dates, camera or PDF metadata, full folder path, and an orange callout telling you: Offline - connect "Blue Photo Archive 2019" (Shelf B, box 3).

Step 5: Add the file to your Wanted List and copy a pull checklist#

  1. In the Inspector (or by right-clicking the result row), click Add to Wanted.
  2. Press Command-3 (or click Wanted List in the sidebar).
  3. At the top of the Wanted List, read the Retrieval plan: Catalogger calculates the minimum number of drives you need to plug in to retrieve every wanted file, automatically checking whether an identical hash copy already exists on another drive that is connected right now.
  4. Click Copy Pull Checklist to copy a clean Markdown checklist sorted by shelf location, ready to paste into Notes or print before walking to your storage closet.
Try it yourself: Test what happens if a drive fails

Press Command-1 to open the Dashboard and scroll to What if this drive dies? at the bottom of the page. Click Simulate next to any drive. Catalogger compares every file on that drive against the rest of your archive and shows the exact files that exist nowhere else, grouped by top-level folder, with a one-click Add Unique Files to Wanted List button so you can back them up before the drive ages out.

4. Workspace Anatomy and Core Concepts#

Catalogger's main window is divided into four areas designed to stay fast and uncluttered even when your catalog grows past a million files:

  1. Left Sidebar (Command-1 through Command-6):
    • Library: Dashboard (Command-1), All Items (Command-2), Wanted List (Command-3), Recents (Command-4), Duplicates (Command-5), and Space Map (Command-6).
    • Devices: Grouped automatically by category (External, Optical, Network, Time Machine, Disk Image, Folder) with a live green/gray status dot, scan spinner, and context menu.
    • Smart Folders: Saved queries with live new-match badges.
    • Tags: User tags and automatically derived metadata tags with item counts.
  2. Top Toolbar & Search Bar:
    • Add (+) menu (Add Folder to Catalog..., Add Disk Image to Catalog..., Scan Connected Drives).
    • Scan Connected Drives (Shift-Command-R) button.
    • Advanced Search (Option-Command-F) rule builder button.
    • Inspector (Option-Command-I) toggle.
    • Search field (Command-F) with recent search history and live operator autocomplete.
  3. Center Content Area:
    • Displays the selected view: the Dashboard, the Search / Results view (switchable between List, Icons, and Gallery modes, with optional Filter Bar via Option-Command-L), the Device Browser (switchable between expandable Outline and Finder-style Columns), Wanted List, Duplicates, or Space Map.
  4. Right Inspector (Option-Command-I):
    • Shows the selected item's thumbnail, offline shelf location banner, action buttons (Reveal, Open, Quick Look, Copy Path, Add to Wanted), file attributes, Detected Signals (GPS place, Vision labels, copyable OCR text), Spoken Transcript segments, Tags, Note, Metadata groups (EXIF, Audio, Video, PDF), Content Preview, Other Copies, and Visually Similar images.

Core data concepts#

Understanding four terms will help you get the most out of Catalogger:

  • Device: Any physical or virtual storage unit you catalog - an external HDD/SSD, USB flash drive, SD card, optical CD/DVD/Blu-ray, Time Machine disk, network share (smb://, afp://, nfs://), disk image (.dmg/.iso), or standalone folder.
  • Volume: A mounted partition or APFS volume belonging to a Device. Most drives have one main volume; partitioned drives can have several.
  • Scan Profile (Quick, Standard, Deep, Custom): Controls which signals Catalogger extracts when scanning a drive. Because signals are additive, you can run a Quick scan in seconds today and enrich the same drive with a Deep scan later without losing your notes, tags, or history.
  • Capture Signals: Each item in the catalog tracks a bitmask of captured signals (hash, metadata, thumbnail, snippet, content, labels, ocr, place, phash, keyframes, transcript, embedding, archive). You can filter by signal coverage at any time using has:ocr, has:transcript, has:gps, or missing:hash.

5. Adding and Managing Drives, Discs, Disk Images, and Shares#

External hard drives, SSDs, USB sticks, and SD cards#

When you plug in an external drive or memory card, Catalogger's DriveMonitor inspects its hardware properties (volume UUID, DiskArbitration media UUID, IOKit USB/Thunderbolt serial number, vendor, model, and filesystem).

  • If the drive is new, click Add to Catalog... in the top banner or on the Dashboard.
  • If the drive has been cataloged before, Catalogger recognizes it even if you renamed the volume in Finder or plugged it into a different USB port.

Optical discs (CDs, DVDs, and Blu-ray)#

Optical media often lacks a writable volume UUID. Catalogger computes a deterministic Disc ID from the disc's table of contents, size, and creation timestamp so each burned DVD or audio CD is uniquely recognized when reinserted.

  • When adding an optical disc, the Case number field appears automatically in Add Drive and Get Info so you can record binder slots (such as Binder 2, Sleeve 14) and search them with case:14.

Folders and disk images (.dmg, .iso, .sparsebundle)#

  • Any folder: Choose File → Add Folder to Catalog... (Shift-Command-O), or drag any folder from Finder directly onto the Catalogger window.
  • Disk images: Choose File → Add Disk Image to Catalog..., or drag a .dmg, .iso, .toast, or .sparsebundle file onto the window. In the Direct edition, Catalogger mounts the image invisibly in read-only mode, catalogs everything inside, and detaches it when finished.

Network shares (SMB, AFP, NFS) and Time Machine#

  • Network shares: Mount the share in Finder (Command-K in Finder), then select it in Catalogger's Connected section or choose File → Add Folder to Catalog.... Catalogger records the server URL (such as smb://nas.local/media) as a persistent identity key.
  • Time Machine drives: Catalogger detects Time Machine backup disks (.backupdb and APFS backup roles), records snapshot counts and date ranges per file (snapCount, snapFirst, snapLast), and lists individual snapshots inside Device Get Info.

Device Browser: Outline, Columns, and Removed Items#

Click any drive under Devices in the sidebar to browse its folder hierarchy offline:

Browsing an offline drive in Finder-style Columns mode while inspecting a photo's EXIF metadata, Detected Signals, and Spoken Transcript on the right
Browsing an offline drive in Finder-style Columns mode while inspecting a photo's EXIF metadata, Detected Signals, and Spoken Transcript on the right
  • Outline vs. Columns: Switch between an expandable tree (Outline) and Finder-style Miller columns (Columns) using the segmented control in the header.
  • Removed toggle: Turn on Removed in the header to reveal files that existed on an earlier scan of this drive but were deleted or moved before the most recent scan, complete with the date they disappeared.
  • Breadcrumb bar: Click any parent folder in the breadcrumb trail below the header to jump up the hierarchy.

Device Get Info and Printable Case Cards#

Click Get Info in a device's header (or right-click the device in the sidebar and choose Get Info) to open the device sheet:

The Device Get Info sheet showing physical shelf location, Copy Case Card button, hardware serial and capacity, and recorded bit-rot verification status
The Device Get Info sheet showing physical shelf location, Copy Case Card button, hardware serial and capacity, and recorded bit-rot verification status

From Get Info, you can:

  • Edit the device's Name, Type, Physical location, Case number, Tags, and Notes, or attach a Photo of the physical drive or binder sleeve.
  • Review Hardware details (vendor/model, hardware serial, filesystem, capacity, first/last seen, last scanned, and Last verified bit-rot summary).
  • Click Copy Case Card in the top-right corner to copy a compact Markdown label card containing the drive's name, location, capacity, top-level folders, last scan/verification dates, and a catalogger://device/<uuid> deep link - ideal for printing on index cards, Dymo labels, or jewel-case inserts.

6. Scanning, Profiles, and Automatic Schedules#

Comparing the four Scan Profiles#

Every time you scan a drive (or configure default scanning behavior in Settings → Scanning), you can choose one of four profiles:

Signal / Option Quick Standard (Default) Deep Custom
Speed Fastest (directory tree only) Fast everyday default Thorough archival capture You choose every toggle
File & folder names, sizes, dates, UTIs Yes Yes Yes Always on
Content fingerprint (Hash) None Fast partial (p256:: first + last 1 MB + size) Full cryptographic sha256: of every byte Off, Partial (p256:), or Full (sha256:)
EXIF, ID3/Audio, Video & PDF metadata No Yes Yes Configurable
Image, video & PDF thumbnails No Yes (320 px HEIC) Yes (320 px HEIC) Configurable
Inside archives (.zip, .tar, .tar.gz, .7z, .rar) No Yes Yes Configurable
Document text (content:) No First 4 KB snippet Full text up to 64 KB Off, Snippet, or Full
Reverse-geocoded GPS place names (place:) No Yes (offline 5,000-city gazetteer) Yes Included with metadata
Vision image labels (label:) No Yes (on-device VNClassifyImageRequest) Yes Configurable
Perceptual image hash (dHash) for similar photos No Yes Yes Configurable
Video keyframes (5 perceptual hashes across duration) No No Yes Configurable
Text inside images & scanned PDFs (ocr:) No No Yes (on-device VNRecognizeTextRequest) Configurable
Spoken audio/video transcript (transcript:) No No Optional (SFSpeechRecognizer, on-device) Configurable
Meaning vectors (meaning:) No Optional Yes Configurable

Incremental scanning and enrichment#

When you rescan a drive (Shift-Command-R or Rescan in the device header):

  1. Catalogger compares each file's size and modification timestamp against the existing catalog row.
  2. Unchanged files are skipped immediately unless you are running a deeper profile than before (for example, upgrading a Quick scan to Standard or Deep). When enriching, Catalogger extracts only the missing signals (writeEnrichment) and merges them into the existing record without touching your tags or notes.
  3. Deleted files are marked as removed (deleted = 1 with removed_at timestamp) rather than erased, unless you uncheck Keep a history of files removed between scans in Settings → Scanning.

Automatic schedules, quiet hours, and per-device rules#

Open Settings → Scanning and Settings → Devices to automate how connected drives are kept fresh:

  • When a known drive is connected: Choose Scan automatically, Ask before scanning, or Do nothing (configurable separately for external drives, network shares, and optical discs).
  • Minimum time between auto-scans: Prevents repeated scans when you plug and unplug a drive several times in the same day (default 24 hours).
  • Scheduled rescan of connected drives: Run Hourly, Daily (at a chosen hour), or Weekly (on a chosen weekday and hour).
  • Battery, Low Power Mode, and Quiet Hours: Pause automatic scans when your MacBook is on battery power, in Low Power Mode, or inside your defined quiet hours (for example, 22:00 to 07:00).
  • Per-device overrides: In Settings → Devices or inside any drive's Get Info → Scanning Rules, switch a drive from Follow global settings to Custom rules or Ignored to set drive-specific exclude globs (like *.tmp, node_modules, Cache*), skip depth limits, or scan profiles.

7. Searching Your Archive (Plain English, Operators, and Meaning)#

Catalogger combines an FTS5 full-text index, structured SQLite filters, a deterministic plain-English query rewriter, and on-device vector embeddings so you can search a million cataloged items in milliseconds.

Searching in plain English for "photos from 2019 on Photo Archive": Catalogger shows the interpreted operator chips above the results and highlights matched signals in the Inspector
Searching in plain English for "photos from 2019 on Photo Archive": Catalogger shows the interpreted operator chips above the results and highlights matched signals in the Inspector
  1. Toolbar Search (Command-F): Type plain English, filenames, or operators from anywhere in the app.
  2. Search Within Results (Shift-Command-F): Narrows your current search by appending to the existing query.
  3. Filter Bar (Option-Command-L): Toggle interactive filter pills for Kind, Device, Availability (Online / Offline), Size, and Date Modified.
  4. Advanced Search Builder (Option-Command-F): Build complex multi-rule queries visually with pop-up menus and save them as Smart Folders in the sidebar.
  5. Command Palette (Command-K or Control-Option-Space): A fast floating launcher that searches files, jumps to devices, and triggers commands (Scan Connected Drives, Eject, Export, Back Up Catalog Now) from the keyboard.

Plain-English queries and operator chips#

When Understand plain-English queries is enabled (the default in the search options popover), you can type natural phrases just as you would ask a colleague:

What you type in the search bar How Catalogger interprets it
photos from 2019 on Photo Archive kind:image modified:2019 device:"Sample - Photo Archive 2019"
the lease pdf from 2021 ext:pdf modified:2021 lease
videos over 2 GB on only one drive kind:video size:>2GB singlecopy:yes
photos taken in Lisbon without raw kind:image place:Lisbon -ext:raw
podcast where they talk about sleep and magnesium kind:audio meaning:"sleep and magnesium"

Whenever Catalogger rewrites a plain-English phrase, a bar appears directly above the results showing removable operator chips for each interpreted filter. Click × on any chip to remove that constraint, or click Use operators to copy the explicit operator string into the search field.

Exact operator preservation: If you type explicit boolean operators (OR, AND, NOT), quoted phrases ("exact phrase"), wildcards (IMG_*.cr3), or exclusion prefixes (-2022), Catalogger runs your query verbatim without rewriting it.

Complete Search Operator Reference#

Press Shift-Command-/ (or choose Help → Search Syntax) at any time to open this reference inside the app:

Category Operator / Syntax Examples What it matches
Boolean & Grouping AND, OR, NOT, -term, ( ... ) (jpg OR heic) -thumb Combines or excludes terms; spaces imply AND
Exact & Wildcard "...", *, ? "Final Cut", DSC_00??.NEF Exact phrase match or shell-style filename glob
Text Scopes name:, path:, ext:, folder:, in: name:invoice ext:pdf in:2023 Restricts text match to filename, path, extension, or folder
Notes & Tags tag:, tags:, note:, notes: tag:favorite note:client Matches user/metadata tags or item notes
Document & Speech Text content:, ocr:, transcript:, said: content:"indemnify" ocr:8420 said:sunset Searches indexed document text, OCR text in images/PDFs, or spoken transcripts
Vision & Places label:, vision:, place: label:mountain place:Yosemite Matches Apple Vision image classification labels or reverse-geocoded GPS places
Meaning (Semantic) meaning: meaning:"contract termination clause" Ranks items by conceptual similarity (plus lexical fallback)
Kind & Type kind:, type:, is: kind:image, kind:video, is:folder, is:archive image, video, audio, document, pdf, archive, code, folder, other
Size size: size:>100MB, size:10MB..1GB, size:<50KB Filters by byte size (B, KB, MB, GB, TB)
Dates & Times modified:, created:, taken:, removed: modified:2024, taken:2019-06..2019-08, modified:>30d Year, YYYY-MM, ISO date, date range (..), or relative age (7d, 6m, 2y)
Time of Day & Weekday timeofday:, weekday: timeofday:evening weekday:weekend morning, afternoon, evening, night; monday..sunday, weekday, weekend
Devices & Shelf Location device:, drive:, location:, case:, online: device:"Photo" location:"Shelf B" case:14 online:no Filters by device name, physical shelf location, optical case number, or connection state
Camera, Audio & PDF camera:, lens:, iso:, artist:, album:, author:, codec:, duration:, dimensions:, pages: camera:Nikon duration:>5m pages:>20 Matches extracted EXIF, ID3, video codec/resolution, or PDF page counts
Redundancy & Health duplicate:yes, singlecopy:yes, copies:, hash:, snapshots: singlecopy:yes size:>500MB, copies:>2 Finds files with only one copy, cross-drive duplicates, or Time Machine snapshot counts
Signal Coverage has:, missing: has:ocr, has:transcript, missing:hash Filters by captured signal (hash, thumb, meta, content, ocr, labels, gps, place, phash, transcript, embedding, archive)

Search by Meaning: Apple NaturalLanguage vs. Optional EmbeddingGemma 2#

When you enable By meaning in the search options popover or use the meaning:"..." operator, Catalogger blends hybrid vector similarity (z-scored cosine similarity) with lexical FTS coverage and exact-name tiers.

Settings -> Search showing match explanations, on-device meaning vector configuration, the 500 MB storage cap, and the optional EmbeddingGemma 2 model in the Direct build
Settings -> Search showing match explanations, on-device meaning vector configuration, the 500 MB storage cap, and the optional EmbeddingGemma 2 model in the Direct build

Catalogger supports two 100% local embedding engines in Settings → Search:

  1. Apple On-Device Language Model (NLEmbedding, Default in all editions):
    • Built into macOS and iOS. Requires zero downloads, runs in process, and stores compact 512-dimension float16 vectors (~512 bytes per item, capped by default at 500 MB).
  2. Optional Stronger Model - EmbeddingGemma 2 (Direct macOS edition only):
    • For deeper semantic recall across complex descriptions, the Direct edition can use Google's open-weights ggml-org/embeddinggemma-2-GGUF (embeddinggemma-300M-Q8_0.gguf, 768 dimensions) via a local llama.cpp helper (llama-server or llama-embedding).
    • How to set up EmbeddingGemma 2 (Direct edition):
      1. Install the llama.cpp helper by running scripts/setup-llama-helper.sh (or brew install llama.cpp).
      2. Open Settings → Search and scroll to Optional stronger model (direct build).
      3. Review and accept the Google Gemma Terms of Use checkbox, then click Download Text Model (314 MB, Q8_0). Catalogger verifies the SHA-256 digest of the downloaded .gguf file before registering it.
      4. Turn on Prefer EmbeddingGemma 2 for meaning search when ready.

8. Inspecting Items, Deep Signals, Transcripts, and Visually Similar Media#

Select any item in Search, Recents, Duplicates, or the Device Browser and press Option-Command-I to open the Inspector:

  • Offline Shelf Callout: When the item's drive is unplugged, an orange card at the top of the Inspector shows the drive name, its physical location (Shelf B, box 3), and a Notify Me When Connected button.
  • Detected Signals: Displays reverse-geocoded Place names (Yosemite Valley, US), Apple Vision Labels (mountain sunset landscape outdoors), and a selectable, copyable box for Text in image (OCR) (TRAILHEAD ELEVATION 8,420 FT).
  • Spoken Transcript: When an audio or video file has an on-device transcript, Catalogger displays the best-matching timestamped quote for your current search query (Best match at 0:07: "wind picking up from the west.") and an expandable Segments list showing every time-coded line.
  • Other Copies Across Your Archive: Lists every other drive and path that holds a byte-identical copy (hash match) of the selected file, with live online/offline status dots and one-click navigation.
  • Visually Similar Images (dHash): For photos and video keyframes with a 64-bit perceptual difference hash (dHash), Catalogger finds resized, re-saved, or lightly cropped siblings across your drives (Hamming distance  ≤ 10) and lists them directly under Visually Similar.
  • Context Menu Shortcuts: Right-click any item row to Find All Copies by Hash, Find Similar Name, Add to Wanted List, Notify When Drive Connected, Copy Path, or Export Selection....

9. Offline Retrieval, Wanted List, and Safe Eject#

Planning a shelf walk with the Wanted List (Command-3)#

When you need files from several unplugged drives, add them to your Wanted List instead of hunting for drives one by one:

The Wanted List showing the greedy Retrieval Plan at the top, Copy Pull Checklist button, Notify Me watch toggle, and three queued photos from Shelf B, box 3
The Wanted List showing the greedy Retrieval Plan at the top, Copy Pull Checklist button, Notify Me watch toggle, and three queued photos from Shelf B, box 3
  1. Open Wanted List (Command-3) in the sidebar.
  2. Read the Retrieval plan at the top of the view:
    • Catalogger uses a greedy set-cover planner (RetrievalPlan) that checks all byte-identical copies (hash) across your entire catalog.
    • If a file you queued from an offline archival drive also has a copy on a drive that is connected right now, Catalogger tells you that you can retrieve it immediately without unplugging or fetching anything.
    • For remaining offline files, Catalogger ranks the exact drives to fetch in order of how many wanted files each drive satisfies.
  3. Click Copy Pull Checklist to copy a formatted Markdown checklist grouped by drive and physical shelf location (Shelf B, box 3), listing each file's relative path and byte size.
  4. Click Notify Me next to any offline drive to register a Connection Watch: the next time you plug that drive into your Mac, Catalogger posts a macOS notification ("Blue Photo Archive 2019 connected - 3 wanted items ready") and shows a banner at the top of the window.
  5. Once the drive is connected, click Copy To... to copy the files into a destination folder on your Mac (with automatic collision-safe renaming if a filename already exists), or Reveal to highlight them in Finder.

Safe Eject and busy-process inspection (Command-E)#

Select any connected drive and press Command-E (or click Eject in the sidebar, toolbar, or Menu Bar Extra):

  • If any Catalogger scan is currently reading that drive, Catalogger cancels the scan cleanly and closes its own file descriptors first.
  • If macOS refuses to unmount the volume because another application still has a file open, the Direct edition runs /usr/sbin/lsof on the mount point and opens the Drive Is Busy sheet (EjectBusySheet), showing the exact application name, process ID (PID), app icon, and open file path blocking the eject, with buttons to Quit Application, Retry Eject, or Force Eject.

10. Storage Health, Bit-Rot Verification, Duplicates, and Space Map#

Dashboard health alerts and "What if this drive dies?"#

Press Command-1 to open the Dashboard, your archive's mission control:

  • Summary Cards: Total cataloged devices (and how many are online right now), total cataloged files and folders, total storage footprint, and Single Copies (the count and byte total of files that exist on only one device).
  • Needs Attention Alerts: Automatically flags drives that have Not been scanned in 90+ days, Not been verified for bit rot in 6+ months (or never), Not been seen for more than 6 months, or Only ever connected once (configurable in Settings → General).
  • What if this drive dies? Simulator: Click Simulate beside any drive to see how many files and gigabytes have zero backup on any other cataloged drive, broken down by top-level folder, with a one-click button to queue those unique files onto your Wanted List.

Bit-Rot and Integrity Verification (Verify Integrity)#

Flash media (SSDs, USB sticks, SD cards) left unpowered for months and aging magnetic or optical disks can suffer silent data corruption (bit rot) - bytes flip on disk without changing the file's size or modification timestamp, so normal backup tools never notice the damage.

Catalogger includes a dedicated, read-only Integrity Verifier (IntegrityVerifier) that re-reads files from a mounted drive, recomputes their cryptographic hash (sha256: or partial p256: matching the stored baseline), and classifies every file into one of seven states:

Verification Status Meaning
Verified OK On-disk bytes match the cataloged sha256: or p256: fingerprint, and size/modification date are unchanged.
Bit Rot (Silent Corruption) Critical: File size and modification timestamp on disk are unchanged from the scan, but the content hash no longer matches! Catalogger immediately searches your other drives for a healthy intact copy (healthyCopyDevices).
Modified Since Scan File size or modification timestamp changed legitimately since the last scan; rescan the drive to update its baseline.
Missing on Disk The file was present in the catalog but no longer exists at that path on the mounted drive.
Unreadable (I/O Error) macOS returned a read error while streaming the file from the disk (often an early warning of failing sectors).
No Hash Baseline The file was originally cataloged with a Quick scan (no hash stored); run a Standard or Deep rescan to establish a baseline.
Skipped (Budget Limit) Not yet checked because the run reached your --max-files or --max-gb budget limit (resume later with --after).

How to verify a connected drive in the Mac app:

  1. Connect the drive to your Mac and open its Device Browser in the sidebar.
  2. Click Get Info in the header and scroll to Verify Integrity (Bit Rot Check).
  3. Click Verify Connected Drive. Catalogger streams and verifies the files in read-only mode, displays a live summary badge, lists any damaged or missing files with the names of other drives holding healthy copies, and records the timestamp and summary in the device's Last verified field.

Finding cross-drive duplicates (Command-5)#

Click Duplicates (Command-5) in the sidebar to inspect groups of files that share identical content across your catalog:

  • Filter duplicate groups by All duplicates or Across different devices only.
  • Sort by Wasted Space (size multiplied by extra copies), File Size, or Copy Count.
  • Expand any group to see which drives are online or offline and add specific copies to your Wanted List.

Space Map Treemap and Drive Retirement Advisor (Command-6)#

Click Space Map (Command-6) in the sidebar to see a proportional treemap of where your bytes live on any online or offline drive:

The Space Map treemap visualizing folder sizes on an archive drive alongside the Pack into other drives consolidation advisor button
The Space Map treemap visualizing folder sizes on an archive drive alongside the Pack into other drives consolidation advisor button
  • Drill down & up: Click any folder rectangle (RAW Originals, Family Video Reel, Lightroom Previews, etc.) to zoom into its subfolders, or click Up / any breadcrumb item to zoom back out.
  • Pack into other drives...: Click Pack into other drives... in the top-right corner of Space Map to run Catalogger's read-only first-fit decreasing packing planner (DrivePacking). It shows how the current drive's top-level folders could fit into the free space of your other cataloged drives - without ever moving or writing a single byte on disk.
  • Drive Retirement & Consolidation Advisor: Want to retire an aging spinning hard drive? Open that drive's Get Info sheet and scroll to Drive Retirement & Consolidation Advisor, then click Analyze Retirement Plan. Catalogger calculates:
    1. How many files and bytes on this drive are Already Redundant (already backed up by hash on your other drives - zero copying needed!).
    2. How many files and bytes are Unique to this drive and must be migrated before you retire it.
    3. Which destination drives have enough free space to absorb those unique folders, plus a one-click Queue All Unique Files to Wanted List button.

11. Backups, Restore, Export, and the iOS Companion App#

Automatic and manual catalog backups#

Your catalog lives inside ~/Library/Application Support/Catalogger (or a custom folder you choose in Settings → General). It consists of two databases (Catalog.store for SwiftData device records and CatalogIndex.sqlite for the FTS5/vector/item index) plus a Thumbnails folder.

Catalogger's BackupEngine creates consistent, hot snapshots while the app is running:

  1. It runs VACUUM INTO on both SQLite databases so WAL transactions are cleanly checkpointed into standalone files.
  2. It packages the databases (and optionally thumbnails) and compresses the bundle using Apple's fast native LZFSE compressor (.catalogbackup / .lzfse), recording a SHA-256 manifest (backup-manifest.json).
  3. It verifies the backup immediately after creation and prunes older backups according to your retention count in Settings → Backup (default: daily backups, keeping the last 10).

To restore a backup: Open Settings → Backup (or choose File → Restore Catalog from Backup...) and pick a backup. Catalogger validates the archive and stages it inside .pending-restore; on the very next launch, BackupEngine.applyPendingRestore atomically swaps the restored catalog into place before any database connection opens.

Exporting your catalog (CSV, JSON, HTML, Plain Text)#

Press Shift-Command-E (or choose File → Export Catalog..., or click Export in the Results toolbar) to export either your entire catalog, a single device, or your current search results:

  • CSV: Spreadsheet-friendly table with path, size, dates, kind, device, location, and SHA-256 hash.
  • JSON: Structured machine-readable records with metadata dictionaries.
  • Standalone HTML: A self-contained, searchable web page you can share with clients or store alongside an archive box.
  • Plain Text (tree): Indented directory listing suitable for printing or diffing.

Using Catalogger for iOS (iPhone and iPad)#

Catalogger for iOS (CataloggerIOS, iOS 17.0+) is a native iPhone and iPad companion app (not a Mac Catalyst port) that lets you carry your entire drive catalog in your pocket when you are in a storage room, studio closet, or on location:

  1. On your Mac, create a catalog backup (File → Back Up Catalog Now) or locate CatalogIndex.sqlite / .lzfse in Settings → Backup → Reveal in Finder.
  2. Send the file to your iPhone or iPad via AirDrop, iCloud Drive, or the Files app.
  3. Open Catalogger on your iPhone or iPad, tap Import Catalog, and select the file.
  4. Browse all devices, search with the full operator syntax or plain English, and inspect file metadata and shelf locations completely offline.

12. Terminal CLI, MCP Server, and Automation#

The Direct edition includes the catalogger command-line tool for scripting, cron jobs, search regression testing, and connecting AI assistants over the Model Context Protocol (MCP).

CLI command reference#

Run catalogger from Terminal (by default it opens your live catalog in ~/Library/Application Support/Catalogger in read-only mode, or pass --catalog <folder>):

# Search with any plain-English or operator query
catalogger search "photos from 2019 on Photo Archive" --limit 25
catalogger search "kind:video size:>2GB singlecopy:yes" --json

# Ask where a file or topic lives in plain English
catalogger where "the signed studio lease from 2021"

# List all cataloged drives, shelf locations, and last-verified status
catalogger devices --json

# Simulate single-copy loss risk if a drive fails
catalogger risk "Photo Archive 2019"

# Build a greedy shelf retrieval plan for item IDs
catalogger plan 1042,1045,2091

# Find all byte-identical copies of an item ID or hash
catalogger copies 1042

# Explain how a plain-English query is rewritten into SQL and operators
catalogger explain "large raw photos from last summer not on NAS"

# Verify a mounted drive for silent bit rot (with optional byte budget & resume cursor)
catalogger verify "Photo Archive 2019" "/Volumes/Photo Archive 2019" --max-gb 100 --after 0

# Run the search evaluation benchmark (or a custom JSON test suite)
catalogger eval --verbose
catalogger eval my-queries.json --json

Connecting AI Assistants via Model Context Protocol (catalogger mcp)#

Catalogger includes a built-in MCP server over standard input/output (stdio JSON-RPC 2.0) so AI tools like Claude Desktop, Cursor, or custom local agents can answer questions about your drives without ever touching your files.

Add this entry to your MCP client configuration (for example, ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "catalogger": {
      "command": "/Applications/Catalogger.app/Contents/MacOS/catalogger",
      "args": ["mcp"]
    }
  }
}

The MCP server exposes five read-only tools:

  • catalog_search: Runs any plain-English or operator search and returns matching items with device names and shelf locations.
  • catalog_devices: Lists every cataloged device, capacity, online status, and physical shelf location.
  • catalog_device_risk: Computes the single-copy failure risk report for a specified drive.
  • catalog_retrieval_plan: Computes the minimum set of drives to plug in to retrieve a list of item IDs.
  • catalog_copies: Finds all byte-identical copies of an item across your archive.

13. Preferences and Personalization Reference#

Press Command-, (Catalogger → Settings...) to open the nine-tab Settings window:

Settings Tab Key Controls and Defaults
General Open Catalogger at login, Show Catalogger in the menu bar (default: On), Keep running in the menu bar when the window is closed, Hide the Dock icon while no window is open, Dashboard warnings (Warn when a device was not seen for 6 months, Warn when a device was not scanned for 90 days), and Catalog Folder (Move Catalog..., Reveal in Finder, Compact Database).
Scanning Default scan profile (Quick, Standard, Deep, Custom), Keep a history of files removed between scans (default: On), Automatic scanning when known drives connect, Minimum hours between automatic scans (24h), Scheduled rescan (Off, Hourly, Daily, Weekly), Power & Quiet Hours (Pause on battery, Pause in Low Power Mode, quiet hour window), and Global exclude patterns (.DS_Store, .Spotlight-V100, .Trashes, etc.).
Devices Per-device list showing each drive's current rule mode (Global, Custom, or Ignored) and a ** forgetting / privacy** control to strip captured signals (OCR, Vision labels, GPS places, Transcripts, or Meaning vectors) from any device without deleting its file tree.
Display Visible Table Columns (Name is always shown; toggle Kind, Size, Date Modified, Date Created, Device, Location, Path, Dimensions, Duration, Hash), Show file extensions (default: On), Show hidden dot-files (default: Off), Use binary byte units (KiB/MiB/GiB instead of KB/MB/GB), Default Inspector visibility, and Reset Display Preferences.
Metadata Configure thumbnail resolution (160 px to 512 px, default 320 px), maximum file size for full-text indexing (64 MB), archive listing depth, Vision image classification, OCR text recognition, and On-device speech transcription toggle.
Search Show why each result matched, Clear History, Compute meaning vectors for new devices by default, Storage limit (500 MB default), and (in the Direct edition) Optional stronger model (EmbeddingGemma 2) download, SHA-256 verification, and helper path status.
Notifications Toggle notifications for Scan completed, Scan failed, Wanted drive connected, Backup completed, and Stale drive reminders.
Backup Back up automatically (Daily / Weekly), Keep last N backups (10), Include thumbnails in backups, Backup folder location, Back Up Now, and Restore... from any listed snapshot.
Advanced Command-K global shortcut (Control-Option-Space) toggle, Verify Catalog Database Integrity (PRAGMA integrity_check), Rebuild Full-Text Search Index, and sample data controls.

14. Keyboard Shortcuts and Accessibility#

Complete keyboard shortcut table#

Action Shortcut Menu Location
Add Folder to Catalog... Shift-Command-O File → Add Folder to Catalog...
Scan Connected Drives Shift-Command-R File → Scan Connected Drives
Eject Selected Device Command-E File → Eject Selected Device
Export Catalog... Shift-Command-E File → Export Catalog...
Find in Catalog Command-F Edit → Find in Catalog
Search Within Results Shift-Command-F Edit → Search Within Results
Advanced Search Builder... Option-Command-F Edit → Advanced Search...
Command Palette... Command-K Edit → Command Palette...
Global Command Palette (any app, Direct build) Control-Option-Space Settings → Advanced
Quick Look Selected Item Space Results / Device Browser
Show / Hide Inspector Option-Command-I View → Show/Hide Inspector
Show / Hide Filter Bar Option-Command-L View → Show/Hide Filter Bar
Go to Dashboard Command-1 View → Dashboard
Go to All Items (Search) Command-2 View → All Items
Go to Wanted List Command-3 View → Wanted List
Go to Recents Command-4 View → Recents
Go to Duplicates Command-5 View → Duplicates
Go to Space Map Command-6 View → Space Map
Open Settings... Command-, Catalogger → Settings...
Search Syntax Reference Shift-Command-/ Help → Search Syntax

Accessibility and VoiceOver support#

  • Every status indicator (Online/Offline device dots, scan progress badges, and capacity donut charts) exposes a descriptive VoiceOver accessibility label (such as "Online", "Offline", or "Used 700 GB of 2 TB").
  • All primary workflows - searching, filtering, browsing folders, inspecting metadata, queuing Wanted List items, and running commands via Command-K - can be operated entirely from the keyboard without a mouse.
  • Respects macOS Increase Contrast, Reduce Motion, and Dynamic Type / Larger Text settings.

15. Purchasing, Editions, and Licensing#

  • Official store: Check the Plum Amazing Store for DiskCataloger availability.
  • Pre-release: The app is in pre-release review. Purchase links, pricing, and trial details will be available when the app is released.
  • Choosing between Direct and Mac App Store:
    • Choose the Direct edition from plumamazing.com if you want automatic mounting of unmounted disk images (.dmg/.iso), lsof open-file process inspection when a drive refuses to eject, the global Control-Option-Space hotkey, the catalogger Terminal CLI and MCP server, or optional EmbeddingGemma 2 local GGUF meaning search.
    • Choose the Mac App Store edition if you prefer App Store purchase management, family sharing, and strict macOS App Sandbox isolation with security-scoped volume bookmarks.
  • Third-party model notice (Direct edition only): The optional EmbeddingGemma 2 weights are never bundled inside Catalogger. If you choose to download them in Settings → Search, they are fetched directly from Hugging Face (ggml-org/embeddinggemma-2-GGUF) for local use on your Mac under the Google Gemma Terms of Use.

16. Updates, Migration, and Privacy#

Checking your build and schema migration safety#

  • Choose Catalogger → About Catalogger to check your version and build number (1.0 (1)).
  • Catalogger stores its SQLite schema version in PRAGMA user_version (currently schema v5). When you update Catalogger to a newer version, CatalogStore.migrate automatically upgrades earlier catalog schemas (v1 through v4 -> v5) in place without requiring you to rescan your drives, while automatic pre-migration backups in Settings → Backup protect your existing catalog.

Privacy architecture#

  • 100% local processing: Every filename, document snippet, OCR string, Vision label, GPS place lookup, spoken word transcript, and meaning vector is computed and stored locally on your Mac. Catalogger contains zero analytics SDKs, zero cloud telemetry, and never transmits your catalog or search queries over the network.
  • Selective signal forgetting: If you ever want to remove derived AI/metadata signals (such as OCR text, transcripts, GPS places, Vision labels, or meaning vectors) from a cataloged drive without losing its file and folder tree, open Settings → Devices, select the drive, and use Forget Captured Signals....

17. Troubleshooting, Known Limits, and Support#

Common symptoms and fast fixes#

Symptom Cause Solution
Drive shows "Permission needed" or scan finishes with 0 files macOS Removable Volumes or Sandbox bookmark access has not been granted for that volume. In the Mac App Store edition, click Grant Access... on the device banner and select the volume root in the open panel. In the Direct edition, check System Settings → Privacy & Security → Files and Folders → Catalogger (or grant Full Disk Access for Time Machine disks).
Eject says the drive is in use Finder Quick Look, Spotlight (mds_stores), or another app still has an open file handle on the volume. In the Direct edition, read the Drive Is Busy sheet to see the exact app and file path, then click Quit Application and Retry Eject.
Verify Integrity reports "No Hash Baseline" on files Those files were originally scanned with the Quick profile, which skips hashing for maximum speed. Reconnect the drive and run a Standard scan (for fast partial p256: hashes) or Deep scan (for full sha256: hashes) to establish a verification baseline.
Plain-English search rewrote a query you wanted searched literally Plain-English interpretation matched a date, kind, or location word (like may or photos). Wrap the word in quotes ("may"), click the × on the interpreted operator chip above the results, or turn off Understand plain-English queries in the search options popover.
EmbeddingGemma 2 says "Helper not installed" (Direct edition) The local llama-server or llama-embedding binary from llama.cpp was not found in /opt/homebrew/bin or Application Support. Run scripts/setup-llama-helper.sh or brew install llama.cpp in Terminal, then click Recheck Helper in Settings → Search.
Catalog database feels large after deleting many sample or old devices SQLite retains freed pages for reuse until compacted. Open Settings → General and click Compact Database (VACUUM), or open Settings → Advanced and click Rebuild Full-Text Search Index.

Known limits#

  • Partial hash (p256:) vs. Full SHA-256 (sha256:): The Standard scan profile computes a fast partial hash (first 1 MB + last 1 MB + file size) so multi-terabyte drives finish scanning quickly. Partial hashes catch most corruption and identify duplicate media files rapidly, but if silent bit rot occurs in the middle of a multi-gigabyte video file without affecting its first or last megabyte, only a Deep scan baseline (sha256:) is guaranteed to detect it.
  • Encrypted drives and unmounted FileVault volumes: Catalogger can only scan volumes after you unlock and mount them in macOS Finder or Disk Utility. Catalogger never prompts for or stores volume encryption passwords.
  • Spoken transcripts require on-device Speech Recognition models: The first time you enable speech transcription, macOS may download Apple's on-device speech recognition assets in the background.

Getting help and contacting Plum Amazing Support#

If you run into a question not answered here, or want to suggest an improvement:

  1. Check Settings → Advanced → Verify Catalog Database Integrity to confirm your local SQLite database is healthy.
  2. Note your macOS version, your Catalogger edition (Direct or Mac App Store), and the version/build shown in Catalogger → About Catalogger.
  3. Reach out to the team at Plum Amazing Support.

Revision history#

Date Manual version Changes
2026-11-12 1.0 Complete Plum Amazing human user manual for Catalogger 1.0: added Quick Start lesson, workspace anatomy, edition comparison (Direct, Mac App Store, iOS 17+ companion, and CLI/MCP), bit-rot integrity verification (Verify Integrity and catalogger verify), hybrid plain-English and meaning search (NaturalLanguage and optional EmbeddingGemma 2), Deep Signal Inspector (places, Vision labels, OCR text, spoken transcripts, perceptual dHash visually similar images), Wanted List shelf pull checklists, Space Map and Drive Retirement Advisor, deterministic search evaluation (catalogger eval), and verified Mac screenshots.