git404hub

what is codex-mac-file-detective fr?

kappaemme-git/codex-mac-file-detective — explained in plain English

Analysis updated 2026-05-18

1PythonAudience · generalComplexity · 2/5LicenseSetup · easy

tl;dr

A Mac-only tool that finds files by describing what you remember about them, content, date, type, or appearance, instead of exact filenames, then returns ranked matches with explanations.

vibe map

mindmap
  root((repo))
    What it does
      Search by description
      Ranked match list
      Explains selections
    How it works
      Reads file metadata
      Searches document text
      Uses Quick Look previews
    Privacy
      Runs on machine only
      Skips sensitive folders
      No uploads or edits
    Outputs
      JSON data file
      Markdown report
      Preview image folder
    Requirements
      macOS only
      Spotlight and Quick Look
    Install
      One terminal command
      Or manual skill copy

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Find a screenshot by describing its colors or layout instead of the filename.

VIBE 2

Locate a PDF invoice by recalling the sender and approximate download date.

VIBE 3

Track down a document by its content, author, or the app that created it.

what's the stack?

PythonmacOS SpotlightmacOS Quick Look

how it stacks up fr

kappaemme-git/codex-mac-file-detective0xustaz/streamgatea-bissell/unleash-lite
Stars111
LanguagePythonPythonPython
Setup difficultyeasyhardhard
Complexity2/54/54/5
Audiencegeneraldeveloperresearcher

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · easy time til it works · 5min

Requires macOS, installed with a single terminal command followed by a Codex restart.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

in plain english

Codex Mac File Detective is a tool for macOS that helps you find files on your Mac when you cannot remember the exact name or folder. Instead of searching by filename, you describe what you remember about the file: its content, approximate date, file type, the application that created it, or visual details like colors and logos. The tool then returns a short ranked list of likely matches, each with an explanation of why it was selected. You install it by running a single command in your terminal, then restart Codex. Once installed, you can ask it things like "find the screenshot with a green pricing table that I saved last month" or "find the PDF invoice from the design supplier I downloaded around March." The tool searches through filenames, folder names, document text, metadata, creation and modification dates, file types, and author information. It can also use macOS Quick Look to check visual previews for clues that match your description. When it finishes searching, the tool saves results in three places: a JSON file with structured data, a folder of preview images, and a Markdown report that opens directly in Codex. The report includes clickable file paths, excerpts of matched content, preview images, and notes about what was searched and any limitations encountered. Privacy is a central focus. The tool runs entirely on your machine and only reads files. It does not upload, move, rename, delete, edit, or permanently index anything. It also avoids sensitive locations by default, including hidden folders, credential stores, private keys, browser profiles, mail stores, caches, and application bundles. You can also install it manually by cloning the repository and copying the skill folder into your Codex skills directory. The project is licensed under MIT and requires macOS to function, since it relies on Spotlight and Quick Look features built into the operating system.

prompts (copy fr)

prompt 1
I'm on macOS and I installed Codex Mac File Detective. Find the screenshot with a green pricing table that I saved last month.
prompt 2
I installed this tool. Find the PDF invoice from the design supplier I downloaded around March.
prompt 3
I can't remember the filename but I know it was a Pages document about project timelines created in February. Use Codex Mac File Detective to find it.
prompt 4
Search my Mac for a text file containing notes about a blue logo concept, likely edited within the last two weeks.

Frequently asked questions

what is codex-mac-file-detective fr?

A Mac-only tool that finds files by describing what you remember about them, content, date, type, or appearance, instead of exact filenames, then returns ranked matches with explanations.

What language is codex-mac-file-detective written in?

Mainly Python. The stack also includes Python, macOS Spotlight, macOS Quick Look.

What license does codex-mac-file-detective use?

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

How hard is codex-mac-file-detective to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is codex-mac-file-detective for?

Mainly general.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.