alchaincyf/codex-orange-book: Inside the OpenAI Codex Complete Guide

A book repository, not a software project

The first thing to understand about alchaincyf/codex-orange-book is that cloning it gives you no build step and no dependency graph. The top level of the repository holds six document files and four media files: a PDF, an EPUB and a single-file HTML build in each of English and Chinese, plus two banner images, a launch film in GIF and MP4 form, and a Chinese version of the same film. The README is the only prose file that is not a book artifact.

The project describes itself as the eighth entry in the Orange Book (橙皮书) series, a set of hands-on guides for people building with AI. The subject here is OpenAI Codex, and the book's stated scope is all five of its forms: CLI, Desktop App, Cloud, IDE Extension and the Chrome Extension, with a coda on the mobile companion that shipped on May 14, 2026. The audience the README names is engineers who want to hand implementation to an agent while keeping architecture decisions, Claude Code users evaluating the alternative, and product managers or founders shipping an MVP alone.

That framing matters for how you evaluate the repository. There is no test suite to run, no issue tracker full of bug reports to weigh, and no API surface to audit. The quality question is whether the prose is accurate and current, and the currency question is answered by the version string in the filenames: v2.0.1, dated May 2026 in the README. The last push to the repository was on 2026-08-23, and the repository is not archived.

How the Orange Book is packaged and delivered

Distribution is deliberately boring. Each edition exists as a PDF, an EPUB and a single-file HTML document, and the README recommends the PDF because GitHub's online preview may not render the others properly. The English HTML build is listed at 232 KB and the Chinese one at 220 KB, which is small enough to open in a browser tab and search with the browser's own find function. That is the practical path for anyone who wants to grep the text for a specific command rather than read cover to cover.

The Chinese EPUB carries a note that it is WeChat Reading optimized, which suggests the author tuned it for a specific reading app rather than for a generic e-reader. If you read EPUBs on a Kobo or a Kindle, that is a detail worth checking before you assume the file behaves the same way. The English EPUB is 5.6 MB against a 1.7 MB PDF, which is a normal ratio for a text-heavy book with images.

The book is also mirrored on WorkBuddy's knowledge base, one page per chapter, and the README explicitly suggests dropping that link into your agent as context. That is the most interesting delivery choice in the whole repository: the book is being positioned as something you can feed to a coding agent, not only something a human reads. There is no tooling in the repository to do that automatically. You would paste the link or the HTML file yourself.

Installing nothing: reading the guide and running your first Codex session

There is no install command for this repository. You download a file. The commands worth documenting are the ones the book teaches, and the README's table of contents places the install walkthrough in the Foundations part, described as a 10-minute install, followed by a first project chapter.

The book's structure tells you the intended order. Foundations covers the five forms and the install. Daily Workflow goes into the CLI with its auto-review and sandbox behaviour, AGENTS.md configuration, and the Desktop App suite. Beyond the Local Machine covers Cloud and the Chrome extension alongside what the README calls four extension layers: Skills, MCP, Automations and the /goal system. Building Real Things covers going from idea to shipped product and a dual-tool mental model for using Codex and Claude Code together.

The appendix is where the reference material lives, and the README names several commands it covers. If you want to know what the book actually documents before downloading, this list is the concrete evidence:

/vim
/hooks
/goal
/ide
codex remote-control

Those are slash commands and a CLI subcommand as the README lists them. The /goal entry connects to a feature the release notes describe as a persistent objective system that survives /clear, compaction and sessions. The /vim entry implies editor keybindings inside the Codex interface. None of these are explained in the README itself; the README only tells you they appear in Appendix A, the command reference.

A second appendix covers pricing across what the README calls three Pro tiers, and a third is the FAQ. The v2.0.0 notes state that the tiers are $20, $100 and $200, replacing an older two-tier structure, and that the author considers the $100 tier the sweet spot for indie developers. Treat that as the author's judgement, not a measured result.

The limitations chapter is the reason to read this over vendor docs

Most guides written close to a product launch read like extended release notes. This one carries a section the README titles "Honest About the Rough Edges," and the items in it are specific enough to be checkable.

Four stand out. First, the book states that on SWE-Bench Pro, GPT-5.5 still loses to Claude Opus 4.7, at 58.6% against 64.3%, even while the same release notes claim GPT-5.5 leads on SWE-bench Verified at 82.6% and Terminal-Bench 2.0 at 82.7%. Presenting both numbers is the honest move: benchmark leadership depends entirely on which benchmark you pick, and a guide that only quoted the favourable one would be marketing. Second, the book says the 1M context window in Codex is actually about 258K usable. That is the kind of number you only learn by hitting the wall, and it changes how you plan large refactors. Third, it warns that Full Access mode on Windows has deleted user files, citing reports of 370 GB, 700 GB and 240 GB, and says never to enable it. Fourth, it notes three unfixed GitHub issues in MultiAgentV2 (#16657, #17523, #14233) as of the v2 release.

The warning about Full Access on Windows is the single most useful sentence in the repository for a new user, and it is the kind of claim that ages. Issue numbers get closed. If you are reading this months after the v2.0.1 release, verify the MultiAgentV2 issues and the Windows behaviour against the current Codex documentation before you treat the warning as still live. The book cannot update itself.

There is also a scoping clarification worth noting: the README states plainly that Codex on mobile is the Desktop App's remote companion, not a standalone phone agent. That distinction is easy to get wrong from product announcements alone.

What the repository does not give you

The most obvious limitation is that this is a static artifact describing a fast-moving product. The version history in the README shows a major revision, v2.0.0, landing on May 14, 2026, one month after the previous state of the book, followed by an addendum release v2.0.1 on May 15. That cadence is the author's own admission that the underlying subject changes faster than a book normally would. The last push to the repository was on 2026-08-23, which tells you when the files were last touched but not which claims inside them were re-verified.

A second limitation is the licence. The work is under CC BY-NC-SA 4.0, which the README summarizes as free to share and adapt for non-commercial purposes with attribution. That rules out a lot of otherwise reasonable uses: internal training material at a company that sells software, a paid course built on the text, or ingestion into a commercial model's training corpus. Share-alike also means adaptations carry the same licence. This is a description of the terms, not legal advice; if your use is commercial, read the licence text itself.

Third, there is no code. If you were hoping for reference implementations, prompt files, AGENTS.md templates or a working MCP server to copy, the repository does not contain them. Everything is prose and rendered documents. The one exception is the HTML build, which you could parse, but it is a book, not a library.

Finally, the repository has no releases and no issue tracker activity visible in what the README describes. There is no errata channel. If you find a factual error, the feedback path is the author's social accounts, which the README lists.

Codex guide versus the official documentation

The obvious alternative is OpenAI's own Codex documentation, and the difference in approach is worth stating precisely. Official docs are organized around the product's current state and are updated by the vendor. They are authoritative on flags, pricing and availability, and they carry no opinion about whether a feature is worth using.

This book is organized around a workflow and carries opinions. It sequences material from install to shipped product, it names a specific tier as the sweet spot for a particular kind of developer, and it publishes a comparison against a competing tool that the vendor would never write. It also bundles the negative findings: the benchmark where Codex loses, the usable context figure, the file-deletion reports on Windows.

A second alternative, for readers who already use another agentic coding tool, is the book's own §10, which the README describes as an honest, data-backed comparison of when to use Codex versus Claude Code. That chapter is inside this repository rather than a competing one, which is a reasonable reason to read it even if you have no plans to switch.

The trade-off is maintenance. Vendor documentation is the source of truth and changes with the product. This book is a snapshot with a version number, and its accuracy degrades between revisions. Use it to build a mental model and to learn which pitfalls exist; use the vendor docs to confirm that a specific flag still behaves the way the book describes.

Licence terms and what upgrading actually costs

The licence is CC BY-NC-SA 4.0, and the README states the grant plainly: share and adapt for non-commercial purposes with attribution. Three consequences follow directly from those terms. Attribution is required, so redistributing the PDF without crediting HuaShu is outside the grant. Non-commercial excludes paid products and revenue-generating internal use, which is broader than many readers assume. Share-alike means a translated or excerpted version you publish must carry the same licence. None of this is legal advice; the licence text governs.

Upgrade cost is unusual here because there is no dependency to bump. Moving from one edition to the next means downloading a new file, and the filenames encode the version, so v2.0.1 is distinguishable from whatever precedes it at a glance. Nothing in your toolchain breaks. The real cost is re-reading: the v2.0.0 notes list changes across model defaults, form count, approval behaviour, pricing tiers and a new persistent objective system, which is a substantial fraction of the book's practical content. If you annotated your copy, those annotations do not carry over.

The maintenance signal available is the last push date, 2026-08-23, and the fact that the repository is not archived. That is what the repository itself shows. Whether another revision lands, and when, is not stated anywhere in the README.

Editorial conclusion

Adopt this if you are an engineer or solo builder who wants a structured walkthrough of Codex's five forms and a limitations chapter that names specific failure reports, and if non-commercial use under CC BY-NC-SA 4.0 fits your situation. Skip it if you need runnable code, a maintained library, or a corpus you can fold into a commercial training pipeline. Before reading, verify the edition tag in the filename matches v2.0.1, check whether the Chinese EPUB is the one you want since it is described as WeChat Reading optimized, and confirm that the claims you plan to rely on (context limits, tier pricing, the Windows Full Access warning) still hold against current OpenAI documentation, because the book's own revision cadence is monthly and nothing in the repository enforces it.

Frequently asked questions

Official sources

1. alchaincyf/codex-orange-book on GitHub
2. Issues
3. Project website
4. README