# Renamo > Local invoice and receipt renaming for macOS This document contains the full content of all documentation pages for AI consumption. --- ## Custom fields **URL:** https://docs.renamo.app/docs/custom-fields **Description:** Teach Renamo to extract extra values for your filenames Custom fields let you define your own filename tokens. Renamo sends their names and descriptions to the local extraction model alongside the built-in fields. ## Add a custom field You can add fields from either place: - The template field menu: choose **Custom...** - **Settings → Custom Fields → Add Field...** Each field has: | Field | Meaning | |---|---| | Name | The token name shown in the filename template | | Description | Instructions for what the model should extract | ## Examples | Name | Description | |---|---| | Invoice Number | Extract the invoice number from the document. | | Country | Extract the billing country from the document. | | Category | Choose one of: Software, Travel, Office, Utilities, Meals. | | Project | Extract the project or client name if present. | ## Use custom fields in filenames After adding a field, insert it into the template just like a built-in token. ```text Date - Vendor - Invoice Number - CurrencyAmount ``` ## Reprocessing When you add or edit a custom field, Renamo reprocesses ready documents so the new value can be extracted. Documents that are already processing are queued again after their current run finishes. ## Removing fields Removing a custom field also removes it from the filename template and clears extracted values for that field from the current document list. --- ## Developer setup **URL:** https://docs.renamo.app/docs/developer-setup **Description:** Build, run, debug, and release the macOS app locally Renamo is a native macOS app generated with XcodeGen. ## Repository The app code lives in: ```sh ~/code/renamo-mac ``` Before starting a worktree session, sync with `origin/main`. ## Generate and run Use the included script: ```sh ./script/build_and_run.sh ``` The script: - Stops any running Renamo process - Runs `xcodegen generate` - Builds the Debug configuration - Opens the built app Modes: ```sh ./script/build_and_run.sh run ./script/build_and_run.sh --debug ./script/build_and_run.sh --logs ./script/build_and_run.sh --telemetry ./script/build_and_run.sh --verify ``` ## Dependencies The project uses: - Native macOS UI frameworks - PDFKit and Vision - Local model packages for document extraction - PostHog for analytics - Sparkle for app updates - A local `InlineTokenField` package for filename templates ## Release tooling The release script is: ```sh ./release.sh ``` Useful commands: ```sh ./release.sh preflight ./release.sh version ./release.sh bump patch ./release.sh release ``` Releases publish DMGs and `appcast.xml` to the `renamo-updates` R2 bucket behind `https://download.renamo.app`. --- ## CSV export **URL:** https://docs.renamo.app/docs/export **Description:** Export document names and extracted fields Use **File → Export CSV...** or **⇧⌘E** to export the current document list. Renamo exports one row per document, including files that are queued, processing, ready, renamed, or failed. ## Columns The CSV includes: - `original_filename` - `proposed_filename` - `renamed_filename` - `current_filename` - `date` - `vendor` - `currency` - `amount` - `vat_percent` - `state` - `confidence` - `error` - `custom_` for every custom field ## When to export Export before renaming if you want an audit trail of proposed names. Export after renaming if you want the final renamed filenames included in `renamed_filename`. ## File format The export is UTF-8 CSV. Values containing commas, quotes, or line breaks are quoted and escaped. --- ## Filename feedback **URL:** https://docs.renamo.app/docs/feedback **Description:** Rate generated filenames and optionally share a file for debugging Renamo includes lightweight feedback controls in the toolbar when a document is selected. ## Rate a filename - Click the thumbs-up button when the generated filename is good. - Click the thumbs-down button when it needs improvement. Bad feedback opens a popover where you can describe what Renamo should have done differently. ## Optional file sharing When you give bad feedback for a PDF or image, the popover can include **Share with developer**. Uploads are limited to files no larger than 1GB. ## What is sent Feedback events include: - Rating - Original filename - Generated filename - Filename template - Extracted values - Your comment, if provided - Upload status and object key, if a file was shared --- ## Filename templates **URL:** https://docs.renamo.app/docs/filename-template **Description:** Build reusable names from extracted fields and fixed text The template field at the top of the sidebar controls how generated filenames are built. The default pattern is: ```text Date - Vendor - CurrencyAmount ``` For example: ```text 2026-05-07 - Apple - USD24.99.pdf ``` ## Built-in tokens | Token | Output | |---|---| | Date | Full date, usually `YYYY-MM-DD` | | Vendor | Issuer, vendor, or merchant | | Currency | Currency code such as `CHF`, `EUR`, `USD`, or `GBP` | | Amount | Final amount as a normalized number | | VAT% | VAT or tax percentage when found | | Year | Year from the extracted date | | Month | Month from the extracted date | ## Add tokens Use the menu on the right side of the template field to insert a built-in token or custom field. You can also type fixed text directly into the template. Spaces, separators, and words are preserved, then sanitized into a valid filename. ## Change the pattern Examples: ```text Year/Month style: Year - Month - Vendor - Amount ``` ```text Accounting style: Date - Vendor - VAT% - CurrencyAmount ``` ```text Project style: Project - Date - Vendor - Amount ``` ## Persistence Template changes are saved in macOS user defaults and reused the next time Renamo opens. --- ## Files and previews **URL:** https://docs.renamo.app/docs/files **Description:** Supported inputs, sample invoices, and document previews Renamo is optimized for invoices and receipts, but it works with any PDF or image that macOS can open. ## Supported files - **PDFs** are read with PDFKit. Renamo uses text embedded in the first pages when available. - **Images** are read with Vision OCR. Screenshots, scans, JPEGs, PNGs, and similar image formats can be added. - **Scanned PDFs** are rendered to an image for OCR when text extraction is incomplete. ## Sample invoices The empty state includes four bundled sample invoices. Clicking them copies the sample PDFs to a temporary folder and adds those copies to the list. Use samples when you want to try the whole workflow without finding your own invoices first. ## Preview controls The detail view shows the selected PDF or image. Use the titlebar controls to: - Zoom out - Fit to width - Zoom in ## Image-aware extraction For models that can inspect document images, Renamo uses both the document image and extracted text. This helps when OCR is incomplete or noisy. --- ## Welcome to Renamo **URL:** https://docs.renamo.app/docs **Description:** Rename invoices and receipts locally on your Mac **Renamo** is a macOS app for turning messy invoice and receipt filenames into consistent names. Add PDFs or images, let Renamo extract fields like vendor, date, currency, amount, VAT, and any custom fields you define, then rename everything in place. ## Why Renamo? - **Local by default.** Renamo extracts filenames on your Mac with the local intelligence level you choose in Settings. - **Built for invoices and receipts.** It looks for vendor, date, currency, amount, VAT, year, month, and custom fields. - **Batch-friendly.** Drop many PDFs or images, process two at a time, then rename every ready file with one action. - **Inspectable.** The optional inspector shows the original name, generated name, and every extracted value. - **Customizable.** Change the filename pattern or add your own extraction fields, such as invoice number, country, project, or category. --- ## Document inspector **URL:** https://docs.renamo.app/docs/inspector **Description:** See the generated name and every extracted field The inspector is an optional right-side panel for checking what Renamo extracted from the selected document. Open or close it with the titlebar **Inspector** button. ## Filenames The **Filenames** section shows: - Original filename - Generated filename If a generated filename is still pending, Renamo shows a skeleton placeholder instead of stale text. ## Extracted fields The **Extracted Fields** section shows: - Vendor - Date - Year - Month - Currency - Amount - VAT% - Custom fields Values are selectable, so you can copy them while reviewing a document. ## Missing values Missing values show as placeholders. A missing value usually means the document did not contain that field, OCR could not read it, or the selected model could not infer it confidently. --- ## Local AI models **URL:** https://docs.renamo.app/docs/models **Description:** Choose how Renamo extracts invoice and receipt fields Renamo extracts filenames locally. The active model is set in **Settings → Models** under the **Intelligence** picker. ## Intelligence levels | Level | Best for | |---|---| | Small | Very fast extraction when available on your Mac | | Medium | Recommended default for most PDFs, images, and languages | | Large | More capable extraction for harder documents | | X Large | Difficult documents on Macs with more memory | ## Recommended model The recommended level is **Medium**. It is the best starting point for most invoice and receipt collections. Renamo recommends about **12 GB** unified memory for Medium. Larger models need more memory and disk space. ## Downloads Downloaded models are stored in Renamo's app-managed model cache. Downloads can resume if interrupted. Settings shows progress while a download is running or resuming. ## If extraction is incomplete If a document is missing important fields, try a higher intelligence level or add a clearer [custom field](/docs/custom-fields). You can always edit the generated filename before renaming. --- ## Privacy and local processing **URL:** https://docs.renamo.app/docs/privacy **Description:** What stays on your Mac and what can leave it Renamo is designed around local document processing. ## Local extraction Renamo extracts text and fields on your Mac using: - Embedded text from PDFs - OCR for image files and scanned PDFs - The local intelligence level selected in Settings The selected model receives extracted text, the document name, custom field instructions, and, when supported, a rendered first-page image. ## Model downloads Downloaded models are stored in Renamo's app-managed model cache. ## Analytics Renamo records product analytics such as app open, files added, settings opened, model settings viewed, exports, renames, and feedback ratings. ## Sending feedback with PDFs or images You can choose to send us feedback so we can teach Renamo how to handle difficult files you encounter. Thank you! Documents are not uploaded during normal rename processing. When you leave **Share with developer** enabled, we will upload the file to our secure storage on Cloudflare (EU server). The file cannot be larger than 1GB. --- ## Quick start **URL:** https://docs.renamo.app/docs/quickstart **Description:** Set up Renamo and rename your first invoices ## Requirements - macOS 14 or later - Apple silicon recommended for larger local models - About 12 GB unified memory for the recommended Medium model - Enough free disk space for the selected local model ## Next steps --- ## Troubleshooting **URL:** https://docs.renamo.app/docs/troubleshooting **Description:** Fix common setup, model, and renaming issues ## The generated filename stays blank The document may still be queued or processing. If the placeholder never changes: - Check **Settings → Models** and make sure the selected model is downloaded. - Try Medium if another model is selected. - Use the inspector to see whether any fields were extracted. ## Model download failed Open **Settings → Models** and click download again. Renamo resumes partial downloads when possible. If the model still fails, check your network connection and make sure enough disk space is available. ## The wrong vendor was detected Renamo tries to use the issuer or merchant, not the billed-to customer. If a document repeatedly picks the wrong party: - Add a custom field with a stricter description. - Edit the generated filename directly for that file. - Submit bad filename feedback with a short explanation. ## Rename all is disabled At least one document must be in the **Ready** state and have a non-empty generated filename. ## The file was not renamed Renamo uses macOS file moves. A rename can fail if: - The file was moved or deleted after being added. - The folder is read-only. - Another app is locking the file. - The generated name is not valid after sanitization. The sidebar shows failed files with a warning icon, and the footer shows the last error. ## I want to start over Remove files from the list with **Delete** or **Backspace**, or quit and reopen Renamo. Debug builds also include **Debug → Complete Reset**. --- ## Rename workflow **URL:** https://docs.renamo.app/docs/workflow **Description:** Add files, review suggestions, and rename everything safely Renamo keeps the flow deliberately short: add documents, inspect the generated names, adjust anything that needs human judgment, then rename all ready files. ## Add PDFs or images You can add documents in three ways: - Drag files into the main Renamo window - Click the empty state in the sidebar - Use **File → Add PDFs or Images...** or **⌘O** Renamo accepts PDFs and image files supported by macOS. Duplicate file paths are ignored so the same file is not queued twice. ## Processing states Each row in the sidebar shows the original filename, generated filename, and current state. | State | Meaning | |---|---| | Queued | Waiting for a processing slot | | Processing | Renamo is extracting text and fields locally | | Ready | The generated filename can be renamed | | Renamed | The file was moved to the generated name | | Failed | macOS returned an error while renaming | Renamo processes up to two documents at once. ## Preview and edit Select a file to preview it in the detail area. PDFs and images support preview zoom controls in the titlebar: zoom out, fit width, and zoom in. The generated filename is editable before renaming. Editing only affects the selected file; it does not change the filename template. ## Remove a file from the list Select a row and press **Delete** or **Backspace**. This removes the item from Renamo's list only. It does not delete the file from disk. ## Rename all Click **Rename all** or press **⌘R**. Renamo renames each ready file in its original folder. --- ## Links - [Feedback](https://tally.so/r/PdvD9b)