mac-file-detective

name

mac-file-detective

description

Find forgotten or misplaced files on macOS from vague natural-language clues by combining scoped Spotlight search, filenames, document text, dates, file types, creator metadata, and visual inspection of local previews. Use when Codex is asked to find a screenshot, image, PDF, document, spreadsheet, presentation, code file, download, invoice, note, or other local file without knowing its exact name or location. Keep searches local and read-only, explain why each candidate matches, avoid sensitive system locations by default, and never move, rename, delete, upload, or open a file automatically.

Mac File Detective

Turn incomplete memories into a small, evidence-ranked candidate list. Search locally and read-only. Do not claim a file is found merely because one keyword appears in its name.

Protect privacy and files

• Treat invocation as permission to search only, never to move, rename, delete, edit, upload, or index files permanently.
• Search only the scope stated by the user. If no scope is given, use existing Desktop, Documents, Downloads, and Pictures folders under the user's home directory.
• State the search roots before searching. Never silently broaden to the whole home directory or disk.
• Exclude Library, Mail stores, browser profiles, Keychains, .ssh, .gnupg, .Trash, hidden folders, dependency trees, caches, Git internals, and application bundles by default.
• Do not read secret files such as .env, private keys, credential stores, auth databases, or password exports.
• Keep all processing on the Mac. Do not upload candidates or snippets to a network service.
• Do not open a candidate automatically. Provide a clickable path and let the user choose. Never execute applications, installers, scripts, archives, or disk images as part of search.
• Write only search artifacts under outputs/mac-file-detective/ or another user-approved output directory.

Reconstruct the memory

Extract useful clues from the request:

• remembered words or phrases
• likely kind or extension
• approximate creation or modification date
• likely folder or application
• visual details such as dominant color, logo, layout, people, or objects
• surrounding event, project, client, or purpose

Do not force the user to know technical metadata. Convert phrases such as “around last March,” “probably a PDF,” or “a screenshot with a green pricing table” into structured search arguments. If a clue is ambiguous, search broadly first and refine from the evidence.

Read references/search-playbook.md when translating date, application, visual, or file-kind clues.

Run the search funnel

1. Create a broad local candidate set

Run the bundled searcher from the skill directory with explicit absolute roots:

python3 scripts/search_files.py \
  "green pricing table from last month" \
  outputs/mac-file-detective/search.json \
  --root "$HOME/Desktop" \
  --root "$HOME/Documents" \
  --root "$HOME/Downloads" \
  --kind image \
  --after 2026-06-01 \
  --before 2026-07-01

Add --term for essential concepts, --phrase for remembered exact text, and --app when the creating application is known. Omit unavailable default roots rather than treating them as errors.

The script uses Spotlight when available and a bounded filesystem/content fallback. It does not create a persistent index. Prefer the default limits; explain before expanding beyond 25,000 files or a large user-selected root.

2. Refine by evidence

• Inspect filename, path, extracted text, timestamps, kind, size, creator metadata, and match coverage.
• Search a narrower root or date range when the candidate list is noisy.
• Search synonyms or project-specific terms when the remembered wording may differ from the file.
• Treat Spotlight absence as missing evidence, not proof that the file does not exist.
• For images and visually described documents, create local Quick Look previews:

python3 scripts/create_previews.py \
  outputs/mac-file-detective/search.json \
  outputs/mac-file-detective/previews \
  outputs/mac-file-detective/previews.json \
  --limit 12

Use the local image-viewing capability to inspect only the top previews. Do not infer visual details from filenames. Record confirmed or rejected visual candidates in a review JSON following references/evidence-schema.md.

3. Generate the native report

python3 scripts/generate_report.py \
  outputs/mac-file-detective/search.json \
  outputs/mac-file-detective/FILE-DETECTIVE-REPORT.md \
  --previews outputs/mac-file-detective/previews.json \
  --review outputs/mac-file-detective/review.json

Omit unavailable optional arguments. Open or link FILE-DETECTIVE-REPORT.md directly in Codex. The report must include scope, search clues, ranked candidates, match reasons, sanitized snippets, dates, and local paths.

Use honest result labels

• STRONG MATCH — Multiple independent clues match, or visual inspection confirms the remembered content.
• LIKELY MATCH — Several clues match but one important detail is unverified.
• POSSIBLE MATCH — Partial evidence; show it only when stronger candidates are absent or as a short fallback list.
• REJECTED — Manual inspection contradicts the remembered clue.
• NO MATCH — No credible candidate remains in the searched scope.

Never describe the top-ranked candidate as confirmed solely because it has the highest score. Explain missing clues and offer one targeted refinement when evidence is weak.

Handle opening and follow-up actions safely

• Provide the absolute clickable path for each top candidate.
• Open or Quick Look a candidate only after the user selects it.
• Never execute a candidate or automatically open executable file types.
• Treat organizing, moving, renaming, or deleting found files as a separate task requiring exact paths and explicit approval.
• If the file is not found, report the exact roots, date window, kinds, exclusions, and limits searched. Suggest the next most useful scope or clue instead of claiming the file is gone.

Hand off

Lead with STRONG MATCH, LIKELY MATCH, POSSIBLE MATCH, or NO MATCH, then provide:

1. The best candidate and why it matches
2. Up to five alternatives
3. Search scope and filters
4. Unverified clues or limitations
5. A link to outputs/mac-file-detective/FILE-DETECTIVE-REPORT.md

State clearly that no files were modified.