# Codex Auth Helper: a Chrome extension that turns a ChatGPT session into auth.json

> Codex Auth Helper reads your logged-in ChatGPT session in the browser and downloads a Codex-shaped auth.json locally. It is a convenience tool for Codex CLI users, not an account manager, and the README leaves several things unsaid.

**zhishile/codex-auth-helper** — Codex登陆助手：安全地在本地导出您的已登录 ChatGPT 会话配置，生成符合 Codex 规范的 auth.json 本地备份文件。

- Repository: https://github.com/zhishile/codex-auth-helper
- Website: https://codex.afione.com
- Stars: 17,058 · Forks: 666
- Language: CSS
- License: not declared
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/zhishile-codex-auth-helper

## The gap Codex Auth Helper fills between a browser login and the Codex CLI

Codex expects an auth.json file. Getting one normally means either running an interactive login inside the CLI or hand-writing JSON from a session you already have in a browser. Codex Auth Helper targets the second path: you are already signed into chatgpt.com in Chrome, and the extension turns that existing session into the file Codex reads. The README frames the audience narrowly, calling it a credential management and local config backup helper for Codex developers. It is not a general ChatGPT tool, and it does not manage accounts. The extension folder holds a Manifest V3 Chrome extension; the landing-page folder holds the marketing site at codex.afione.com. The primary language of the repository is CSS, which tells you where most of the effort went: the README advertises a glassmorphism popup, hover transitions, toast feedback and several theme colors. The security claim is the other half of the pitch. The README states the core logic runs in a closed browser sandbox and that the generated config is delivered as a data: URL download rather than a temporary Blob. Whether that distinction matters to you depends on how much you care about the file passing through browser memory, but it is a concrete implementation choice rather than a slogan.

## What the extension actually does with your session

The flow described in the README is short. The popup detects the current ChatGPT authorization state and shows the avatar, email and subscription plan, listing Free, Plus or Pro. It reads the token expiry time and counts down to it in the popup. When you ask for the file, the extension assembles a Codex-compatible auth.json and triggers a download. The README says the assembly includes a synthetic signed id_token produced by what it calls JWT simulation. That is the part worth pausing on. A synthetic token is not the token ChatGPT issued; it is constructed to satisfy whatever shape Codex validates. The README does not document how long such a token remains acceptable, whether Codex re-validates it against the server on each run, or what happens when the underlying session expires. The permission list is deliberately small: downloads and https://chatgpt.com/. The README states there are no external CDN libraries and that all assets are bundled locally, so background.js and popup.js can be read in full with the browser developer tools. That is a real property you can verify yourself, and it is the strongest argument the project makes.

## Installing Codex Auth Helper from source and exporting your first auth.json

There is no store listing and no packaged release in the repository, so installation is the developer-mode path the README gives. Clone the repository, then open Chrome and go to the extensions page. Turn on Developer mode, click Load unpacked, and select the extension folder, the one containing manifest.json. The README notes the version badge points at extension/manifest.json, so that directory is the extension root.

```bash
git clone https://github.com/zhishile/codex-auth-helper.git
```

After cloning, the repository root contains .gitignore, README.md, extension/ and landing-page/. Only extension/ is loaded into Chrome.

```text
chrome://extensions/
```

Enter that address, enable Developer mode, click Load unpacked, and choose the extension directory. The README then says to find Codex Auth Helper behind the puzzle-piece icon in the toolbar and pin it. Before exporting, confirm you are signed in at chatgpt.com in the same browser profile. Open the popup; it should show your avatar, email and plan, plus the countdown to token expiry. If it reports no session, the README mentions a one-click button to go to the login page. When the status reads as detected, click the button to generate and save auth.json and the file downloads. The README does not state where Chrome places the file or what the download filename is beyond auth.json.

## Where Codex Auth Helper stops being the right tool

The extension has no account switching. The related searches around Codex account switchers describe a different kind of tool, and nothing in this README suggests the extension stores more than the session currently active in your browser profile. If you juggle several ChatGPT accounts, this does not help. The second limitation is lifecycle. The popup counts down to token expiry, which implies the exported auth.json has a shelf life, but the README never says what to do when it lapses. There is no documented refresh command, no re-export reminder, and no note on whether Codex fails loudly or silently when the synthetic token goes stale. Third, the trust model is entirely local but also entirely manual. You are loading unpacked code that reads your ChatGPT session and writes a credential file to disk. The README tells you to inspect background.js and popup.js, and that is not a formality: an unpacked extension does not receive Chrome Web Store review, and updates arrive only when you pull the repository again. The last push to the default branch was on 2026-06-07, and the only release listed is v1.0.0 from 2026-06-03. That is a single-version project, so treat it as something you audit rather than something you trust on reputation.

## How this differs from logging in through the Codex CLI itself

The obvious alternative is the CLI's own login flow, which writes auth.json for you without a browser extension in the loop. The trade-off is where the credential originates. A CLI login is a first-party path: the token comes from the provider through the tool that will use it, and refresh behaviour is the CLI's responsibility. Codex Auth Helper instead harvests a session that already exists in Chrome and reshapes it into the file Codex wants, which is faster when you are already signed in and slower to reason about when something breaks, because the failure could sit in the browser session, the synthetic token construction, or the Codex validator. A second alternative is writing auth.json by hand from your own session data. That avoids installing anything, but it is exactly the manual JSON assembly this project exists to remove, and it is no safer if you do not know the required structure. The extension's advantage over both is the detection UI: showing plan and expiry before you export is a genuine convenience that neither a CLI prompt nor a text editor gives you.

## Maintenance, updates and what the MIT licence actually covers

The README states the project is released under the MIT License and permits modification and redistribution provided the original attribution and licence notice are kept. The LICENSE file is referenced from the README and the version badge links to extension/manifest.json, but the top-level repository entries listed are .gitignore, README.md, extension/ and landing-page/, so confirm the LICENSE file exists in the tree before you rely on that grant. MIT is permissive and imposes no obligation on your own code; it also gives you no warranty, which matters more than usual here because the artifact is a credential file. Upgrades are manual by design. Because installation is unpacked, you update by pulling the repository and reloading the extension from chrome://extensions/, and the README does not describe any rollback path if a newer commit breaks export. With one release, v1.0.0, and no changelog in the repository, there is no upgrade history to inspect. Pin a commit you have read if you intend to keep using it.

## What to check before you let it write a credential file

Read extension/manifest.json first and confirm the permissions are only downloads and https://chatgpt.com/, as the README claims. Then read background.js and popup.js end to end; the README says there are no external CDN dependencies, so a complete reading is feasible in one sitting. Watch the network panel while you export and confirm nothing leaves the machine. Check the downloaded auth.json against whatever your Codex version accepts, and note the expiry the popup showed so you know when to expect trouble. If you cannot sign in to chatgpt.com in the same Chrome profile you run the extension in, the tool has nothing to read and you should use the CLI login instead. The README does not document a rollback, a token refresh procedure, or a supported installation channel, so plan around those gaps rather than assuming they are handled.

## Conclusion

Adopt it if you already run the Codex CLI on a machine where you are signed into chatgpt.com in Chrome and you want an auth.json without hand-assembling one. Do not adopt it if you need multi-account switching, a documented token refresh path, or a supported install channel; the README describes only developer-mode loading from the extension folder, and the repository ships no release artifacts or store listing. Before trusting it, open extension/background.js and extension/popup.js and confirm the only network host in the manifest is https://chatgpt.com/, then check that the downloaded file is accepted by your Codex build.

## FAQ

### How do I authenticate Codex with Codex Auth Helper?

Sign in to chatgpt.com in Chrome, open the extension popup, and confirm it detects your avatar, email and plan. Click the button to generate and save auth.json, and the file downloads for Codex to use.

### What is Codex Mobile used for?

The README does not mention a mobile client or any mobile use case. Codex Auth Helper is a Chrome extension that runs on the desktop browser and writes a local auth.json file.

### Does Codex Auth Helper upload my ChatGPT credentials anywhere?

The README states the extension performs 100% local offline processing, declares only the downloads and https://chatgpt.com/ permissions, and bundles all assets locally with no external CDN libraries. It says the generated config is delivered as a data: URL download rather than a temporary Blob.

### How do I install Codex Auth Helper?

Clone the repository, open chrome://extensions/, enable Developer mode, click Load unpacked, and select the extension folder containing manifest.json. The README does not list a Chrome Web Store package.

### What happens when the token in auth.json expires?

The popup shows a countdown to the token expiry time, but the README does not document a refresh procedure or what Codex does once the exported token lapses. Re-exporting from a fresh ChatGPT session is the only path the README describes.

## Sources

- [Issues](https://github.com/zhishile/codex-auth-helper/issues)
- [Project website](https://codex.afione.com)
- [README](https://github.com/zhishile/codex-auth-helper/blob/main/README.md)
- [Releases](https://github.com/zhishile/codex-auth-helper/releases)
- [zhishile/codex-auth-helper on GitHub](https://github.com/zhishile/codex-auth-helper)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zhishile-codex-auth-helper