Refactoring with Codex: plan, goal and a review for each step

What Codex does for refactoring

• Works through a refactoring backlog in small steps, each its own pull request.
• Runs the tests before and after every step, and stops when they fail.
• Does the mechanical part of migrations: renames across the codebase, API upgrades, a move to a new library.
• Removes dead code and duplicated logic, and explains each removal.

Codex features for refactoring

How to set up Codex for refactoring

1. Connect the tools

   There's nothing to connect. What makes a refactor safe is a test command Codex can run and a limit on the size of each step, so put both in AGENTS.md.

   # In the CLI: agree on the plan, then set the finish line
   /plan Propose a migration plan for the billing module
   /goal Finish the migration and keep tests green

2. Write the rules in AGENTS.md

   Codex reads AGENTS.md before any work: ~/.codex/AGENTS.md, then the files from the repository root down to the folder it's working in. Put the job's rules there, or in a skill under .agents/skills/ if they're long. See the AGENTS.md guide.

   ## Refactoring rules
   - No behaviour changes. If a test has to change, stop and ask.
   - Run `npm test` before you start and after every step.
   - One step per pull request, under 400 changed lines.
   - Keep REFACTOR.md current: check off what's done, add what
     you found.
   - Don't touch migrations/, generated files or public APIs
     without asking.

3. Run it without the interactive interface

   codex exec runs one task and exits. Progress goes to stderr and the final message to stdout; -o also writes it to a file and --json streams events. The sandbox is read-only unless you pass --sandbox workspace-write.

   # Day one, then the same session again the next day
   codex exec --sandbox workspace-write "Do the first step in REFACTOR.md"
   codex exec resume --last "Continue with the next unchecked step in REFACTOR.md"

4. Put it on a schedule

   Create a scheduled task in the ChatGPT desktop app or on the web (the CLI doesn't manage them), or run codex exec from cron. See how to make Codex proactive.

Source: Codex documentation

Limits and safety

• Without tests it can't tell a refactor from a behaviour change. Add tests for the area first.
• A large rewrite in one pass is hard to review. Small steps that each merge are safer, and faster in the end.
• It doesn't know which odd code is deliberate. Mark those places with a comment or in the rules.
• Codex sandboxes commands by default: writes stay in the workspace and the network is off. Keep danger-full-access for an isolated runner or container.

Claude Code or Codex for refactoring?

The rules carry over. Write them once in AGENTS.md and put @AGENTS.md in CLAUDE.md, and both agents read the same file.

Step by step for the other agent: refactoring with Claude Code.

Make refactoring someone's job

Commands run when someone remembers to run them. Crewmark turns your own Codex into an AI employee with a role, a goal in numbers, working hours and a heartbeat, so the work happens on schedule and shows up on a board.

1. Start from the role

   The AI software engineer, with these rules in its brief.

2. Put the work on its board

   Add the job as a recurring issue. The employee wakes on its heartbeat, does it and reports in a comment.

3. Related

   Code review checks each step before it merges.

FAQ