A file renaming tool for humans

1 Feb 2026

I deal with a lot of PDFs. Medical invoices, insurance correspondence, bank statements, tax documents—they all arrive with names like e134-a1cf-4b4b-af65-ccf83c5270cb.pdf or Document(3).pdf or, my personal favourite, scan.pdf. Every. Single. Time.

So I started renaming files to something like 2025-09-30-125.00-rahona-clinic.pdf. Now I know what it is without opening the thing - an invoice, with the date and amount right there in the name. I'm halfway to the spreadsheet already. And thanks to ISO date format, they sort nicely too.

I receive a lot of medical bills, and I have to record every one on a spreadsheet. For a while I let them pile up, which eventually turns into a brutal day of opening each PDF, reading the date, amount, provider, adding it to the sheet, recording the filename. Mind-numbing stuff.

Then I thought: could AI automate this?

And the stars told me, yes Taḋg, it can be done.

I built smart-rename, and I've released it for anyone who might find it useful.

What it does

It's a command-line tool that reads your files and proposes a descriptive, human-readable filename based on actual content. By default it uses Ollama, running entirely on your machine. No API keys, no cloud, no data leaving your computer.

You can configure it to use OpenAI or Anthropic if you prefer—some of the lighter models are fast and cheap. Of course, those services do send your data to the cloud, so be aware if you go that route.

In practice

$ smart-rename 176991171023732.pdf
Trying Ollama (qwen2.5:7b)...
✓ Got response from Ollama
📎 176991171023732.pdf →
🆕 2026-01-15-54.97-svph-cardiac-clinic.pdf (y/N): y
✓ Renamed

The tool has read the PDF, found the date, the amount (€54.97), and worked out it's an outpatient consultation at St. Vincent's Private Hospital. It's using the abbreviation svph because I've given it a list of my preferred abbreviations, but that's optional—it works grand without any configuration.

It doesn't have to be an invoice

$ smart-rename scan(3).pdf
Trying Ollama (qwen2.5:7b)...
✓ Got response from Ollama
📎 scan(3).pdf 
→ acme-publication-offer.pdf (y/N): y
✓ Renamed

Run it on a folder of PDFs with smart-rename *.pdf, or add -y to auto-accept if you trust it.

Naming conventions

Opinionated but practical:

Invoices and receipts: =YYYY-MM-DD-amount.cc-description.ext=—date first for natural sorting, amount with two decimal places, short description.
Regular documents: =descriptive-name-YYYY-MM.ext=—description with year and month appended.
Everything: lowercase, hyphen-separated, no spaces or special characters.

The prompt that drives this lives in a config file you can edit to taste.

Supported files

PDF, TXT, MD, HTML, CSV, JSON, XML, SRT, VTT, SUB, and most plaintext source code. Image analysis and Office documents are on the roadmap.

Install

macOS with Homebrew:

brew install tigger04/tap/smart-rename

NixOS with flakes:

nix run github:tigger04/smart-rename

First run downloads the Ollama model (about 4GB). Runs fast on any Mac with 8GB RAM or more.

Full documentation and source: github.com/tigger04/smart-rename