Codex is now a name OpenAI has used for two quite different things, which causes confusion. The original was a model that turned natural language into code and powered the first version of GitHub Copilot. The current one is a coding agent, which is a different proposition entirely. It reads your repository, plans changes, edits files, runs tests, and comes back with a result you review.
That shift from autocomplete to agent is the important thing about the last couple of years of AI assisted development and it changes what you need to learn. There are three ways to use it and they suit different work. The cloud agent runs in ChatGPT against a container with your repository in it, works on a task while you do something else, and produces a pull request. Good for well specified, self contained changes where you can write a clear description and walk away.
The command line tool runs locally in your terminal with access to your actual working directory, which suits iterative work where you want to watch and intervene. The IDE extension sits somewhere between the two. Understanding which mode fits which task is most of the skill and the documentation explains the mechanics of each without quite telling you that. On the documentation itself, it has come a long way.
The early material was thin and assumed you already knew what an agent was for. The current version covers installation across platforms, authentication, the approval and sandboxing model, configuration files, how to give the agent standing instructions about your repository, and how to wire it into continuous integration. That is a proper reference now and it is kept reasonably current, which is more than a lot of fast moving tools manage. The sandboxing documentation deserves specific credit.
An agent that can run arbitrary commands in your repository is a meaningful trust decision and the docs are honest about it. They explain what network access the agent has in each mode, what file system access, what requires approval, and how to tighten or loosen it. Anyone deploying this on a codebase that matters should read that section properly rather than accepting defaults, and the fact that it is written clearly enough to do that is worth something. The repository instruction file pattern is well covered and underused.
You can leave standing guidance for the agent about your conventions, your test commands, your architectural constraints, and the difference in output quality between a repository that has this and one that does not is large. This is the single highest leverage thing most people are not doing, and it is documented, and people still skip it. Now the limitations, and the biggest one is not a documentation problem so much as a gap nobody has filled. The docs teach you the tool.
They do not teach you the skill, which is knowing how to decompose a task so an agent can do it, how to write a specification precise enough to be useful, when a task is too entangled to delegate, and above all how to review what comes back. That last one is where the real risk sits. An agent produces code that looks right, passes the tests it wrote itself, and contains an assumption you did not notice. Building the instinct for where to look is a professional skill and you develop it by being burned a few times.
No documentation is going to shortcut that. Cloud environment configuration is the practical sticking point. Getting the container to install your dependencies, reach whatever internal services your tests need, and generally look enough like your development machine to be useful takes fiddling, and the documentation on this is thinner than the difficulty warrants. Expect to spend real time here on any non trivial repository, and expect the payoff to be worth it once it works.
Pace of change is the usual problem. Interface details, flag names and capabilities move, so anything you read outside the official docs may be describing a version that no longer exists. Stick to the official pages and check the changelog, which is maintained. On value, if you already pay for ChatGPT then trying this costs you nothing extra, which removes the main reason people put off evaluating these tools.
It is genuinely competitive with the alternatives, all of which are also moving fast, and I would not tell anyone the comparison is settled. Try two or three on your own codebase for a week each. Your repository and your working style will decide it more reliably than anyone's benchmark. My four out of five is for a strong tool with documentation that has grown into something genuinely useful, held back from higher by a thin treatment of the environment setup that causes most of the friction and by the absence of any real guidance on the review discipline that makes agent assisted work safe rather than fast.