# Overview

> 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.

- Repository: JimLiu/decode-codex
- GitHub: https://github.com/JimLiu/decode-codex
- Human docs: https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33
- Complete Markdown: https://grok-wiki.com/public/docs/jimliu-decode-codex-1a3a0c425b33/llms-full.txt

## Source Files

- `README.md`
- `.agents/skills/codex-app-ref-refresh/SKILL.md`
- `.agents/skills/deobfuscate-javascript/SKILL.md`
- `.gitignore`
- `.agents/skills/codex-app-ref-refresh/agents/openai.yaml`

---

---
title: "Overview"
description: "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."
---

decode-codex is a skill-pack repository that turns the installed macOS **Codex.app** bundle into readable source. It ships two agent skills under `.agents/skills/` — `codex-app-ref-refresh` and `deobfuscate-javascript` — that write generated artifacts into `./ref` (extracted app code) and `./restored` (deobfuscated deliverables). Neither directory is version-controlled; both are regenerated by running the skills.

## What this repository exposes

| Surface | Location | Role |
| ------- | -------- | ---- |
| **codex-app-ref-refresh** | `.agents/skills/codex-app-ref-refresh/` | Extracts `Codex.app/Contents/Resources/app.asar` into `./ref` and formats extracted `.js`/`.css` with Prettier |
| **deobfuscate-javascript** | `.agents/skills/deobfuscate-javascript/` | Reverse-engineers bundled JS from `./ref` into readable, well-named source under `./restored/` |
| **Refresh script** | `.agents/skills/codex-app-ref-refresh/scripts/refresh-codex-ref.mjs` | Direct CLI entry when no agent harness is available |
| **Deobfuscation scripts** | `.agents/skills/deobfuscate-javascript/scripts/*.ts` | Bun-run TypeScript tools orchestrated by the agent during restoration |

The typical workflow is linear: **refresh `./ref` from the app → deobfuscate `./ref` into `./restored`**.

```mermaid
flowchart LR
  subgraph source["Installed app"]
    ASAR["/Applications/Codex.app<br/>Contents/Resources/app.asar"]
  end

  subgraph skill1["codex-app-ref-refresh"]
    EXTRACT["@electron/asar extract"]
    PRETTY["Prettier format"]
  end

  subgraph refRoot["./ref (generated)"]
    HTML["ref/webview/index.html"]
    ASSETS["ref/webview/assets/"]
  end

  subgraph skill2["deobfuscate-javascript"]
    STAGE["Stage 1–3 pipeline"]
    STAGE_WS["restored/.deobfuscate-javascript/"]
  end

  subgraph restoredRoot["./restored (generated)"]
    SEM["Semantic subfolders"]
    MAP["IMPORT_MAP.json"]
  end

  ASAR --> EXTRACT --> refRoot
  EXTRACT --> PRETTY
  ASSETS --> STAGE --> STAGE_WS
  STAGE_WS -->|"organize → promote"| SEM
  STAGE --> MAP
```

## Artifact roots

### `./ref` — extracted Codex app source

`codex-app-ref-refresh` deletes and recreates `./ref` on every run. The bundled web UI lives at:

- Entry: `ref/webview/index.html`
- Chunks: `ref/webview/assets/`

The refresh script refuses to run unless the target resolves to `./ref` under the current working directory, and it skips `ref/node_modules` during Prettier passes.

### `./restored` — readable deliverables

`deobfuscate-javascript` writes finalized files into `./restored/` with:

- Semantic-domain subfolders (`app-shell/`, `composer/`, `utils/`, `icons/`, …)
- kebab-case filenames and PascalCase React component identifiers
- Provenance headers (`// Restored from <path>`)
- A shared `restored/IMPORT_MAP.json` mapping original chunk basenames to public paths

Batch and script output never lands directly in `./restored`. Mechanical checkpoints stage under `restored/.deobfuscate-javascript/` (for example `_full/checkpoints/` or per-chunk workspaces) and promote only after the agent organizes them.

<Note>
Both `ref/` and `restored/` are listed in `.gitignore`. Regenerate them with the skills rather than editing by hand or committing them.
</Note>

## Runtime prerequisites

| Requirement | Used by | Purpose |
| ----------- | ------- | ------- |
| **macOS** with **Codex.app** at `/Applications/Codex.app` | `codex-app-ref-refresh` | Source `app.asar` for extraction |
| **Node.js** | `codex-app-ref-refresh` | Runs `refresh-codex-ref.mjs`; invokes `npx @electron/asar` and `npx prettier` |
| **[Bun](https://bun.sh)** | `deobfuscate-javascript` | Runs TypeScript restoration scripts |
| **Agent harness** (optional) | Both skills | Any agent that reads `.agents/skills/` — Claude Code, Codex, Grok, or similar. Skills are portable file-based instructions, not tied to a specific model provider. |

First-time setup for deobfuscation scripts:

```bash
cd .agents/skills/deobfuscate-javascript
bun install
```

## Shortest end-to-end path

<Steps>
<Step title="Install prerequisites">

Confirm Codex.app is installed at `/Applications/Codex.app`, Node.js and Bun are available, and deobfuscation script dependencies are installed (`bun install` inside `.agents/skills/deobfuscate-javascript`).

</Step>

<Step title="Refresh ./ref from Codex.app">

From the repository root:

```bash
node .agents/skills/codex-app-ref-refresh/scripts/refresh-codex-ref.mjs
```

Or ask your agent:

> Use **codex-app-ref-refresh** to refresh `./ref` from the installed Codex app.

Verify completion signals in stdout:

```
Formatting N JS/CSS file(s) with Prettier, ignoring git/prettier ignore files...
Prettier verification complete.
Codex app ref refresh complete.
```

Spot-check that files under `ref/webview/assets/` are multi-line (Prettier-formatted), not single minified lines.

</Step>

<Step title="Deobfuscate ./ref into ./restored">

After `./ref` exists, invoke the deobfuscation skill:

> Use **deobfuscate-javascript** to restore `./ref`.

For this repository, the default bundled-code root is `ref/webview/assets`. The skill auto-discovers the app entry from `ref/webview/index.html` and restores the reachable import tree.

</Step>

<Step title="Verify restored output">

Confirm deliverables under `restored/` with semantic folder layout, kebab-case filenames, and an updated `restored/IMPORT_MAP.json`. For a whole-tree deep restore, `quality-gate.ts` over the target directory must pass before the restore is complete.

</Step>
</Steps>

## Restoration depth at a glance

The deobfuscation skill operates on two independent axes: **scope** (single file vs whole import tree) and **depth** (readable vs deep).

| Axis | Default | Output |
| ---- | ------- | ------ |
| **Scope** | Whole tree from `index.html` | Every reachable project-local chunk under `ref/webview/assets/` |
| **Depth** | Deep for whole-tree restores | Typed `.tsx`, npm-import resolution, import-graph orchestration, acceptance review |
| **Readable opt-out** | Triggered by "quick" / "readable" / "快速", or a lone pasted snippet | Well-named untyped JS/TSX — naming quality is the hard bar |

The per-chunk pipeline runs three stages:

1. **Stage 1 — Deobfuscation** (only if input is obfuscated): unpack, decode strings, simplify control flow.
2. **Stage 2 — Restore to readable**: `smart-rename` + agent hand-naming, then reading-aid polish (`polish.ts --fast`).
3. **Stage 3 — Finalize** (deep mode only): semantic typed rewrite, directory organization, acceptance review.

<Info>
For the Codex project profile in this repo, load `reference/codex-ref.md` inside the deobfuscate skill before choosing a workflow. Vendor npm chunks and bundled data (Shiki grammars, 3Dmol) are detected as terminal `npm-leaf` nodes and left as bare npm imports rather than restored into `./restored/`.
</Info>

## Invoke skills with or without an agent

Skills live under `.agents/skills/` and are provider-neutral: any agent harness that reads skill files can invoke them by name. You can also run bundled scripts directly.

**Via agent** (recommended for deobfuscation — the agent performs semantic renaming):

```
Use codex-app-ref-refresh to refresh ./ref from the installed Codex.app asar and format extracted JS/CSS.
```

```
Use deobfuscate-javascript to restore ./ref.
```

**Via CLI** (refresh only; deobfuscation requires agent orchestration for naming):

<ParamField body="--dry-run" type="flag">
Print resolved paths without deleting or extracting `./ref`.
</ParamField>

<ParamField body="--skip-format" type="flag">
Extract only; skip Prettier formatting. Treat as incomplete unless intentional.
</ParamField>

<ParamField body="CODEX_APP_ASAR" type="string">
Override the default `/Applications/Codex.app/Contents/Resources/app.asar` path.
</ParamField>

## Repository layout

:::files
decode-codex/
├─ .agents/skills/
│  ├─ codex-app-ref-refresh/      # Skill 1: Codex.app → ./ref
│  │  ├─ SKILL.md
│  │  ├─ agents/openai.yaml
│  │  └─ scripts/refresh-codex-ref.mjs
│  └─ deobfuscate-javascript/     # Skill 2: ./ref → ./restored
│     ├─ SKILL.md
│     ├─ scripts/*.ts
│     ├─ workflows/
│     ├─ stages/
│     └─ reference/codex-ref.md
├─ ref/                           # Generated: extracted Codex app (gitignored)
└─ restored/                      # Generated: readable output (gitignored)
:::

## Legal and ethical constraints

<Warning>
This project is for **personal study and interoperability research** of software you have installed. Extracted code is © OpenAI. Respect the Codex app's license and terms of service. Do not redistribute extracted or restored code.
</Warning>

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Prerequisites and first-time setup: Codex.app, Node.js, Bun, and `bun install` in the deobfuscate skill directory.
</Card>
<Card title="Quickstart" href="/quickstart">
First successful run from refresh through deobfuscation with expected log lines and directory layout.
</Card>
<Card title="Restoration pipeline" href="/restoration-pipeline">
Stage 1–3 workflow, readable vs deep depth, whole-tree vs single-file scope, and the restoration contract.
</Card>
<Card title="Refresh Codex reference" href="/refresh-codex-ref">
Run `codex-app-ref-refresh`, verify Prettier completion, and prepare `./ref` for deobfuscation.
</Card>
<Card title="Codex project profile" href="/codex-project-profile">
Layout of the extracted `openai-codex-electron` bundle and default restore targets for this repository.
</Card>
</CardGroup>