Codex App Parity Skill

Use this skill for any feature work or user-visible behavior/UI change in this repository. Do not use it for purely internal refactors that do not affect behavior.

Objective

Ensure behavior is implemented with Codex.app as the source of truth, then verified with headless Playwright and screenshots.

Project Instructions

Codex.app-First Development Policy

For every new feature and every behavior/UI change, treat the installed desktop app as the source of truth:

• App path: /Applications/Codex.app
• Primary bundle to inspect: /Applications/Codex.app/Contents/Resources/app.asar

Do not implement first and compare later. Compare first, then implement.

How to Search for Features in Codex.app

Extraction

Extract the app bundle once (reuse if already extracted):

mkdir -p /tmp/codex-app-extracted
npx asar extract "/Applications/Codex.app/Contents/Resources/app.asar" /tmp/codex-app-extracted

Key Directories

Searching the Minified Bundle

The main UI bundle is a single large minified JS file at webview/assets/index-*.js. Use Python to search since grep -o with large repeat counts fails on macOS:

python3 -c "
with open('/tmp/codex-app-extracted/webview/assets/index-<hash>.js', 'r') as f:
    content = f.read()
idx = content.find('YOUR_SEARCH_TERM')
if idx >= 0:
    print(content[max(0, idx-200):idx+500])
"

What to Search For

1. i18n keys: Search locale files (webview/assets/zh-TW-*.js, webview/assets/en-*.js, etc.) for human-readable labels. Keys follow the pattern component.feature.property (e.g., composer.dictation.tooltip).
2. Component functions: Minified React components follow patterns like function X4n({prop1:t,prop2:e,...}). Search for the feature's i18n key to find the component that renders it.
3. API calls and endpoints: Search main process files (.vite/build/main-*.js) for endpoint URLs, auth handling, and IPC channels. Key patterns:
   • prodApiBaseUrl → production API base (e.g., https://chatgpt.com/backend-api)
   • devApiBaseUrl → dev API base (e.g., http://localhost:8000/api)
   • fetch-request / fetch-response → IPC-proxied HTTP calls from renderer to main process
4. Icon names: Search for icon imports like audiowave-dark.svg, book-open-dark.svg. Icon mapping is in the main bundle around the Hwn=Object.assign({ pattern.
5. Keyboard shortcuts: Search for CmdOrCtrl+, Cmd+, keydown, keyCode, or specific key names.

Search Strategy

1. Start with i18n locale files — they have human-readable labels that identify features.
2. Use the i18n key to find the component in the main bundle.
3. Trace the component to find hooks/composables, API calls, and event handlers.
4. Check the main process bundle for any server-side proxying or Electron IPC handling.

Architecture Notes

• Renderer → Main Process: The renderer uses a Uu HTTP client class that sends fetch-request IPC messages to the main process. The main process class tle handles these, adds auth tokens, and uses electron.net.fetch to make actual HTTP calls.
• Auth: Auth tokens come from the app-server's getAuthStatus RPC method (ChatGPT backend auth).
• App-server: A codex app-server child process communicating via JSON-RPC over stdin/stdout. Our bridge middleware proxies RPC calls to it.
• Config constants: R7 = prodApiBaseUrl (https://chatgpt.com/backend-api), I7 = devApiBaseUrl (http://localhost:8000/api), C7 = originator (Codex Desktop).

Required Workflow (Feature Work)

1. Identify target behavior:

• Restate what behavior is being added/changed.
• Define whether it is: data mapping, runtime event handling, UX text, visual treatment, interaction model, or all of these.

2. Inspect Codex.app before coding:

• Locate the implementation in app.asar (extract and search built assets as needed).
• Find relevant strings/keys/functions/components for the feature (status labels, event names, item types, summaries, collapse/expand behavior, etc.).
• Capture the closest equivalent pattern if exact parity is not present.

3. Build a parity checklist from Codex.app:

• Data model shape (fields used by UI).
• Realtime event sources and transitions.
• Rendering structure (what is shown collapsed vs expanded).
• Copy/text behavior (phrasing and status wording).
• Interaction behavior (auto-expand, auto-collapse, click/keyboard handling).
• Visibility rules (when elements appear/disappear).

4. Implement against that checklist:

• Prefer Codex.app behavior over novel design.
• Keep deviations minimal and intentional.
• If deviating, include a short reason in the final response.

5. Verify parity after implementation:

• Confirm each checklist item.
• Run local build/tests.
• Re-check UI behavior against Codex.app reference.

Response Requirements (When delivering feature changes)

For feature tasks, include:

• Codex.app analysis: what was inspected (files/areas/patterns).
• Parity result: matched items and any explicit deviations.
• Fallback note only if Codex.app could not be inspected or had no equivalent.

Fallback Rules

If Codex.app cannot be inspected (missing app, extraction/search failure) or has no equivalent pattern:

• State the blocker explicitly.
• Use best local implementation consistent with existing repository patterns.
• Keep behavior conservative and avoid speculative UX innovations.

Scope and Safety

• This policy applies to feature behavior and UX decisions, not just styling.
• Bug fixes should still check Codex.app when they affect user-visible behavior.
• Prefer minimal patches that align with app behavior rather than large refactors.

Completion Verification Requirement

• After completing a task that changes behavior or UI, always run a Playwright verification in headless mode.
• Always capture a screenshot of the changed result and display that screenshot in chat when reporting completion.

Self-Improvement Protocol

After each feature implementation session that uses this skill:

1. Record new findings: Append a dated ## Findings: section documenting any newly discovered Codex.app internals (state keys, API endpoints, component patterns, auth flows, etc.).
2. Update search instructions: If new search techniques were used (e.g., a better way to extract minified code, new file locations), update the "How to Search for Features" section.
3. Update architecture notes: If new IPC channels, API endpoints, or data flows were discovered, add them to the Architecture Notes.
4. Keep findings actionable: Each finding should include enough detail that a future session can reuse it without re-discovering.

Findings: Workspace Root Ordering (2026-02-25)

• Codex.app persists workspace root ordering/labels in global state JSON keys:
  • electron-saved-workspace-roots (order source of truth)
  • electron-workspace-root-labels
  • active-workspace-roots
• In this environment, persisted file path is:
  • ~/.codex/.codex-global-state.json
• In packaged desktop runs, equivalent userData path is typically:
  • ~/Library/Application Support/Codex/.codex-global-state.json
• For folder/project reorder parity, prefer reading these keys over browser LocalStorage-only ordering.
• Validation requirement for reorder changes:
  • Run build/typecheck.
  • Run Playwright in headless mode and capture a screenshot showing sidebar order.

Findings: Dictation / Microphone Feature (2026-02-26)

• i18n keys: composer.dictation.* — tooltip is "Hold to dictate", aria is "Dictate".
• Component: M4n React hook handles recording state, audio capture, and transcription.
• Audio pipeline: navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1 } }) → MediaRecorder → chunks → Blob → multipart POST.
• Transcription endpoint: The renderer sends audio to /transcribe via the IPC fetch proxy. The main process (tle class) prepends the prodApiBaseUrl (https://chatgpt.com/backend-api) and attaches ChatGPT auth bearer tokens. Full URL: https://chatgpt.com/backend-api/transcribe.
• Request format: Multipart form-data with boundary ----codex-transcribe-<uuid>, fields: file (audio blob) and optional language. Body is base64-encoded and sent with X-Codex-Base64: 1 header.
• Response: { text: "transcribed text" }.
• Interaction model: Press-and-hold to record → release to stop and transcribe → text inserted into composer. Has "insert" and "send" modes.
• Icon: audiowave-dark.svg / audiowave-light.svg (custom SVG, not from icon library).
• Web app implementation: Our bridge proxies /codex-api/transcribe to the ChatGPT backend using auth tokens from the app-server getAuthStatus RPC. Frontend uses useDictation composable with MediaRecorder API.