> For the complete documentation index, see [llms.txt](https://docs.realmacsoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmacsoftware.com/squash/quick-guide/ai.md).

# AI Setup

Generate descriptive filenames and image descriptions on your Mac with Apple Intelligence

Squash uses **Apple Intelligence** to generate **descriptive filenames** and **descriptions** written into image metadata. Everything happens on your Mac: images are never uploaded, and there are no API keys, accounts or usage charges. Compression, resizing and visual effects work independently of this feature.

![Squash with the Rename template set to Describe, listing images with descriptive filenames such as orange-leaf.webp and orange-juice.webp](https://1309898043-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9hJwt9oZ5CYj9I9YIUa9%2Fuploads%2Fgit-blob-da7ff0ba423252c7a6a59a5b7485851b27e1315f%2Fsquash-4-describe.png?alt=media)

### Requirements

* **macOS 27 or later**, on a Mac that supports Apple Intelligence.
* Apple Intelligence turned on in **System Settings**, with its models downloaded.
* On-device image understanding available on that Mac.

See [System Requirements](/squash/system-requirements.md) for the difference between Squash's normal requirements and these.

### Checking the status

There is no AI tab in Settings. Instead, the [Rename](/squash/quick-guide/nodes/rename.md) section in the sidebar shows whether Apple Intelligence is ready:

* **Ready:** the section says "Generated on your Mac with Apple Intelligence. Images never leave your Mac."
* **Apple Intelligence is turned off:** the section asks you to turn it on in **System Settings**.
* **Still downloading:** Squash says the models are still downloading. Try again shortly; queued work starts once they are ready.
* **Not supported on this Mac:** on Macs that can't run Apple Intelligence, such as Intel Macs or Macs running an earlier version of macOS, the **Describe** token is hidden. Any Describe token in your template is replaced with **Original**.

### Turning descriptive filenames on and off

The [Rename](/squash/quick-guide/nodes/rename.md) template starts as **Describe**, so descriptive filenames are on by default on supported Macs. Remove the Describe token from the template to turn them off; nothing is described while the template doesn't use it.

### Image descriptions

In the [Metadata](/squash/quick-guide/nodes/metadata.md) section, set **Description** to **Apple Intelligence** to write a sentence or two about each image into its metadata, useful as alt text. Descriptions are generated when you export, alongside any descriptive filenames, and use the same queue, progress and **Retry Failed**. Images redacted with the [Highlighter](/squash/quick-guide/nodes/redact.md) are never described. Where Apple Intelligence isn't available, the option is dimmed.

### When generation starts

* **Adding images:** when the Rename template uses Describe, Squash starts generating as soon as images are added to the list. Adding Describe to the template also starts generation for images already in the list.
* **Export:** exporting images runs any missing AI steps, filenames and descriptions, before saving.

Generation does not depend on **Automatically compress images**. Matching cached results are reused, so exporting an unchanged batch does not repeat completed work. Failed descriptions wait until you choose **Retry Failed**.

Review generated filenames and descriptions before using them.

### What Apple Intelligence sees

Squash prepares the image with your sidebar edits applied, such as resizing and effects, but before compression. It scales it down so its longest side is at most 1600 pixels, and removes original EXIF and GPS metadata. Apple Intelligence then describes it on your Mac. See [Privacy Policy](/squash/extras/privacy-policy.md) for more on how Squash handles images.

### Performance

Descriptions are generated by Apple Intelligence on your Mac, so how quickly they arrive depends on your Mac. Newer Apple silicon with more memory describes images faster. On Macs with 8 GB of memory it can be slow, especially with large batches or other demanding apps open.

Each image has up to a minute. If it takes longer, that image is marked as failed and the rest of the batch continues. Choose **Retry Failed** to try again, ideally with fewer images at once or other apps quit. If you don't need descriptive filenames, remove **Describe** from the [Rename](/squash/quick-guide/nodes/rename.md) template.

### Progress and troubleshooting

Click the **Activity** button (the progress ring at the bottom left of the settings sidebar, beside **Export Images**) to follow the **Describe** job. Choose **Stop** to stop a running batch, or **Retry Failed** to try failed images again. A cancelled or failed generation does not remove a filename you already have.

| Message or problem                                      | What to check                                                                                                                                   |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| Requires macOS 27 or later                              | Update macOS on a Mac that supports Apple Intelligence.                                                                                         |
| This device doesn't support Apple Intelligence          | Descriptive filenames aren't available on this Mac. Other features work normally.                                                               |
| Turn on Apple Intelligence                              | Turn on Apple Intelligence in **System Settings**.                                                                                              |
| Still downloading                                       | Wait for the Apple Intelligence models to finish downloading.                                                                                   |
| Apple Intelligence took too long to describe this image | Choose **Retry Failed**. On Macs with less memory, describe fewer images at once or quit other demanding apps. See [Performance](#performance). |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.realmacsoftware.com/squash/quick-guide/ai.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.