Skip to content

System skills cache can disappear during refresh #30014

Open
Open
System skills cache can disappear during refresh#30014
Labels
CLIIssues related to the Codex CLIbugSomething isn't workingskillsIssues related to skills

Description

@Tygb99
Tygb99
opened on Jun 25, 2026

Summary

The embedded system skills cache under CODEX_HOME/skills/.system can temporarily disappear during startup/refresh. In practice this can make bundled skills such as $imagegen unavailable until another Codex process recreates the cache.

User impact

A user can see $imagegen fail to load because /Users/<user>/.codex/skills/.system/imagegen is missing. Running Codex again may recreate it, but it can disappear again later.

Observed behavior

On macOS with Codex v0.142.0, I observed:

  • ~/.codex/skills/.system missing while the user expected $imagegen to be available.
  • Starting codex exec recreated ~/.codex/skills/.system/imagegen.
  • After the Codex process exited, the system cache could be missing again.
  • The GitHub compare page for the proposed fix shows the branch is mergeable, but opening a PR is limited to collaborators on this repository.

Root cause hypothesis

codex-rs/skills/src/lib.rs::install_system_skills removes the existing CODEX_HOME/skills/.system directory before writing the embedded skills back into place. That creates a window where readers can observe .system as missing. If the process is interrupted or another process reads during that window, bundled skills can be unavailable.

Proposed fix

Refresh the embedded system skills in place instead of deleting the .system root first:

  • collect the embedded paths
  • write embedded files/directories into the existing cache root
  • remove stale entries after the embedded files are written
  • write the marker last

I pushed a candidate fix here:

https://github.com/openai/codex/compare/main...Tygb99:codex/system-skills-refresh-in-place?expand=1

Branch:

Tygb99/codex:codex/system-skills-refresh-in-place

Commit:

ea02050723c15994038768ab004974b14e652d88 (Refresh system skills in place)

Validation on the candidate branch

  • Added a Unix regression test that verifies refresh keeps the existing .system cache root inode while still removing stale entries.
  • Confirmed the new test fails before the fix because the cache root inode changes.
  • just fmt
  • just test -p codex-skills
  • just fix -p codex-skills

Note

I attempted to open this as a PR, but GitHub reported that this repository limits opening pull requests to collaborators.

Activity

  1. github-actions
    added
    bugSomething isn't working
    CLIIssues related to the Codex CLI
    skillsIssues related to skills
    on Jun 25, 2026

  2. Nicolas0315 commented on Jun 25, 2026

    @Nicolas0315
    Nicolas0315
    on Jun 25, 2026

    I prepared a focused branch for this as well:

    What changed:

    • install_system_skills no longer removes CODEX_HOME/skills/.system before refreshing embedded skills.
    • Embedded files are written first, stale cache entries are removed afterward, then the marker is rewritten.
    • Regression coverage checks stale cleanup on all platforms and verifies the .system root inode is preserved on Unix.

    Verification:

    • Local Windows: just fmt
    • Local Windows: just test -p codex-skills
    • Local Windows: cargo check --manifest-path codex-rs\Cargo.toml -p codex-skills
    • Local Windows: git diff --check
    • SSH rtx4090: just test -p codex-skills
    • SSH cyberagent-mac-m5max: fresh clone + git apply + cargo test --manifest-path codex-rs/Cargo.toml -p codex-skills (3 tests, including Unix inode preservation)

    I attempted to open an upstream PR, but GitHub returned: Nicolas0315 does not have the correct permissions to execute CreatePullRequest.

    Other SSH nodes were probed but blocked by local toolchain state:

    • nicolas2025: cargo/rustc shims are 0-byte files.
    • rtx5060ti: rustc link smoke test fails because link.exe resolves incorrectly / MSVC build tools are unavailable.
    • nicolas-macbook-pro: cargo/rustc are not in PATH; just is installed.

  3. Tygb99 commented on Jun 25, 2026

    @Tygb99
    Tygb99
    on Jun 25, 2026 – with ChatGPT Codex Connector
    Author

    I verified this also reproduces on Windows with the official Codex CLI 0.142.0 release asset, without using npm.

    Setup:

    • Asset: codex-x86_64-pc-windows-msvc.exe.zip from rust-v0.142.0
    • Binary reports: codex-cli 0.142.0
    • Authenticode signature: valid, signed by OpenAI OpCo, LLC
    • ZIP SHA256: B109CCEF543D969128E22834857343AF94FE446039FF51854926B585DD136E6F

    Repro shape:

    1. Created an isolated CODEX_HOME on Windows.
    2. Pre-created CODEX_HOME\skills\.system with a stale .codex-system-skills.marker and a stale-file.
    3. Started the real binary with:
    codex-x86_64-pc-windows-msvc.exe exec --skip-git-repo-check --ephemeral --ignore-user-config probe
    1. Polled CODEX_HOME\skills\.system while startup refreshed bundled skills.

    Observed:

    • Waiting only until imagegen\SKILL.md appeared: .system was observed missing in 10/12 runs.
    • Waiting until the fresh marker was written: .system was observed missing in 4/5 runs.
    • In completed runs, imagegen\SKILL.md and a fresh marker were recreated, and the stale file was removed.

    So the delete-then-rewrite refresh window is observable on Windows CLI 0.142.0 as well.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    CLIIssues related to the Codex CLIbugSomething isn't workingskillsIssues related to skills

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions