codex-app-cleanup

Prune stale project roots, environment references, and worktree pairings from Codex caches.

3|1|Updated Jun 20, 2016

Search Tags:#codex #cleanup #worktree #macos #cache #state-management #desktop-app

Ready to run

npx skills add https://github.com/paulchiu/dotfiles --skill codex-app-cleanup

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: codex-app-cleanup
Source: https://github.com/paulchiu/dotfiles/tree/main/.config/opencode/skills/codex-app-cleanup
Command: npx skills add https://github.com/paulchiu/dotfiles --skill codex-app-cleanup

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Cleans stale Codex desktop app state such as dead project picker entries, invalid local environment refs, and obsolete worktree pairings, ensuring the UI reflects current reality and reducing confusion from outdated references.

Core Features & Use Cases

Detects and removes dead project roots from Codex's project picker and clears related labels to prevent confusion.
Reconciles pairing caches and environment references that no longer point to valid directories, reducing stale shortcuts.
Safe, reversible cleanup with backups and validation to minimize disruption when Codex UI still shows old projects or envs after worktree cleanups.

Quick Start

Identify and prune missing paths from the global state and pairing caches, then relaunch Codex.

Frequently Asked Questions about codex-app-cleanup

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I remove stale project roots from the Codex desktop app project picker?▼

Remove stale project roots from the Codex desktop app by pruning dead paths from the global state file and pairing cache. This identifies invalid project picker entries and clears related labels to prevent confusion.

Why does the Codex UI still show old environments after worktree removal?▼

The Codex UI shows old environments after worktree removal because local caches retain obsolete pairing data. Reconciling the pairing caches and environment references prunes invalid directories that no longer point to valid paths.

Is it safe to prune obsolete worktree pairings from macOS local caches?▼

Pruning obsolete worktree pairings from macOS local caches is safe because the process implements JSON file validation and creates backups before selectively removing relevant keys, ensuring valid entries are preserved and the cleanup is reversible.

What is the best way to clean up dead project references in Codex state management?▼

The best way to clean up dead project references in Codex state management is to validate the global state JSON file, create a backup, and selectively prune invalid environment references and obsolete worktree pairings while preserving valid entries.

Do I need to manually edit JSON files to fix outdated Codex desktop app state?▼

You do not need to manually edit JSON files to fix outdated Codex desktop app state. The cleanup process automates JSON file validation, backup creation, and selective pruning of relevant keys in the global state file and pairing cache.