Use Claude Code to Plan a File Rename Without Changing Files

File names become a small tax on every project. final_report_v7_really-final.docx is funny once. A folder full of them is not.

Claude Code can inspect files and run commands from a terminal, but that does not mean you should hand it permission to rename a folder immediately. This workflow keeps the first pass read-only. You ask for a proposed rename map, review it, and only then decide whether to do the work.

This guide is documentation-based. It uses a fictional folder and an illustrative output. It does not claim that a Claude Code run happened.

What you will make

You will make a text file called rename-plan.md containing each original file name, its proposed new name, the reason for the change, collision warnings, and files that should not be changed.

You need Claude Code installed on a terminal surface and a folder you are allowed to inspect. Anthropic documentation describes Claude Code as a tool that can work across files and tools, run commands, and work with git. Use a disposable practice folder first.

Fictional input

Create a folder named client-pack with these files:

client-pack/
  2026-09-30_final_report.docx
  2026-09-30_final_report (1).docx
  notes.txt
  logo-approved.svg
  README.md
  archive/
    2026-08-31_final_report.docx

The intended convention is YYYY-MM-DD_topic_status.extension. The logo and README should stay unchanged. The archive folder is out of scope.

Steps

1. Start in the practice folder

Open a terminal and move into the folder parent. Start Claude Code in the project folder:

cd path/to/client-pack
claude

Claude Code may ask you to sign in on first use. The command and login flow can vary by installation surface, so follow current official setup instructions for your system.

2. State the boundary before asking for analysis

Paste this prompt:

Inspect only the files in the current directory. Do not inspect archive/.
Do not rename, move, delete, edit, or create any files yet.

Prepare a proposed rename plan for files that match this rule:
YYYY-MM-DD_topic_status.extension

Keep README.md and logo-approved.svg unchanged.
Treat duplicate-looking names as a possible collision, not as permission to overwrite anything.

Return a Markdown table with these columns:
original path | proposed path | reason | collision risk | action
Then list:
1. files you will leave unchanged
2. assumptions you made
3. questions that need a human answer
Stop after producing the plan. Do not run a write command.

The stopping point is explicit. You still review every permission prompt and terminal output.

3. Check the proposed map against the folder

Compare every original path in the table with the real directory listing. Confirm that:

archive/ never appears in the proposed changes
README.md and logo-approved.svg remain unchanged
the two September reports are not silently merged
the plan does not overwrite an existing path
each proposed name keeps its file extension
an ambiguous topic is marked as a question instead of guessed

For this sample, the duplicate report should remain unresolved until a person decides whether it is a copy, a revision, or a separate deliverable.

4. Save the plan outside the input folder

Copy the response into a review note, or ask Claude Code to write the plan to a location you choose only after reviewing the text. The safest first artifact is plain text in the chat history. Do not ask the tool to execute a rename as part of this lesson.

A possible illustrative output looks like this:

| original path | proposed path | reason | collision risk | action |
| 2026-09-30_final_report.docx | 2026-09-30_report_final.docx | remove redundant word | medium | human review |
| 2026-09-30_final_report (1).docx | unknown | possible duplicate or revision | high | do not rename yet |

Unchanged: notes.txt, logo-approved.svg, README.md, archive/2026-08-31_final_report.docx
Question: are the two September reports duplicates or separate versions?

This is an editor-written example. It is not a captured Claude Code result.

5. Decide on a separate execution step

If the plan is correct, start a new request with the exact approved paths and a dry-run command for your operating system. Ask Claude Code to show the command before running it:

Use only the approved rename rows below.
First show the exact commands you would run and the resulting paths.
Do not execute them until I approve the command list.
Abort if any destination already exists.

Do not approve a command list that uses a broad wildcard, includes archive/, or overwrites a destination. Keep a backup or use version control before changing files.

Acceptance checks

The planning step passes when the plan contains every in-scope file exactly once, excluded files and directories are named, collisions are visible, no file was renamed or deleted, known facts are separate from assumptions, and a human can approve individual rows.

Verify the no-change condition with a directory listing and, in a git project, git status. An empty status does not prove that the plan is correct. It only shows that the repository did not record a change.

Troubleshooting

Claude proposes changes inside archive/. Stop. Restate the boundary and ask for a new plan using an explicit allowlist of file paths.

A destination already exists. Mark the row as blocked. Do not ask Claude to replace it. Compare the files and choose a destination manually.

The tool wants to run a shell command immediately. Decline the permission and request the table only. The task is planning, not execution.

The file names contain spaces or parentheses. Keep paths quoted in any later command. Do not let a shell interpret the name as several arguments.

Limits and privacy

Claude Code can read files, run commands, and connect to external tools, depending on session permissions and configured MCP servers. Do not start with a real client folder, confidential exports, or a directory containing credentials. Review MCP connections and permissions before using them. A read-only plan is safer than a write-enabled first attempt, but it is not risk free.

Evidence label

Documentation-based guide. Claude Code official overview and MCP documentation support the tool and permission model. The sample folder and output are fictional and illustrative. No personal test or reproduced demo is claimed.

Sources

Join The Weekly Verdict for one practical AI workflow each week.