# Installation

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

- 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/deobfuscate-javascript/package.json`
- `.agents/skills/deobfuscate-javascript/tsconfig.json`
- `.agents/skills/codex-app-ref-refresh/scripts/refresh-codex-ref.mjs`
- `.agents/skills/codex-app-ref-refresh/SKILL.md`

---

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

decode-codex is a macOS-only workflow: extract the installed Codex desktop app into `./ref` with Node.js, then run TypeScript restoration scripts under `.agents/skills/deobfuscate-javascript/` with Bun. First-time setup installs Bun skill dependencies once; the refresh skill pulls `@electron/asar` and Prettier on demand via `npx`.

## Platform requirements

| Requirement | Role |
| ----------- | ---- |
| **macOS** | Codex ships as a macOS desktop app; extraction reads its `app.asar` bundle. |
| **[Codex desktop app](https://chatgpt.com/codex)** at `/Applications/Codex.app` | Source for `Contents/Resources/app.asar`. Override with `CODEX_APP_ASAR` when the bundle lives elsewhere. |
| **Node.js** | Runs `refresh-codex-ref.mjs` and shells out to `npx @electron/asar` and `npx prettier`. |
| **[Bun](https://bun.sh)** | Executes the deobfuscate-javascript TypeScript scripts (`bun scripts/*.ts`). |
| **Agent harness** (optional) | Claude Code, Codex, or any agent that reads `.agents/skills/`. Scripts can also be run by hand. |

<Warning>
Extracted and restored Codex source is for personal study and interoperability research. Do not redistribute extracted or restored code.
</Warning>

## What installs where

The repository has no root `package.json`. Dependencies are scoped to the deobfuscate skill; the refresh skill uses on-demand `npx` tools.

:::files
decode-codex/
├─ .agents/skills/
│  ├─ codex-app-ref-refresh/     # Node only — no bun install
│  │  └─ scripts/refresh-codex-ref.mjs
│  └─ deobfuscate-javascript/     # Bun + Babel — run bun install here
│     ├─ package.json
│     ├─ scripts/*.ts
│     └─ node_modules/            # created by bun install
├─ ref/                           # generated by refresh (gitignored)
└─ restored/                      # generated by deobfuscation (gitignored)
:::

| Location | Installed by | Contents |
| -------- | ------------ | -------- |
| `.agents/skills/deobfuscate-javascript/node_modules/` | `bun install` | `@babel/generator`, `@babel/parser`, `@babel/traverse`, `@babel/types`, and dev types |
| `ref/node_modules/` | Codex `app.asar` extraction | Bundled Electron app dependencies (not managed by this repo) |
| Ephemeral `npx` cache | Refresh and script wrappers | `@electron/asar`, `prettier`, `@wakaru/cli`, `webcrack`, `source-map-explorer` as invoked |

## Runtime prerequisites

### Node.js (refresh skill)

The refresh script is a plain Node ESM module. It requires:

- `node` on `PATH`
- `npx` for `@electron/asar extract` and Prettier formatting

Default asar path:

```
/Applications/Codex.app/Contents/Resources/app.asar
```

<ParamField body="CODEX_APP_ASAR" type="string">
Override the source asar path when Codex.app is not at the default location.
</ParamField>

### Bun (deobfuscate-javascript skill)

All pipeline scripts under `.agents/skills/deobfuscate-javascript/scripts/` run with `bun`. The skill's `tsconfig.json` targets `esnext`, uses `moduleResolution: "bundler"`, and includes only `scripts/**/*.ts`.

`package.json` declares Babel as runtime dependencies and `bun-types` as a dev dependency. External binaries (`prettier`, `@wakaru/cli`, `webcrack`) are **not** listed in `package.json`; wrappers invoke them via `npx`/`bunx` and degrade gracefully when absent.

## First-time setup

<Steps>
<Step title="Clone the repository">

```bash
git clone https://github.com/JimLiu/decode-codex.git
cd decode-codex
```

Work from the repository root for all subsequent steps. The refresh script requires `./ref` to resolve under the current working directory.

</Step>

<Step title="Install Codex.app on macOS">

Install the [Codex desktop app](https://chatgpt.com/codex) so it lands at `/Applications/Codex.app`.

Verify the asar bundle exists:

```bash
test -f /Applications/Codex.app/Contents/Resources/app.asar && echo "asar found"
```

If Codex is installed elsewhere, note the path for `CODEX_APP_ASAR`.

</Step>

<Step title="Install Node.js and Bun">

Install Node.js (any recent LTS or current release with `npx` support) and [Bun](https://bun.sh).

Verify both runtimes:

```bash
node --version
bun --version
```

</Step>

<Step title="Install deobfuscate-javascript dependencies">

From the repository root:

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

This installs the Babel packages the scripts import. Re-run after pulling skill dependency changes.

Optional sanity check:

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

</Step>

<Step title="Verify refresh prerequisites (dry run)">

From the repository root, confirm paths resolve without modifying `./ref`:

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

<RequestExample>

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

</RequestExample>

<ResponseExample>

```text
Workspace: /path/to/decode-codex
Source asar: /Applications/Codex.app/Contents/Resources/app.asar
Target ref: /path/to/decode-codex/ref
Dry run only; no files changed.
```

</ResponseExample>

</Step>

<Step title="Point your agent at the repository (optional)">

Skills live under `.agents/skills/`. Configure your agent harness to read that directory, then invoke by skill name:

- `codex-app-ref-refresh` — sync `./ref` from Codex.app
- `deobfuscate-javascript` — restore `./ref` into `./restored/`

The codex-app-ref-refresh skill also ships an OpenAI agent interface at `.agents/skills/codex-app-ref-refresh/agents/openai.yaml` with display name **Codex App Ref Refresh**.

</Step>
</Steps>

## Dependency tiers

| Tier | Tools | Install method | Required for |
| ---- | ----- | -------------- | ------------ |
| **Core** | Node.js, Bun, Codex.app | OS / manual install | Any end-to-end run |
| **Skill-local** | Babel packages | `bun install` in deobfuscate-javascript | All `bun scripts/*.ts` commands |
| **On-demand** | `@electron/asar`, `prettier` | `npx -y` from refresh script | `./ref` extraction and formatting |
| **Optional** | `@wakaru/cli@1.5.0`, `webcrack`, `source-map-explorer` | `npx` from script wrappers | Better normalization and bundle pre-split; auto-skipped when unavailable |

<Tip>
You do not need to pre-install `@electron/asar` or Prettier. The refresh script and format wrappers fetch them via `npx` on first use.
</Tip>

## Agent vs manual execution

| Mode | Refresh | Deobfuscate |
| ---- | ------- | ----------- |
| **Agent** | Ask: *Use codex-app-ref-refresh to refresh `./ref` from the installed Codex app.* | Ask: *Use deobfuscate-javascript to restore `./ref`.* |
| **Manual** | `node .agents/skills/codex-app-ref-refresh/scripts/refresh-codex-ref.mjs` | `bun .agents/skills/deobfuscate-javascript/scripts/<script>.ts …` (agent normally orchestrates) |

Manual deobfuscation is possible but the skill expects an agent for semantic renaming in Stage 2 and acceptance review in deep mode.

## Verification checklist

After setup, confirm:

| Check | Expected signal |
| ----- | --------------- |
| Bun deps installed | `.agents/skills/deobfuscate-javascript/node_modules/@babel/parser` exists |
| Dry run succeeds | Prints `Workspace`, `Source asar`, `Target ref`, and `Dry run only; no files changed.` |
| Asar reachable | No `Error: asar file not found` from refresh |
| Refresh cwd guard | Running refresh outside the repo root fails with `ref directory must resolve to ./ref under the current working directory` |

A full extraction run (not just dry-run) additionally logs Prettier formatting lines and ends with `Codex app ref refresh complete.` — see [Refresh Codex reference source](/refresh-codex-ref).

## Troubleshooting

<AccordionGroup>
<Accordion title="Error: asar file not found">

Codex.app is missing or not at the default path. Install Codex or set the override:

```bash
CODEX_APP_ASAR=/path/to/app.asar node .agents/skills/codex-app-ref-refresh/scripts/refresh-codex-ref.mjs --dry-run
```

</Accordion>

<Accordion title="ref directory must resolve to ./ref under the current working directory">

The refresh script only replaces `./ref` relative to the current working directory. `cd` to the decode-codex repository root before running it.

</Accordion>

<Accordion title="bun: command not found or script import errors">

Install Bun and run `bun install` inside `.agents/skills/deobfuscate-javascript`. Stage 2 docs also gate on `cd <skill-dir> && bun install` before creating per-chunk workspaces.

</Accordion>

<Accordion title="npx @electron/asar or prettier failed to start">

Confirm Node.js and network access for first-time `npx -y` downloads. Corporate proxies may block registry access.

</Accordion>

<Accordion title="Prettier skips ref/ files during manual checks">

`ref/` is gitignored. Prettier 3 honors `.gitignore` by default. The refresh script passes `--ignore-path /dev/null` to bypass ignore files. Use the same flag for manual verification.

</Accordion>
</AccordionGroup>

## What is not part of installation

- **No `bun install` at the repository root** — only inside the deobfuscate-javascript skill directory.
- **No install step for codex-app-ref-refresh** — it is a single `.mjs` script plus skill metadata.
- **No committed `ref/` or `restored/`** — both are generated artifacts listed in `.gitignore`.
- **No API keys or model-provider setup** — the deobfuscate skill uses the host agent for renaming, not an external LLM API.

## Next

<CardGroup>
<Card title="Quickstart" href="/quickstart">
Run the first successful refresh and deobfuscation pass; verify `./ref` and `./restored/` output.
</Card>
<Card title="Overview" href="/overview">
Two skills, artifact roots, and the shortest path from Codex.app to readable source.
</Card>
<Card title="External tools and dependencies" href="/external-tools-and-dependencies">
Full list of Bun, Babel, and subprocess tools with graceful-degradation behavior.
</Card>
<Card title="Refresh Codex reference source" href="/refresh-codex-ref">
Operational guide for running codex-app-ref-refresh after installation.
</Card>
</CardGroup>