kappaemme-git/codex-mac-file-detective — explained in plain English
Analysis updated 2026-05-18
Find a screenshot by describing its colors or layout instead of the filename.
Locate a PDF invoice by recalling the sender and approximate download date.
Track down a document by its content, author, or the app that created it.
| kappaemme-git/codex-mac-file-detective | 0xustaz/streamgate | a-bissell/unleash-lite | |
|---|---|---|---|
| Stars | 1 | 1 | 1 |
| Language | Python | Python | Python |
| Setup difficulty | easy | hard | hard |
| Complexity | 2/5 | 4/5 | 4/5 |
| Audience | general | developer | researcher |
Figures from each repo's GitHub metadata at analysis time.
Requires macOS, installed with a single terminal command followed by a Codex restart.
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.
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.
Mainly Python. The stack also includes Python, macOS Spotlight, macOS Quick Look.
Use freely for any purpose, including commercial use, as long as you keep the copyright notice.
Setup difficulty is rated easy, with roughly 5min to a first successful run.
Mainly general.
This repo across BitVibe Labs
double-check against the repo, no cap.