Last week, I was staring down a messy Node.js codebase that needed a major refactor. I had dozens of functions using outdated callback patterns that needed to be converted to async/await, plus a handful of lingering TypeScript type errors. Doing it manually was going to take hours of tedious find-and-replace work. I'd been using Cursor for small autocomplete tasks, but I needed something that could actually execute multi-file changes and run my test suite to verify nothing broke.
That's when I decided to give OpenAI's Codex a real spin. I'd ignored it when it first launched, assuming it was just another chatbot glued to a terminal, but spending a weekend deep-diving into it genuinely surprised me. Here's exactly how I got it set up, the mistakes I made along the way, and how you can start using it for your own coding tasks.
Understanding the Four Flavors of Codex
Before we dive in, you need to know that Codex isn't just one thing. There are actually four ways to use it, and picking the wrong one will just frustrate you:
- The Desktop App: A standalone app where you point Codex at a local folder or git repo, and it works directly on your machine.
- The VS Code Extension: Runs side-by-side in your editor, great for inline edits and quick queries.
- The CLI: A terminal-based interface for those who live in the command line.
- Codex Cloud: Runs on OpenAI's sandboxed servers. It can handle larger tasks and even open pull requests directly via GitHub integration without touching your local machine.
For my refactor, I started with the Desktop App because I wanted it to read my local files, make changes, and run my local test suite. Here's how that went.
Step 1: Setup and Authentication
Getting started is deceptively simple, which actually tripped me up later.
- Download and open the Codex desktop app.
- Sign in with your ChatGPT account. (If you have a Pro, Team, or Enterprise subscription, you'll have higher rate limits, which you will absolutely need for anything substantial.)
- Select a folder or git repository on your computer where Codex will work.
I pointed it at my messy Node.js project folder. The app immediately indexed the codebase, which took about 30 seconds for a medium-sized project.
My first mistake: I pointed it directly at my main working branch instead of creating a new branch. Codex will happily edit your files in place. Within five minutes, I had uncommitted changes scattered across 15 files, and I wasn't entirely sure what it had done. Now, I always create a new git branch before kicking off a task. If something goes sideways, I can just git checkout . and start over.
Step 2: Kicking Off Your First Task
Codex operates on "tasks." You give it a prompt, and it formulates a plan, writes the code, and—crucially—can run commands to verify its work.
For my callback-to-async/await refactor, I typed this prompt into the task input:
Find all functions in the src/ directory that use callback patterns
(the last argument is a function called 'cb' or 'callback') and convert
them to async/await. Update any callers of these functions to handle
the promises correctly. After making the changes, run 'npm test' to
ensure nothing is broken.
What happened next was the part that surprised me. Codex didn't just start blindly replacing text. It laid out a step-by-step plan: first, it would scan for the pattern, then list the affected files, then make the edits, and finally run the tests. It asked for my approval before executing the plan.
Step 3: Watching It Work (And Intervening)
As Codex started working, I could see it opening files, making edits, and saving them. It moved through about 20 files, converting the patterns. The edits were clean—it correctly identified return callback(err) patterns and converted them to throw new Error(err), which was a nice touch.
Then it hit a snag. One of my files had a complex waterfall of callbacks where variables were shared across scopes. Codex's initial attempt at converting it created a scoping bug. I watched the test suite fail in real-time as it ran npm test.
Here's where Codex earned my respect: it read the failing test output, realized its mistake, reverted its changes to that specific file, and tried a different approach—wrapping the shared state in a closure before converting to async/await. The second time around, the tests passed.
This iterative loop (edit → run tests → read errors → fix) is the real power of Codex. It's not just generating code snippets; it's acting as an agent that can verify its own work.
Step 4: Using the VS Code Extension for Fine-Tuning
After the bulk refactor was done, I still had a handful of TypeScript type errors. For this, I switched to the VS Code extension because the changes were smaller and I wanted to see the diffs right in my editor.
The VS Code extension is much more conversational. I highlighted a function with a type error, asked "Why is TypeScript complaining about the return type here?", and it explained that my converted async function was now returning Promise<void> instead of just void, which broke an interface I hadn't updated. It offered to fix the interface, and I accepted the one-click edit.
Step 5: Delegating to Codex Cloud
The next day, I had a different task: writing a new utility module from scratch to handle CSV parsing. I didn't need my local environment for this, so I tried Codex Cloud.
Setting up the GitHub integration took about two minutes. I authorized OpenAI to access my repo, gave it the task prompt, and let it run in the cloud. About ten minutes later, I got a notification that it had opened a pull request. I reviewed the PR on GitHub, left a couple of comments asking for edge-case handling, and Codex actually pushed new commits to the PR addressing my review comments. That felt like having a junior developer on call.
Practical Tips and Honest Limitations
After spending real time with Codex, here are the hard-won tips I wish I had from the start:
1. Always work on a new branch. I can't stress this enough. Codex will modify your files. If you're on your main branch, you're in for a stressful time.
2. Be painfully specific in your prompts. "Refactor this" will get you unpredictable results. "Convert all callbacks to async/await in src/utils, ensure all callers are updated, and run npm test" will get you exactly what you want.
3. Give it a good test suite. Codex is at its best when it can verify its own work. If you don't have tests, it will happily make changes that look correct but introduce subtle bugs. The agent is only as good as its feedback loop.
4. Use the right interface for the job. The desktop app is great for large, multi-file refactors where you need local context. The VS Code extension is perfect for quick fixes and explanations. The CLI is ideal if you're SSH'd into a server. Codex Cloud is best for self-contained tasks where you want a PR at the end.
Now, for the limitations. Codex is not a senior developer in a box. It struggles with deeply nested architectural decisions. During my refactor, it missed a circular dependency that my brain caught immediately. It also has a tendency to over-engineer simple solutions—I asked it to add a logging function, and it tried to set up a whole Winston logger with file rotation when a simple console.log wrapper would have sufficed. You still need to review every line it writes.
It also burns through rate limits fast. On a standard Plus account, I hit the cap after about 45 minutes of heavy refactoring. If you're planning to use this for a full workday, you'll likely need a Pro or Team account.
Finally, the context window isn't infinite. On a massive monorepo, Codex sometimes lost track of files it had already edited, leading to inconsistent changes. For huge codebases, break your tasks down into smaller, focused prompts rather than asking it to "fix the whole app."
Despite those caveats, Codex has earned a permanent spot in my workflow. It's not replacing me, but it's taking the soul-crushing tedium out of refactors, boilerplate, and bug fixes. And honestly, watching it read its own failing tests and fix its own mistakes is just genuinely fun.