kappaemme-git/codex-mac-file-detective

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.