How to Use OpenAI Codex CLI for Automated Code Refactoring: Multi-File Edits, Natural Language Instructions & Diff Review
How to Use OpenAI Codex CLI for Automated Code Refactoring
OpenAI Codex CLI is a terminal-native AI coding agent that lets you refactor entire codebases using plain English instructions. Unlike chat-based tools, Codex CLI operates directly in your repository, editing multiple files simultaneously and presenting reviewable diffs before any changes are committed. This guide walks you through setup, multi-file editing, writing effective prompts, and safely reviewing AI-generated changes.
Step 1: Install OpenAI Codex CLI
Codex CLI requires Node.js 22 or later. Install it globally via npm:
npm install -g @openai/codex
Verify the installation:
codex —version
Step 2: Configure Your API Key
Export your OpenAI API key as an environment variable. Add this to your shell profile (~/.bashrc, ~/.zshrc, or equivalent):
export OPENAI_API_KEY="YOUR_API_KEY"
Reload your shell or run source ~/.bashrc. You can also pass the key inline per session:
OPENAI_API_KEY=YOUR_API_KEY codex
## Step 3: Understand Approval Modes
Codex CLI provides three approval modes that control how much autonomy the agent has:
| Mode | Flag | Behavior |
|---|---|---|
| Suggest | --approval-mode suggest | Requires approval for every file read and edit (default, safest) |
| Auto Edit | --approval-mode auto-edit | Reads and writes files automatically, but asks before running commands |
| Full Auto | --approval-mode full-auto | Executes everything autonomously within a sandboxed environment |
codex --approval-mode auto-edit
## Step 4: Write Natural Language Refactoring Instructions
Navigate to your project root and launch Codex CLI with a clear, specific prompt. The more context you provide, the better the results.
Single Concern Refactoring
codex “Refactor all callback-based functions in src/api/ to use async/await. Preserve existing error handling behavior and update the corresponding unit tests in tests/api/.”
Multi-File Rename and Restructure
codex "Rename all React class components in src/components/ to functional components using hooks. Convert lifecycle methods to useEffect where appropriate. Keep prop types intact."Code Style Enforcement
codex "Convert all JavaScript files under src/ from CommonJS require() syntax to ES module import/export syntax. Update package.json to set type to module."Using Instruction Files for Complex Refactors
For large refactoring tasks, save your instructions to a Markdown file and reference it:
# Create instructions file
cat > refactor-instructions.md <<'EOF'
## Refactoring Tasks
1. Extract all database queries from route handlers into a new `src/repositories/` directory
2. Each model should have its own repository file (e.g., userRepository.js, orderRepository.js)
3. Repository functions should accept a database connection as the first parameter
4. Update all route handlers to import from repositories instead of inline queries
5. Add JSDoc comments to each repository function
EOF
codex “Follow the instructions in refactor-instructions.md to refactor this project.”
Step 5: Review AI-Generated Diffs Before Commit
In **suggest** mode, Codex CLI presents each proposed change as a diff and waits for your approval. You will see output like:
── Edit: src/api/users.js ──
- function getUsers(callback) {
- db.query('SELECT * FROM users', callback);
- }
+ async function getUsers() {
+ return await db.query('SELECT * FROM users');
+ }
Apply this change? [y/n/e(dit)]
Your review options:
- y — Accept and apply the change- n — Reject the change- e — Open the diff in your editor for manual adjustmentsAfter reviewing all changes, use Git to inspect the full scope before committing:
# Review all changes made by Codex git diff
Stage and commit with a descriptive message
git add -A
git commit -m “refactor: convert callback functions to async/await via Codex CLI”
Step 6: Configure Project-Level Settings
Create a codex.md file in your project root to provide persistent context to the agent:
# codex.md
Project Context
- This is a Node.js Express API using PostgreSQL
- Use ESM import syntax throughout
- Follow the existing error handling pattern in src/middleware/errorHandler.js
- Never modify files in the migrations/ directory
Runnpm testafter making changes to verify nothing is brokenCodex CLI automatically reads this file on every invocation, ensuring consistent behavior across sessions.
Pro Tips for Power Users
- Chain with Git branches: Always create a feature branch before running Codex —
git checkout -b refactor/async-migration— so you can easily discard all changes if needed.- Use full-auto mode with tests: If your project has a solid test suite, runcodex —approval-mode full-auto “Refactor X and then run npm test to verify”. The agent will self-correct if tests fail.- Scope your prompts: Specify exact directories or file patterns. “Refactor files matchingsrc/services/*.js” yields more focused results than broad instructions.- Model selection: Codex CLI defaults to theo4-minimodel. For complex architectural refactors, specify a more capable model:codex —model o3 “your prompt”- Quiet mode for scripting: Usecodex —quietin CI/CD pipelines to suppress interactive prompts and output only the results.- Combine with linters: After Codex completes edits, run your linter to catch formatting issues:codex “Refactor X” && npx eslint src/ —fix
Troubleshooting Common Errors
| Error | Cause | Solution |
|---|---|---|
Error: OPENAI_API_KEY not set | Missing environment variable | Run export OPENAI_API_KEY=YOUR_API_KEY in your terminal |
EACCES permission denied | Global npm install without permissions | Use sudo npm install -g @openai/codex or configure npm prefix |
Node.js version < 22 | Outdated runtime | Update Node.js: nvm install 22 && nvm use 22 |
| Agent modifies unintended files | Prompt too broad | Narrow your instruction scope to specific directories or file patterns |
| Changes break existing tests | Agent lacks project context | Add a codex.md with project conventions and test commands |
Rate limit exceeded | Too many API requests | Wait and retry, or reduce the scope of your refactoring task |
Can Codex CLI refactor code across multiple programming languages in the same project?
Yes. Codex CLI is language-agnostic and can process files in any language within the same session. For example, you can instruct it to refactor Python backend files and JavaScript frontend files simultaneously. Simply specify the directories and languages in your prompt for the best results, such as: codex “Convert all Python files in backend/ to use type hints and update the TypeScript types in frontend/src/types/ to match.”
Is it safe to use full-auto mode on a production codebase?
Codex CLI runs full-auto commands inside a network-disabled sandbox with directory-level write restrictions, which limits the blast radius. However, you should always run it on a separate Git branch, never directly on main or production branches. Pair full-auto mode with a comprehensive test suite so the agent can validate its own changes. Review the final diff with git diff before merging regardless of mode.
How does Codex CLI differ from using ChatGPT or Copilot for refactoring?
Unlike ChatGPT which operates on code snippets you paste into a chat window, Codex CLI has direct access to your entire repository file system. It reads your project structure, understands file relationships, and edits multiple files in place. Compared to Copilot which provides inline suggestions, Codex CLI executes complete refactoring workflows autonomously — it can rename variables across dozens of files, restructure directories, update imports, and run your test suite to verify correctness, all from a single natural language command.