# decode-codex Documentation

> Reference for extracting the installed Codex.app bundle into ./ref and reverse-engineering its minified JavaScript into readable, typed source under ./restored using two agent skills and bundled Bun/Node scripts.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33)
- [GitHub repository](https://github.com/JimLiu/decode-codex)

## Repository

- Repository: JimLiu/decode-codex

- Generated: 2026-06-27T21:23:39.455Z
- Updated: 2026-06-28T00:40:55.317Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 20

## Pages

- [Overview](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/01-overview.md): What decode-codex exposes: two agent skills (codex-app-ref-refresh and deobfuscate-javascript), the ./ref and ./restored artifact roots, runtime prerequisites, and the shortest end-to-end path from installed Codex.app to readable source.
- [Installation](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/02-installation.md): Prerequisites and first-time setup: macOS Codex.app at /Applications/Codex.app, Node.js for asar extraction, Bun for deobfuscation scripts, and bun install inside the deobfuscate-javascript skill directory.
- [Quickstart](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/03-quickstart.md): First successful run: refresh ./ref from Codex.app, invoke deobfuscate-javascript on ref/webview/assets, and verify formatted output under restored/ with expected log lines and directory layout.
- [Restoration pipeline](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/04-restoration-pipeline.md): Stage 1 deobfuscation, Stage 2 rename and polish, and Stage 3 semantic finalize; readable vs deep depth; whole-tree vs single-file scope; and the restoration contract that defines done.
- [Workspace and output conventions](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/05-workspace-and-output-conventions.md): Per-chunk staging under restored/.deobfuscate-javascript/, the promote bar for deliverables, semantic-domain subfolders, kebab-case filenames, provenance headers, and the shared restored/IMPORT_MAP.json contract.
- [Import graph and boundaries](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/06-import-graph-and-boundaries.md): manifest.json and ledger.json orchestration, terminal chunk kinds (npm-leaf, oversized-local, external, faced-boundary), facade lifecycle, and quality-gate coverage rules for whole-tree restores.
- [Codex project profile](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/07-codex-project-profile.md): Layout of the extracted openai-codex-electron bundle: ref/webview/index.html entry discovery, ref/webview/assets chunk root, npm-leaf and Pierre vendor boundaries, and default deep-restore command frame for this repository.
- [Refresh Codex reference source](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/08-refresh-codex-reference-source.md): Run codex-app-ref-refresh to delete and recreate ./ref from Codex.app Contents/Resources/app.asar, format extracted JS/CSS with Prettier, and verify completion signals before deobfuscation.
- [Deobfuscate a single file](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/09-deobfuscate-a-single-file.md): Readable-tier workflow for lone minified snippets or isolated chunks: sourcemap-check, wakaru-normalize, extract, smart-rename, polish --fast, format, and promote a single deliverable without import-graph orchestration.
- [Full tree restoration](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/10-full-tree-restoration.md): Deep default workflow for index.html plus asset trees: entry discovery, build-import-graph, build-symbol-ledger, auto-restore-full checkpoints, plan-organize, promote-organized, and quality-gate over the whole target.
- [Handle obfuscated input](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/11-handle-obfuscated-input.md): Stage 1 workflow for packed, encoded, or Obfuscator.IO input: detect, unpack, string-array, decode-strings, simplify, control-flow-report, and critical ordering before Stage 2 rename.
- [Delta restore and resume](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/12-delta-restore-and-resume.md): Continue an in-progress restoration: inspect manifest.json, ledger.json, and IMPORT_MAP.json; run delta/boundary replacement for a scoped chunk; and avoid rebuilding the whole reachable graph.
- [Refresh script reference](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/13-refresh-script-reference.md): refresh-codex-ref.mjs flags (--dry-run, --skip-format), CODEX_APP_ASAR override, safety guards on ./ref replacement, Prettier verification passes, and expected stdout completion lines.
- [Stage 1 scripts reference](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/14-stage-1-scripts-reference.md): CLI signatures and behavior for detect, unpack, string-array, decode-strings, simplify, control-flow-report, and the deobfuscate.ts orchestrator with --skip and --stop-after controls.
- [Stage 2 scripts reference](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/15-stage-2-scripts-reference.md): Rename and polish script reference: sourcemap-check, wakaru-normalize, extract filters, smart-rename, apply, polish flags (--rename, --fast, --format), and deep-mode import-resolution passes.
- [Orchestration scripts reference](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/16-orchestration-scripts-reference.md): Full-restoration CLI reference: check-entry exit codes, build-import-graph flags, ledger subcommands, auto-restore-full, plan-organize, promote-organized, quality-gate checks, and semantic-finalize recipes.
- [External tools and dependencies](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/17-external-tools-and-dependencies.md): Bun and Babel package dependencies, subprocess tools (@electron/asar, prettier, @wakaru/cli, webcrack, source-map-explorer), BSD-style script exit codes, and graceful degradation when binaries are absent.
- [Quality bar and anti-patterns](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/18-quality-bar-and-anti-patterns.md): Readable and deep-tier completion criteria, naming anti-patterns (program-scope-only rename, mechanical fallback names, checkpoint promotion), Stage 3 acceptance categories E1–E4, and quality-gate failure modes.
- [Pipeline caveats](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/19-pipeline-caveats.md): Ordering rules, eval safety in unpack, sourcemap precedence, polish tier differences, Prettier gitignore traps, wakaru caveats, vendor-leaf entry misidentification, and other documented failure modes with recovery steps.
- [Maintaining the skill](https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/pages/20-maintaining-the-skill.md): Self-improvement protocol for deobfuscate-javascript: when to update CHUNK_NAME_REGISTRY, fix scripts with tests, append caveats or codex-ref notes, commit discipline, and legal constraints on extracted Codex source.

## Source Files

- `.agents/skills/codex-app-ref-refresh/agents/openai.yaml`
- `.agents/skills/codex-app-ref-refresh/scripts/refresh-codex-ref.mjs`
- `.agents/skills/codex-app-ref-refresh/SKILL.md`
- `.agents/skills/deobfuscate-javascript/package.json`
- `.agents/skills/deobfuscate-javascript/reference/bundler-runtimes.md`
- `.agents/skills/deobfuscate-javascript/reference/caveats.md`
- `.agents/skills/deobfuscate-javascript/reference/codex-ref.md`
- `.agents/skills/deobfuscate-javascript/reference/examples.md`
- `.agents/skills/deobfuscate-javascript/reference/naming-heuristics.md`
- `.agents/skills/deobfuscate-javascript/scripts/acceptance-checklist.md`
- `.agents/skills/deobfuscate-javascript/scripts/apply.ts`
- `.agents/skills/deobfuscate-javascript/scripts/auto-restore-full.ts`
- `.agents/skills/deobfuscate-javascript/scripts/build-import-graph.ts`
- `.agents/skills/deobfuscate-javascript/scripts/build-symbol-ledger.ts`
- `.agents/skills/deobfuscate-javascript/scripts/check-entry.ts`
- `.agents/skills/deobfuscate-javascript/scripts/chunk-classification.ts`
- `.agents/skills/deobfuscate-javascript/scripts/control-flow-report.ts`
- `.agents/skills/deobfuscate-javascript/scripts/decode-strings.ts`
- `.agents/skills/deobfuscate-javascript/scripts/deobfuscate.ts`
- `.agents/skills/deobfuscate-javascript/scripts/detect.ts`
- `.agents/skills/deobfuscate-javascript/scripts/extract.ts`
- `.agents/skills/deobfuscate-javascript/scripts/format.ts`
- `.agents/skills/deobfuscate-javascript/scripts/ledger.ts`
- `.agents/skills/deobfuscate-javascript/scripts/make-facade.ts`
- `.agents/skills/deobfuscate-javascript/scripts/plan-organize.ts`
- `.agents/skills/deobfuscate-javascript/scripts/polish.ts`
- `.agents/skills/deobfuscate-javascript/scripts/prepare-stage-e-review.ts`
- `.agents/skills/deobfuscate-javascript/scripts/promote-final.ts`
- `.agents/skills/deobfuscate-javascript/scripts/promote-organized.ts`
- `.agents/skills/deobfuscate-javascript/scripts/quality-gate.test.ts`
- `.agents/skills/deobfuscate-javascript/scripts/quality-gate.ts`
- `.agents/skills/deobfuscate-javascript/scripts/resolve-npm-imports.ts`
- `.agents/skills/deobfuscate-javascript/scripts/semantic-finalize.ts`
- `.agents/skills/deobfuscate-javascript/scripts/simplify.ts`
- `.agents/skills/deobfuscate-javascript/scripts/smart-rename.ts`
- `.agents/skills/deobfuscate-javascript/scripts/sourcemap-check.ts`
- `.agents/skills/deobfuscate-javascript/scripts/string-array.ts`
- `.agents/skills/deobfuscate-javascript/scripts/unpack.ts`
- `.agents/skills/deobfuscate-javascript/scripts/verify-stage-e-results.ts`
- `.agents/skills/deobfuscate-javascript/scripts/wakaru-normalize.ts`
- `.agents/skills/deobfuscate-javascript/SKILL.md`
- `.agents/skills/deobfuscate-javascript/stages/stage-1-deobfuscate.md`
- `.agents/skills/deobfuscate-javascript/stages/stage-2-restore.md`
- `.agents/skills/deobfuscate-javascript/stages/stage-3-finalize.md`
- `.agents/skills/deobfuscate-javascript/stages/workspace.md`
- `.agents/skills/deobfuscate-javascript/tsconfig.json`
- `.agents/skills/deobfuscate-javascript/workflows/full-obfuscation.md`
- `.agents/skills/deobfuscate-javascript/workflows/full-restoration.md`
- `.agents/skills/deobfuscate-javascript/workflows/huge-single-file.md`
- `.agents/skills/deobfuscate-javascript/workflows/react-vite.md`
- `.agents/skills/deobfuscate-javascript/workflows/small-minified.md`
- `.agents/skills/deobfuscate-javascript/workflows/webpack-bundle.md`
- `.gitignore`
- `README.md`
- `restored/app-shell/thread-app-shell-chrome-entry.ts`
- `restored/app-shell/thread-handoff-operations/index.ts`
- `restored/browser/browser-use-settings/index.tsx`
- `restored/composer/composer-footer-branch-switcher/branch-switcher.tsx`
- `restored/composer/project-selector/project-selector.tsx`
- `restored/runtime/vite-browser-external.ts`
- `restored/ui/tooltip-b/index.tsx`