Use Codex to Plan a File Rename Without Changing Files

Renaming a folder of files is a small job with an annoying failure mode: a helpful command can change more files than you intended. Codex CLI can inspect a local repository, make focused changes, and run local tools, but the safe first step is a plan that writes nothing.

This Advanced builder lesson is documentation-based. The commands and outputs below were not run here, and no Codex result is claimed.

What you need

• Codex CLI installed and signed in.
• A disposable folder with fictional files or a safe copy of the real folder.
• A terminal and enough access to inspect that folder.
• A human who will review the rename map before any execution.

OpenAI’s Codex CLI documentation describes a terminal workflow for inspecting files, making changes, and running local tools. It also documents permissions and review steps. Treat those controls as boundaries, not as proof that a requested rename is safe.

The fictional folder

Create this safe copy:

client-pack/
  FINAL_notes.txt
  final_budget.csv
  draft_notes.txt
  logo.png
  final_budget (1).csv
  archive/
    FINAL_notes.txt

The rule for this exercise is narrow: rename files in the top level only, convert spaces to underscores, and change .txt names to lowercase. Do not rename folders, files in archive/, or files whose destination already exists.

1. Write the task boundary

Save this as rename-task.txt:

Scope: client-pack/ top level only
Include: files, not directories
Rules: lowercase .txt filenames and replace spaces with underscores
Exclude: client-pack/archive/
Collision rule: report a destination that already exists; never overwrite
First action: print a dry-run map only
Approval stop: do not rename anything until a person approves the map
Acceptance check: every proposed source exists and every destination is unique

This file is the checkable artifact. If the requested change is larger than this boundary, stop and rewrite the task map.

2. Ask Codex for a dry run

From the disposable project, use a prompt like this:

Read rename-task.txt and inspect client-pack.

Produce a dry-run rename map with source path, proposed destination, reason,
and collision status. Do not rename, create, delete, or edit any file.
Do not inspect outside client-pack. Do not run shell commands that change files.
Include excluded files and explain why they were excluded.
Stop after showing the map and a short list of assumptions.

The expected artifact is a table, not a command to paste into production. If Codex proposes a shell command, inspect it without running it. The article does not claim that Codex produced the example below.

3. Review the illustrative map

A suitable map could be:

Source	Proposed destination	Reason	Collision
client-pack/FINAL_notes.txt	client-pack/final_notes.txt	lowercase .txt name	none
client-pack/final_budget.csv	unchanged	no rule applies	none
client-pack/draft_notes.txt	client-pack/draft_notes.txt	already matches	none
client-pack/logo.png	unchanged	extension is not .txt	none
client-pack/final_budget (1).csv	unchanged	spaces rule would need a separate approved action	none
client-pack/archive/FINAL_notes.txt	excluded	outside top-level scope	not checked

The map should not silently rename final_budget (1).csv. The task says spaces should become underscores, but the example map marks it unchanged because the stated rules also require a separate approved action. This ambiguity belongs in the assumptions for a human to resolve.

4. Acceptance checks before execution

A rename plan passes when:

1. Every source path in the map exists in the allowed top-level folder.
2. No directory or excluded archive file appears as an executable change.
3. Every proposed destination is unique.
4. Existing destination files are never overwritten.
5. The map names every unchanged file that was inspected.
6. A person resolves the space rule before any command runs.
7. The original folder remains unchanged during the dry run.

Only after these checks should a technical owner choose an execution method. Keep the map and approval together so the rename can be reviewed later.

No-code alternative

For a small folder, sort the files in your file manager and write the source and destination names in a spreadsheet. Add a collision column and review the rows before renaming anything. The manual method is slower, but it makes the boundary visible.

Troubleshooting

• Codex changes a file during planning: stop and restore the safe copy. Repeat that the first action is read-only and use a disposable folder.
• The map omits unchanged files: require an inspected-file list and compare it with the top-level directory.
• Two sources share a destination: mark both as blocked and resolve the naming rule before execution.
• Codex inspects archive/: restate the top-level scope and ask it to report excluded paths without reading their contents.
• A command looks destructive: do not run it. Ask for a map instead and have a technical owner review the command separately.

Limits and safe use

The CLI can inspect, edit, and run local tools, so keep credentials and production folders out of the first exercise. A dry run does not prove that an eventual rename command is correct. Review the command, make a backup, and use version control or a recovery plan before execution.

TRY this with fictional files in a disposable folder. SKIP unattended renames and production folders. USE an approved rename map only after a human checks collisions and the final command.

Sources and next step

• Codex CLI
• Codex developer commands
• Use Claude Code to plan a file rename without changing files
• Get The Weekly Verdict

The useful result is the reviewed map. The rename comes later, if it still makes sense.