English | 简体中文

repair-codex-plugins

A Windows PowerShell Codex Skill and repair script for diagnosing and repairing verified Codex Desktop plugin, Chrome integration, Windows AppX copy, bundled runtime, and local MCP failures.

Community project. Not affiliated with or endorsed by OpenAI.

Applicable Problems

Use this project for evidence-backed failures such as:

• Codex Desktop plugin installation reports an error, but the plugin later appears installed or incomplete.
• Chrome integration fails, Chrome shows Unable to start ChatGPT, or the app-server reports a resourcesPath error.
• The Codex plugin library is empty, or chrome, computer-use, or visualize is missing or stale.
• Chrome Native Messaging manifests, registry values, or the v2 native-host state are missing or inconsistent.
• Windows AppX WindowsApps copy operations fail with errno -4094, UNKNOWN, or related encrypted-copy evidence.
• Bundled marketplace synchronization leaves stale staging directories or plugins.sync.lock files.
• Bundled Node or Codex runtime caches are missing, stale, or inconsistent with the current AppX package.
• A registered bundled marketplace source conflicts with the source managed by the updated desktop app.

Not In Scope

Do not use this project for sidebar conversation visibility, account login, deleted session files, plugins intentionally hidden from the composer, model-provider configuration, API keys, session content, project code, or user browser data. It is not a general-purpose Windows repair tool.

Modes

• Diagnose (default): Inspect current package identity, marketplace sources, plugin versions, native registration, and recent desktop log categories.
• Repair -PlanOnly: Preview supported source value changes without writing files.
• Repair: Back up config and apply only recognized source corrections within the user's authorized scope. Refuse to overwrite changes made after diagnosis.

The workflow always starts from diagnosis. A request to audit the skill does not authorize live repairs. Preserve custom API settings and separate local plugin integrity, actual Chrome connectivity, and online catalog authorization.

Installation

Prerequisites

• Windows only.
• PowerShell 5.1 or a compatible PowerShell environment.
• A user-level Codex Desktop installation, plugin cache, Chrome Native Messaging integration, bundled runtime, or local MCP setup that needs diagnosis.
• Run Diagnose first. Repair is not automatic.

Windows PowerShell

git clone https://github.com/Sunne927/repair-codex-plugins.git "$HOME\.agents\skills\repair-codex-plugins"

The clone contains both the Codex Skill metadata and the scripts used by the Skill. If the Skill does not appear in the Codex Skills list after installation, restart Codex.

Usage

Call Through Codex

Diagnose only:

$repair-codex-plugins 诊断当前 Codex 插件和 Chrome 集成状态，不要执行修复

Authorize repair:

$repair-codex-plugins 诊断并修复已确认的 Codex 插件问题

The second request explicitly authorizes the Repair phase. A request to inspect, check, or diagnose remains in Diagnose mode.

Run the PowerShell Script Directly

Diagnose:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$HOME\.agents\skills\repair-codex-plugins\scripts\repair-codex-plugins.ps1" -Mode Diagnose

Preview the source changes first:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$HOME\.agents\skills\repair-codex-plugins\scripts\repair-codex-plugins.ps1" -Mode Repair -PlanOnly

Apply supported corrections:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$HOME\.agents\skills\repair-codex-plugins\scripts\repair-codex-plugins.ps1" -Mode Repair

Tests:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$HOME\.agents\skills\repair-codex-plugins\scripts\test-repair-codex-plugins.ps1"

Recommended Workflow

1. Run Diagnose and inspect the dimension relevant to the reported symptom.
2. If health.managedMarketplace.sourceChanges contains supported corrections, preview them with -Mode Repair -PlanOnly, then apply within the authorized scope.
3. After a source correction, allow the desktop app to reconcile its own plugins and service records. Rerun Diagnose and verify the actual Chrome panel.
4. If sources are correct but Chrome cannot connect, inspect both v2 registrations, current package paths, and current synchronization logs. Do not automatically uninstall the extension.
5. If only catalog entries are missing, investigate marketplace availability and authorization separately. A personal catalog does not unlock online entitlements.
6. If there is no supported source change, repeating Repair will not help. Continue focused diagnosis.

JSON Results

The top-level result contains mode, planOnly, health, healthMeasuredBeforeRepair, repair, browserEndToEndVerified, and nextAction.

• health.managedMarketplace: Current materialization identity, source parsing problems, and proposed source changes.
• health.plugins, health.chromeCache: Installed/enabled versions and Chrome cache checks.
• health.nativeHostStateCandidates: Both known v2 registration locations; prefer a compatible current entry over a newer stale entry.
• health.desktopEvidence: Recent event categories and timestamps, without raw log lines. Historical failures may have been followed by success.
• health.installerEvidence, health.runtimeCaches: Supporting observations; a stale hash alone is not proof of a current copying failure.
• health.staging, health.syncLocks: Age-based investigation candidates, not automatic deletion targets.
• health.catalogAuthorization: Untested by the script and separate from the custom API provider.
• health.healthy: Only the implemented local source, plugin, and Chrome checks. It does not certify browser connectivity or catalog completeness.

An applied correction returns repair.status: "awaiting_app_reconcile". The reported health was measured before the write. A preview returns plan_only; no supported changes returns no_supported_source_change. A successful script exit is not proof that the user's original symptom is resolved.

Repair Scope and Safety

Repair can correct the known openai-bundled-repaired source to a verified current app-managed materialization, and canonicalize a verified existing primary-runtime source. It backs up config, checks for concurrent edits, and changes only the recognized source tokens while preserving provider settings, keys, comments, and unrelated entries.

The default repair entry point no longer moves marketplaces, rebuilds plugin trees, uninstalls plugins, stops processes, deletes locks, repairs runtimes, or restores unrelated MCP servers. Retained low-level historical helpers are not invoked by Repair. Unrecognized sources or unverified materialization require further diagnosis.

For confirmed current WindowsApps copy failures, consult the focused reference. Do not infer a copying failure from old staging directories or hashes.

Chrome and Catalog Verification

An installed extension or valid native manifest does not prove a compatible app-server registration. Fix synchronization inputs and let the current desktop app generate its own v2 records. Consider first-party Computer control installation only when the remaining evidence supports incomplete installation; do not repeatedly uninstall to expose the Install button.

Missing online categories require separate account and service authorization diagnosis. Preserve custom API preferences. A local or personal marketplace can expose plugin definitions without granting the corresponding service access.

Testing

Run the isolated test suite with:

powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$HOME\.agents\skills\repair-codex-plugins\scripts\test-repair-codex-plugins.ps1"

The suite contains 13 isolated temporary-fixture tests covering native exit codes, current/stale registrations, missing runtime paths, Chrome junctions, canonical paths, compatible-entry selection, read-only preview, exact config preservation, lock/directory preservation, idempotence, app-update materialization identity, and concurrent-edit refusal.

The tests do not run a live Repair against the user's Codex installation or verify online catalog entitlements.

Repository Structure

repair-codex-plugins/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   └── windowsapps-copy-failures.md
├── scripts/
│   ├── repair-codex-plugins.ps1
│   └── test-repair-codex-plugins.ps1
├── LICENSE
├── README.md
└── README.zh-CN.md

Updating

git -C "$HOME\.agents\skills\repair-codex-plugins" pull

License

This project is released under the MIT License.