Organize a Messy Reference Folder With Claude Code or Codex

refern 1.10 lets Claude Code or Codex organize the workspace that is open in refern. Through refern's built-in MCP server, the assistant can look through an unsorted folder, propose a folder plan, create the folders, move items into them, rename items with numbers, and move rejects to the Trash. No access level can delete files from disk.

Most of these changes have no Undo: refern lists them, but it cannot reverse them for you. Only the Trash step (and any tag or detail edits) has an Undo button. So the safe workflow is a test folder first, a plan before any change, small batches, and a check of every change afterward.

This guide assumes your assistant is already connected. If it is not, follow connect Claude Code or Codex to your reference library first.

What each step needs, and what you can undo

Each access level includes the one above it, so an Organize token can do every step in this table that is possible.

Before you start

1. Create an Organize token for this job only. In Settings > Local API, select Create token, give it a name such as "Codex: sort Unsorted", and choose Organize. A separate token makes the change list easy to read, because each change shows the token that made it. Keep your everyday token at Read or Write.
2. Make a small test folder. In refern, put 20 to 30 items from your messy folder into a new folder, such as "Sort test". Run the whole workflow on it before you touch the real folder.
3. Keep one workspace open. The assistant works only in the workspace that is open in refern. If you open another workspace during the job, refern refuses the next change and writes nothing.

The assistant looks at thumbnails, names, and tags to make its plan. Assistant apps that run their models in the cloud send what they read to their provider. Turn on Exclude NSFW items when you create the token if those items must stay out of view.

Step 1: Ask for a survey and a plan, not changes

Ask the assistant to look first and change nothing. You type plain sentences; the assistant picks the tools.

Look through every item in my Sort test folder in refern. Do not change anything yet. Describe what you see, and propose a folder plan that lists which items go in each folder.

List the items you are unsure about, and the ones you think are rejects, by name. Do not move anything.

The assistant can read each item's name, size, tags, and dates, and it can look at the thumbnail. If you have run the Auto Tagger, it also sees the suggested labels. Ask it to collect the full list of items before it moves anything: moving items while it reads a folder page by page can shift the listing.

Step 2: Correct the plan

The first plan is a draft. Change it to match how you look for references later. Folders work best for stable context, such as a shoot, a project, or a source pack. Use tags for subjects that cross folders. The reasons are in how to organize reference images.

Use three folders under References: Skies, Hands, and Architecture. Put the uncertain items in a folder named Review later. Show me the final plan as a table, with each item's current name and its new folder.

Keep this table. It is your record of where every item came from, and you need it if you want to reverse a move. If you also want tags, ask for them now and use how to tag reference images with Claude Code or Codex. Tag edits can be undone, and the assistant can show a dry run before it saves them.

Step 3: Create the folders

Create the folders in the plan under References. Tell me which ones already exist.

refern creates each folder on disk. If a folder with that name already exists there, refern refuses to make a second one. A hidden folder cannot hold a new folder until you show it. New folders have no Undo; to remove one you made by mistake, move it to the Trash.

Step 4: Move items in small batches

Move the items in the Skies row of the plan to References/Skies. Then list what you moved.

Move one row of the plan at a time and look at the result in refern before the next row. These rules apply to every move:

• A move changes the file's location on disk and in the library.
• If an item with the same name is already in the destination, refern keeps both.
• One request moves at most 200 items. The assistant splits a larger row into batches.
• A hidden folder cannot be a destination, and items inside one cannot be moved. Show the folder first.
• Large files take longer. refern waits up to 30 minutes for a big move.

A move has no Undo. To reverse it, ask the assistant to move the items back, using the table from step 2.

Step 5: Rename in bulk with numbers

refern's numbered rename works like its bulk rename dialog. It names items basename-1.jpg, basename-2.png, and so on, in the order the assistant gives. Each file keeps its own extension, and the rename happens on disk and in the library.

Before you rename anything, list the current names of the items in References/Hands. Then rename them as hands-001, hands-002, and so on, oldest first.

You can choose the starting number and zero padding. A padding of 3 gives hands-001. A single item gets the base name with no number. Names cannot end with a dot or be a reserved Windows name such as CON or NUL.

If the selection contains a linked copy, the numbered rename renames its original file, as the bulk rename dialog does. If a rename stops partway, refern reports how many items it renamed.

A rename has no Undo. The list of old names you asked for is how you rename items back.

Step 6: Move the rejects to the Trash

Move the items on the rejects list to the Trash.

Moving items to refern's Trash deletes nothing: their files stay on disk. A folder goes to the Trash with everything inside it, and a group stands for all its members.

No token can empty the Trash or delete items permanently. Only you can do that, from the Trash's right-click menu in refern. Look through the Trash before you use Delete permanently or Empty Trash.

This is the one organizing step you can undo from Settings. Undo restores the items, but groups that the Trash dissolved and links of the trashed items do not come back.

Step 7: Check every change, then undo what you do not want

Open Settings > Local API and look at Recent API changes. Each row shows the kind of change, how many items it touched, the token that made it, and the time. refern also writes every change to local-api-journal.ndjson in its app data folder.

A row has an Undo button only when refern can reverse that change. Undo skips items that were changed again later, and it tells you how many it skipped.

These changes can be undone:

• Item details and tags
• Folder and item appearance, such as covers
• An item's creators
• Tag edits and creator edits
• Tag structure names and colors
• Moves to the Trash

These changes are listed but cannot be undone: renames, moves, copies, linked copies, and making an original; imports; restores from the Trash; new folders; hiding folders; groups and links; Auto Tagger runs and reviews; smart folders; custom tag colors; tag structure members; and creating or deleting tags, tag structures, and creators.

refern keeps undo data for the newest 100 changes, up to 32 MB in all. A single change larger than 4 MB is saved but cannot be undone. An assistant can also undo a change for you, but its token needs the same access as the change.

Step 8: Revoke the Organize token

When the job is done, select Revoke on the Organize token in Settings > Local API. refern does not change a token's access after you create it. To keep using the assistant for searches or tags, create a new Read or Write token. To stop all access, switch off Allow apps on this computer to access the open workspace.

Then do the real folder

When the test folder comes out right, repeat the same steps on the real folder with a new Organize token: survey, plan, folders, moves in batches, renames with a record, Trash, check, revoke. For a large folder, back up the workspace first.

To find items again after the cleanup, see how to find reference images with Claude Code or Codex.

Limits to know

• Your computer only. The server listens on 127.0.0.1 (ports 7733 to 7743) and refuses requests from web pages. Cloud-hosted chat apps cannot reach it.
• refern must be running with the workspace open.
• A license after the trial. The free trial lasts 30 days. After that, requests are refused until a license is active. A license is $35 once, for one user on up to three devices, on Windows, macOS, and Linux.
• Not a plugin system. The Local API gives assistant apps access to what refern already does. It does not add features. If you are choosing between libraries for this kind of work, read refern vs Eagle.