# 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 Fields control what Renamo extracts for filenames. You can adjust the descriptions for built-in fields and define your own custom filename tokens. Renamo uses your field names and descriptions during extraction, alongside the built-in fields. ## Edit built-in fields Open **Settings → Fields** to review the built-in extraction fields. Date, Vendor, Currency, Amount, VAT%, and VAT Amount can each use the default description or a custom description. Settings is organized into tabs, including **Account**, **Fields**, and **Models**. Use a custom description when your documents use unusual wording or when you want Renamo to prefer a specific value. ## Add a custom field You can add fields from either place: - The template field menu: choose **Custom...** - **Settings → 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 - Currency + Amount ``` ## 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 custom 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` - `vat_amount` - `state` - `confidence` - `error` - `custom_` for every custom field (using the custom field name from **Settings → Fields**) ## 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 - Currency + Amount ``` For example: ```text 2026-05-07 - Apple - USD24.99.pdf ``` In the default pattern, **Currency** is placed immediately before **Amount** (with no separator), so you get outputs like `USD24.99`. ## 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 formatted for your locale | | VAT% | VAT or tax percentage when found | | VAT Amount | VAT or tax amount formatted for your locale | | Year | Year from the extracted date | | Month | Month from the extracted date | | Index | The file's current list position, starting at `1` | | Counter | The file's current list position padded to four digits, such as `0001` | ## 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% - VAT Amount - Currency + Amount ``` ```text Project style: Project - Date - Vendor - Amount ``` ## Persistence Template changes are saved on your Mac 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.** Renamo uses embedded text when it is available, and falls back to text recognition when needed. - **Images.** Screenshots, scans, JPEGs, PNGs, and similar image formats can be added. - **Scanned PDFs.** When a PDF has no usable embedded text, Renamo can recognize text from the page images. ## 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 In **list view**, Renamo shows a built-in preview for the selected PDF or image. In **table view**, preview happens in Quick Look. Press **Space** or double-click a row to open it. Use the titlebar controls to: - Zoom out - Fit to width - Zoom in ## Image-aware extraction Higher intelligence levels can use both the document image and extracted text. This helps when text recognition 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 Small by default when available, or 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:** Review and correct every extracted field The inspector is an optional right-side panel for checking and correcting 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 editable values for: - Vendor - Date - Year - Month - Currency - Amount - VAT% - VAT Amount - Custom fields Hover over a value to reveal the text field, then type the correction. Renamo immediately updates the generated filename for the selected document when that field is used by the filename template. You can correct the full date, or adjust the derived year and month fields directly. Editing a custom field works the same way as editing a built-in field. ## Missing values Values that are still pending show as placeholders. After extraction finishes, an empty field means the document did not contain that field, OCR could not read it, or the selected model could not infer it confidently. You can type into an empty field if you know the correct value. The generated filename updates immediately if the current template uses that field. --- ## 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 intelligence level is set in **Settings → Models** under the **Intelligence** picker. ## Intelligence levels | Level | Best for | |---|---| | Small | Default local extraction when available on your Mac | | Medium | Most languages and OCR-heavy documents | | Large | A slower alternative for harder documents | | X Large | Difficult documents on Macs with more memory | ## Default level The default level is **Small** when it is available. Small does not store Renamo model files on disk. If Small is not available on your Mac, Renamo uses **Medium** instead. During onboarding, Renamo helps you download Medium before you continue. Renamo recommends about **12 GB** unified memory for Medium. Larger models need more memory and disk space. ## If Small isn't available Small uses Apple Intelligence. If you do not see Small as an option (or Renamo switches back to Medium), try: - Update macOS if needed - Turn on Apple Intelligence in **System Settings** ## Downloads Medium, Large, and X Large can be downloaded from **Settings → Models**. Downloads can resume if interrupted. Settings shows progress while a download is running or resuming. You can also delete downloaded models from **Settings → Models** to free disk space. ## 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 Small does not store Renamo model files on disk. Downloaded Medium, Large, and X Large files are stored in Renamo's app-managed model cache. ## Accounts During onboarding, Renamo asks you to sign in with **Google** or **email** before using the app. After you sign in, **Settings → Account** shows the signed-in account and lets you log out. ## Analytics Renamo records product analytics such as app open, files added, settings opened, model settings viewed, exports, renames, and feedback ratings. If you are signed in, analytics events can be associated with your account. ## 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 - Small is available only on some Macs - About 12 GB unified memory and enough free disk space if you use Medium ## 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 confirm the selected intelligence level is available. - Try Medium if Small is unavailable or struggles with the document. - Use the inspector to see whether any fields were extracted. ## Model download failed Open **Settings → Models** and click download again for Medium, Large, or X Large. 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. - Correct the vendor in the inspector, or 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 The file list can be shown as a compact list or as a table. Use the view control in the toolbar to switch between them. List rows show the original filename, generated filename, and current state. The table view is Finder-style and adds sortable columns for extracted fields, including custom fields. On first run, Renamo starts in table view. | 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. While a batch is running, the toolbar action changes to **Cancel Processing**. ## Preview and edit In list view, select a file to preview it in the detail area. In table view, press **Space** or double-click a row to open Quick Look. PDFs and images support preview zoom controls in the titlebar: zoom out, fit width, and zoom in. If a prediction is wrong, open the inspector and correct the extracted field. The generated filename updates immediately when that field is part of the filename template. You can also edit the generated filename directly before renaming. Direct filename edits only affect the selected file; they do not change the filename template or extracted fields. To retry one file with a different downloaded intelligence level, right-click the file and choose **Process With**. ## 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** in the toolbar (or press **⌘R**). Renamo renames each ready file in its original folder. While renaming, the button shows progress so you can see how far the batch has gone. --- ## Links - [Feedback](https://tally.so/r/PdvD9b)