# Codexfast Development Flow > Use when iterating on codexfast features, bundle-patch signatures, compatibility gates, recovery behavior, or repo documentation in the codexfast repository. - Skill: `tomevault-io/codexfast-development-flow` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/codexfast-development-flow` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/codexfast-development-flow/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/codexfast-development-flow --- # Codexfast Development Flow ## Overview Use this skill for day-to-day `codexfast` feature work. This repo is high risk because it launches and can test runtime patches against a real `/Applications/Codex.app` bundle. Public `launch` must leave the app bundle untouched. Legacy bundle mutation, file-patch, archive rewrite, re-sign, and restore flows have been removed. ## When To Use - Adding or updating a patch target in `src/targets/*` or `src/patcher-targets.mts` - Adapting to a new Codex bundle version - Changing compatibility gating or bundle metadata handling - Updating runtime launch, CDP interception, generated CLI composition, or hidden watcher cleanup - Updating repo docs because behavior, support scope, or release guidance changed Do not use this skill for release-only work. Use `codexfast-release-flow` for that. ## Core Rules - Keep the generated CLI self-contained. - Edit `src/*` as the source of truth, then run `pnpm build` to regenerate `bin/codexfast`. - Preserve the runtime-only launcher. Do not reintroduce bundle unpack/repack, archive rewrite, persistent `Contents/Resources/app`, local `codesign`, or restore paths. - Treat patch-signature and runtime interception changes as one unit. - Do not add new public watcher commands. Current `launch` removes legacy auto-repair watcher files installed by older releases. - Do not claim app behavior is fixed from code inspection alone. The regression suite must pass. ## Workflow 1. Inspect the current repo state. - Read `AGENTS.md`, `src/cli.mts`, the relevant `src/cli-*.mts` module, `src/patcher-targets.mts`, the relevant `src/targets/*` module, `test/runtime-launch-flow.mts`, `test/re-sign-flow.sh`, and the relevant README sections. - Use `src/targets/speed.mts`, `src/targets/plugins.mts`, and `src/targets/models.mts` for feature-specific target definitions; keep shared target builders in `src/targets/builders.mts`. - For runtime launch behavior, inspect `src/cli-runtime-launch.mts`, `src/cli-runtime-patcher.mts`, `src/cli-cdp.mts`, and `src/cli.mts` together because the generated CLI inlines those modules. - For app environment or watcher behavior, inspect `src/cli-app-environment.mts`, `src/cli-watcher.mts`, and `src/cli.mts` together. - If the change is bundle-specific, identify the exact gated text key, target file shape, and runtime URL shape first. - Do not trust a missing runtime match as proof that a feature target is gone. For every expected feature path, search the extracted bundle by stable needles such as `settings.agent.speed.label`, `composer.speedSlashCommand.title`, `composer.intelligenceDropdown.speed.title`, `featureRequirements?.fast_mode`, `sidebarElectron.pluginsDisabledTooltip`, `skills.pluginsAuthBlockedToast.title`, `pluginDeepLinkAuthBlocked`, `openai-curated-marketplaces-hidden`, `skills.appsPage.pluginsLimitedCatalog`, `4218407052`, `plugins.install.connectorUnavailable`, `plugins.installModal.about`, `directoryApps`, `appsNeedingAuth`, and nearby `serviceTierSettings` / auth-method gates. - For Fast support, verify the source hook that computes service-tier allowance and request-tier fallback, the request helper that computes `serviceTier` for send/edit/resume paths, and the visible consumers. Settings, `/fast`, and composer Speed controls are not sufficient if `use-service-tier-settings-*.js` or an equivalent shared hook still collapses custom API users to standard, if a helper near `Failed to read service tier for request` still gates non-ChatGPT auth methods with `:!1`, if stale conversation-level service-tier state overrides Settings Fast, or if latest-turn `params.serviceTier` from stop/edit/resend flows locks the current conversation to Standard. - For Plugins catalog support, trace both the backend result and the UI consumption path. A successful `list-plugins` response with `openai-curated` plugins is not enough if `use-plugins-*.js` later excludes marketplace names, applies build-flavor filtering, or `plugins-page-selectors-*.js` selects only bundled sections. Inspect `Ne(t.marketplaces, ...)`, `He({buildFlavor,...})`, vertical-catalog flags such as `4218407052`, and selector defaults when the page shows only a sparse list. - Distinguish "target absent" from "target present but regex stale". A target is absent only after broad non-locale JS search shows the user-facing needle and adjacent gate are no longer present anywhere in `webview/assets`. - For runtime launch work, inspect the real CDP request URLs as well as the extracted archive paths. Current `26.513.20950` serves renderer JavaScript as `app://-/assets/*.js`, while older assumptions used `app://-/webview/assets/*.js`. - For runtime launch interception issues, verify the browser-level CDP auto-attach path first: `Target.setAutoAttach` must use `waitForDebuggerOnStart` and flattened sessions, `Fetch.enable` must run in the renderer `sessionId` before `Runtime.runIfWaitingForDebugger`, and the heartbeat should stay browser-level rather than page-level. 2. Make the smallest viable code change. - Keep patch logic narrow. - Prefer adding a new target spec over refactoring unrelated logic. - For compatibility gating, update the whitelist and surface the detected version/build clearly in output. - If changing the generated entrypoint, edit the source pieces, update `scripts/build-codexfast.mts` when a new `src/cli-*.mts` module must be inlined, and regenerate `bin/codexfast`. 3. Update regression coverage in the same change. - Extend `test/runtime-launch-flow.mts` for every new target, runtime path, hidden watcher cleanup path, or compatibility guard. Keep `test/re-sign-flow.sh` as the compatibility entrypoint. - Cover both positive and negative cases when relevant. - When changing runtime launch, cover generated single-file behavior. A source-level `patch-engine` import is not enough because the embedded runtime engine is extracted from generated `__PATCHER_SOURCE__`. 4. Update repo docs in the same change. - Update `README.md` when usage, compatibility policy, supported features, or recovery guidance changes. - Update `README.zh-CN.md` with the same behavior changes. - Keep README compatibility lists newest-first when adding or reordering verified Codex builds. - Keep public README usage focused on `launch`, `help`, and `version`. - Update `AGENTS.md` when the maintenance checklist or validation expectations change. - Update `CHANGELOG.md` under the active unreleased or target release section. 5. Verify before calling the work done. - Run `pnpm build:check`. - Run `pnpm typecheck`. - Run `pnpm test` or, for a narrow local check, `bash test/re-sign-flow.sh`. - If package metadata changed, also inspect `package.json` and `bin/codexfast`. - If packaging or docs changed materially, run `pnpm pack --dry-run`. - For runtime launch changes, run a real installed-app `launch` pass when possible, then confirm `app.asar`, `Info.plist`, and the app signature are unchanged. ## Codexfast-Specific Checklist - Settings-side Fast patch still works. - The shared Fast service-tier allowance/source hook still lets custom API users compute, persist, and send the selected Fast tier while preserving official ChatGPT `fast_mode` requirements. - The Fast request service-tier helper still lets send/edit/resume paths compute and send Fast for non-ChatGPT auth methods while preserving official ChatGPT `fast_mode` requirements. - The shared Fast service-tier fallback path still ignores stale conversation-level service-tier state, so reopened conversations fall back to the configured Settings tier instead of forcing Standard. - The shared Fast service-tier fallback path still ignores stale latest-turn `params.serviceTier`, so stopping a Fast response, editing the message, and resending in the same conversation does not force Standard or lock speed changes until restart. - Composer `/fast` patch still works. - Composer-side `Speed` menu patch still works for the target bundle: - `Add files and more / +` Speed submenu on builds that still expose the add-context path. - Composer `Intelligence` dropdown Speed submenu on newer builds where the add-context Speed entry moved. - Every Plugins gate required by the target build still works, including sidebar access, page content, plugin detail redirects, curated catalog visibility, install-button availability, install-modal content, plugin detail app-connect content, and post-install app connect where present. - Curated catalog validation checks the visible page, not only the backend. For builds with curated catalog support, the page must not collapse to only bundled addable plugins such as Computer Use and LaTeX after `list-plugins` returns the OpenAI curated marketplace. - Unsupported versions are blocked before runtime launch starts Codex. - Generated CLI extraction still runs the embedded runtime patch engine. - Public help and the interactive menu must not advertise `status`, `apply`, `restore`, `install-watcher`, or `uninstall-watcher`. - Public `launch` removes legacy auto-repair watcher files when present. ## Common Mistakes - Updating source target regexes without regenerating and inspecting the generated CLI. - Treating a missing target as product behavior. First prove whether the bundle still contains the feature needle in a moved file or with a renamed minified hook. - Validating Fast support only by making controls visible. Trace the selected tier back to the shared service-tier hook, the request helper used by send/edit/resume commands, the request/config path, and conversation reload fallback so Fast is not silently normalized back to standard after relaunch, history restore, or edit/resend with changed reasoning effort. - Assuming `serviceTierForRequest` covers every send path. Newer bundles can also call a helper near `Failed to read service tier for request`; if that helper returns false for non-ChatGPT auth methods, UI can show Fast while outgoing requests still omit `service_tier`. - Treating latest-turn `params.serviceTier` as safe request state. Stop/edit/resend flows can leave stale Standard there; tests must prove `serviceTierForRequest` falls back to the configured Settings tier. - Validating Plugins catalog support only by calling `list-plugins`. Trace the returned marketplaces through `use-plugins-*.js` and `plugins-page-selectors-*.js`; a later exclusion can still hide `openai-curated` from the actual page. - Assuming old Plugins sidebar/page/detail gates are required on every new build. Some builds remove those gates but add new catalog or install gates, so required initial targets must stay build-specific. - Writing a fixture assertion that passes on both guarded and patched code. For hidden-control fixes, assert both the patched replacement and the removal of the original guard, for example `if(!n)return null;` is gone. - Describing a Codex build as supported before adding tests and whitelist coverage. - Updating only one README and leaving English/Chinese docs out of sync. - Publishing behavior changes without moving the maintenance checklist forward. - Validating runtime launch only against extracted fixture files or source imports; generated CLI extraction and CDP timing can fail independently. --- > Source: [Veath/codexfast](https://github.com/Veath/codexfast) — distributed by [TomeVault](https://tomevault.io).