Find Reference Images With Claude Code or Codex in refern
You can find a reference by describing it to Claude Code or Codex. With refern 1.10 connected over MCP, the assistant searches the workspace that is open in refern on your computer. It can use words and filters, Search by meaning, color, and similar images. It can also look at a result's thumbnail to check it. When the result is useful, the assistant can keep it as a smart folder, a group, or links.
This guide assumes refern is already connected. If it is not, follow connecting Claude Code or Codex to your reference library first.
Use a Read token for searching
Create a separate token with Read access for search work. A Read token can browse, search, find similar images, search by color, and read thumbnails and original files. It cannot change anything. The assistant sees only the tools its token allows.
When you create the token in Settings > Local API, you can also turn on Exclude NSFW items. A token with this setting never receives an NSFW item: not its file, thumbnail, metadata, links, or name. Changes to such items fail as not found. An item counts as NSFW when it is marked NSFW or carries a tag whose rule marks items NSFW, as in the app. A group with an NSFW member is hidden too. An NSFW folder cannot be listed or searched in, but items in it that are not NSFW still appear elsewhere, with their folder path. The token list shows the badge Hides NSFW items on such a token.
To keep your results later, you need a token with more access. The last section explains which one.
Search by words and filters
Most searches start here. Say what you remember in plain words, and add the filters you know. The assistant turns your request into one search with text and filters.
Find images tagged anatomy and hands with a rating of 4 or higher.
Show me favourite video references in my Lighting folder and its subfolders, most recently added first.
Find images with a source name that contains ArtStation, added after 2026-06-01, that have notes.
These are the filters a search can combine:
| What you say | What refern filters on |
|---|---|
| Words, such as "rainy street" | Every word must match: the word index, part of the item's name, or part of a tag or creator name on the item |
| Tags | All of the tags, any of them, exactly these tags, none of them, or items with no tags; tags to exclude |
| A folder | One folder, with or without its subfolders |
| A kind | Image, video, canvas, file, or folder |
| Favourites, NSFW | Only favourites or only others; only NSFW items or only safe items |
| Rating and color labels | A minimum rating from 1 to 5; one or more color labels |
| Creators | Items credited to the creators you name |
| Description, notes, source | Items that have a description or notes; text in the source name |
| Dates | Added after or before a date |
| Order | Relevance, date added, date updated, name, rating, or size, in either direction |
A search returns up to 200 items. When more items match, the result says so, and you can ask the assistant to narrow the search. Each list filter takes at most 50 values. Items in hidden folders never appear, as in the app.
Two rules differ from the search box in refern. First, the app tries close spellings when nothing matches, and the API does not. If a search comes back empty, check the spelling of each word. Second, tag names must exist. A tag's alias also works, but an unknown name returns an error that lists it. Ask "List my tags that contain hand" before a tag search if you are not sure of the name.
The filters match what is recorded about each item. They cannot find a subject that nobody tagged or named. For how to record useful details as you save references, read finding old reference images by tag. To run the same kind of search yourself, see searching with operators.
Search by meaning
Use Search by meaning when you remember what an image shows but not how you labeled it.
Find images of a figure lit from below by firelight.
Search by meaning compares your description with the images themselves, so it can find references that have no matching tags. It needs the Auto Tagger model. If the model is not installed, the search fails with semantic_unavailable. Install the Auto Tagger in refern first. The model is a one-time download; after that, searches run on your computer.
A search by meaning returns up to 200 results, ranked. Treat the ranking as a shortlist to check, not as a final answer.
Search by color
Give the assistant a hex color to find images whose dominant colors match it. You can limit the search to one folder.
Find images in my Skies folder with a dominant color of #3a6ea5.
If you name a color in words, such as "dusty teal", the assistant must choose a hex code for it. Ask it which code it used, and change the code if the results are off.
Find similar images
Start from an image you already found, then ask for more like it. There are two modes:
- Visual, the default, finds images that look like the starting image.
- Meaning finds images that show the same kind of thing, even when they look different. It needs the Auto Tagger model, like Search by meaning.
Find 20 images that look like the third result.
Find images similar in meaning to sunset-pier.png.
The starting item must be an image or other file in the open workspace. Results are ranked, up to 200.
Let the assistant look at the results
Search results come back as text: names, folders, tags, and other details. To check what an image actually shows, ask the assistant to look at it. When it reads one item, refern also returns that item's thumbnail as an image the assistant can see.
Look at the first ten results and keep only the ones that show hands from below.
The assistant reads items one at a time for this. Thumbnails come only with these single reads, not when it reads several items at once or sends requests in a batch, so a long list takes more steps. The assistant sends what it reads, thumbnails included, to its own provider, as with any file you show it.
Keep the result
A search answer disappears when the conversation ends. If you will need the references again, ask the assistant to keep them in refern. Each way needs more than Read access:
| Keep it as | Best for | Access |
|---|---|---|
| Smart folder | Rules you want to run again as the library grows | Organize |
| Group | A hand-picked set of files in one folder | Write |
| Links | A hand-picked set across folders | Write |
Create a separate token with that access for this step, or ask the assistant to list the result first and keep it later.
A smart folder
A smart folder saves search rules, not a list of files. Use it for a search you want to run again, such as "images tagged anatomy with a rating of 5". For what makes a good rule, read creating smart folders.
Make a smart folder called Anatomy shortlist for images tagged anatomy with a rating of 5. Show me the folder you will add before you save.
refern stores all smart folders as one list. To add one, the assistant reads the current list and its revision, adds your folder, and sends the whole list back with that revision. If the list changed between the read and the save, refern refuses the save with revision_conflict and writes nothing. The assistant must then read the list again. refern also checks each folder against the rules the app can run, and refuses a list it cannot use.
Because the assistant replaces the whole list, ask it to keep your other smart folders unchanged, then check the sidebar. Smart folder changes cannot be undone from Settings > Local API.
A group
A group keeps two or more files together in refern. All members must be files in the same folder.
Group the four results from the Poses folder and name the group Crouching.
An item can be in only one group. If a result is already in another group, it leaves that group when it joins the new one.
Links
Links connect items across folders. The assistant can link up to 50 items at a time, and every pair of them is linked. Link items, not groups; to link a group, link its members.
Link these six references to each other.
Links and groups also cannot be undone from Settings. To remove links later, ask the assistant to remove the links between the same items.
The same searches from a script
Each request above uses a documented Local API endpoint. Scripts can call them directly with the same token:
| Task | Endpoint | Access |
|---|---|---|
| Text and filters | POST /v1/search | Read |
| Search by meaning | POST /v1/search/semantic | Read |
| Color | POST /v1/search/color | Read |
| Similar images | GET /v1/items/{id}/similar?mode=visual or ?mode=meaning | Read |
| Thumbnail | GET /v1/items/{id}/thumbnail | Read |
| Group | POST /v1/groups | Write |
| Links | POST /v1/links | Write |
| Smart folders | PUT /v1/smart-folders with expectedRevision | Organize |
While the Local API is on, refern serves the full reference at /llms-full.txt on the address Settings shows.
Found images that still need tags? See tagging reference images with Claude Code or Codex.
What this cannot do
- Work without refern open. refern must be running with a workspace open, and the assistant searches only that workspace.
- Reach other computers or web chats. The server listens only on your computer. An assistant that runs in a web browser cannot connect.
- Guess spellings. Text search through the assistant does not try close spellings, and tag names must exist.
- Search by meaning without the model. Search by meaning and similar in meaning need the Auto Tagger model.
- Delete files. No access level can delete files from disk.
- Work after the trial without a license. Requests are refused when the 30-day trial has ended and no license is active. A license costs $35 once, for up to three devices on Windows, macOS, and Linux.
Frequently asked questions
Do I need the Auto Tagger to search with an assistant?
Only for Search by meaning and for finding images that are similar in meaning. Text and filter search, color search, and visually similar images work without it. If the Auto Tagger model is not installed, a search by meaning fails with semantic_unavailable, and the assistant should tell you to install the model in refern.
Can a Read token change anything in my library?
No. A Read token can browse, search, find similar images, search by color, and read thumbnails and original files. The assistant sees only the tools its token allows, so it has no editing tools to call.
Why does the assistant say a tag does not exist?
Tag filters need tag names that exist in the open workspace. A tag's alias also works. Unknown names return an error that lists them. Ask the assistant to list your tags that contain a word, then search again with the exact name.
Can I undo a smart folder that the assistant made?
Not from Settings > Local API. The change is listed in Recent API changes, but smart folder changes have no undo there. Edit or delete the smart folder in the refern sidebar instead. The same applies to groups and links.