Auto Filename Helper is a native macOS companion that validates and applies filename suggestions supplied by a Shortcut.
A download called document (3).pdf says little about its contents. A meaningful name makes later search easier, but an automated suggestion still needs checking: it may be too vague, contain an unsafe character, or collide with another file.
Auto Filename Helper separates those jobs. The Shortcut derives the suggested name; the native app checks the request and handles the actual rename. The helper itself is not an AI model and does not inspect a document to invent its title.
Build the helper and connect the Shortcut
The project currently provides source and an included Auto Filename.shortcut, rather than a packaged GitHub Release. Building requires macOS 13 or later and Xcode Command Line Tools.
Download the repository, inspect its installation script, then run:
|
|
The script installs ~/Applications/AutoFilenameHelper.app. Import Auto Filename.shortcut into Shortcuts and replace its execution step with the repository’s shortcut_shell_replacement.sh, as the README describes.
This connection matters. Merely opening the app does not create a filename suggestion; the Shortcut must send the selected path and analysis result to the helper.
Think of it as a handoff with a checkpoint: select a file such as document (3).pdf in Finder, let the Shortcut propose a descriptive name, and let the helper check the path, extension, and possible conflict. A proposal such as “project meeting notes.pdf” is only an example; the real name depends on what the Shortcut derives from your file.
Try one file before a batch
Start with a disposable copy of a supported file. Run the Shortcut from Finder, inspect the suggested filename and reason, and check the result in Finder.
The helper receives fields including the path, suggestion, confidence, and reason. It validates the request, preserves the original extension by default, and uses moves that do not overwrite an existing file. It rejects unsafe or hidden names, symlinks, unsupported file types, and unchanged names.
Those checks protect the rename operation; they do not prove that the proposed title describes the contents accurately. Keep names factual and easy to recognize later.
Decide when confirmation is required
The app’s settings include a rename threshold, extension handling, conflict behaviour, appearance, and English/Chinese interface choices. Ambiguous names, low-confidence suggestions, executables, and disabled automatic renaming can trigger confirmation.
Quick Look, Reveal in Finder, and Copy Path help inspect the original before accepting. For files with uncertain contents, the right answer may simply be to keep the existing name until you have checked it.
On the first run, use a copy and check three things: whether the proposed name really describes the content, whether .pdf or another extension stays intact, and whether the folder already contains that name. Even a high confidence value is a reason to inspect the file, not a substitute for opening it.
A confidence value is supplied by the workflow, not an independent certification from the helper. Moving the threshold should be a deliberate convenience choice, especially when filenames influence your later search or filing rules.
Find the project folder before building
If you use Code → Download ZIP on GitHub, unzip the archive and locate the folder containing build_and_install.sh. That is the folder Terminal needs as its current directory. Type cd , drag the folder into Terminal, and press Return before running the build command. This also handles spaces in the path.
If the script reports missing Xcode Command Line Tools, run xcode-select --install, complete the system installer, then return to the project. The script rebuilds and replaces ~/Applications/AutoFilenameHelper.app. Keep a copy first if you have customized an existing installation. The source folder is useful for future updates, while the Shortcut should call the executable inside the installed app.
In the Shortcut editor, find the shell action that invokes the helper and preserve the preceding analysis actions. The supplied replacement script handles the handoff; it does not create a missing analysis workflow. If you choose a different app location, update that invocation too. Otherwise a suggested name may exist while the Shortcut cannot find the program that applies it.
Choose a naming convention you can keep using
Think about the words you will search for later. For meeting documents, a project, topic, and a date actually present in the document can be useful. For invoices, the supplier or invoice number may matter more. A polished title that invents a year, person, or version is harder to trust than a modest, accurate description.
Renaming document (3).pdf to quarterly budget discussion.pdf helps if “budget” is what you will remember. If that name already exists, inspect both documents rather than relying on a numbered suffix to explain their relationship. Keeping the extension is sensible: changing .pdf to .docx does not convert a PDF into a Word document.
Try several copies before choosing a threshold: a clearly named file, an ambiguous one, and a case that conflicts with an existing name. Watch which suggestions are accepted, questioned, or rejected. This gives the threshold a practical meaning in your own workflow instead of treating it as an abstract accuracy score.
When the Shortcut runs but the name stays unchanged
Follow the chain: selected file, generated suggestion, handoff, then rename. If only Settings opens, check whether the Shortcut is passing the payload to standard input. If a confirmation window appears, it may still be waiting for your decision. If the helper reports an unchanged name or unsupported type, resolve that message before rerunning the same input.
Always verify the path. A similarly named document in Downloads, on the Desktop, and in a cloud folder can be three separate files. Use Reveal in Finder to locate the intended original, then check that folder after the rename. If a script or project configuration refers to the old filename, account for those references before changing it.
Local renaming and upstream analysis are separate
The helper makes no network requests. The Shortcut is responsible for deriving the suggestion and may use an AI service depending on its actions and configuration.
Review that Shortcut before applying it to personal documents. “The rename happens locally” does not automatically mean the whole analysis workflow stays on the Mac.
For an explanation of an unfamiliar file before renaming it, see What File Is This. To find the renamed item later, MacHunt provides local filename search. Setup details remain in the project README.