Keep Codex Fast
Inspect and safely trim bloated local Codex Desktop/CLI sessions, logs, worktrees, and config without deleting continuity.
Overview
Keep Codex Fast is an agent skill for the Operate phase that safely reports on and maintains local Codex state with backups, archives, and restore manifests instead of destructive deletes.
Install
npx skills add https://github.com/vibeforge1111/keep-codex-fast --skill keep-codex-fastWhat is this skill?
- Default report-only first run: no writes, backups, or moves until you opt in
- Backup-before-mutate flow with optional `--backup-only`
- Archives instead of permanent deletes for chats, logs, worktrees, memories, skills, and plugins
- Writes manifests and restore scripts when sessions or worktrees are relocated
- Windows extended-path normalization plus pruning dead config projects and rotating large logs
- First run must be report-only with no local Codex state mutations
Adoption & trust: 1 installs on skills.sh; 1.4k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Codex feels slow or bloated because local sessions, logs, worktrees, and config have grown, but you are afraid of losing chat continuity.
Who is it for?
A solo builder on Codex Desktop/CLI who wants scripted hygiene with report-only defaults and explicit safety gates.
Skip if: One-off greenfield projects with no local Codex history, or when you demand permanent deletion without archives—the skill refuses that pattern.
When should I use this skill?
Codex feels slow or bloated, local sessions/logs/worktrees/config have grown, or the user wants safe maintenance for Codex Desktop/CLI state.
What do I get? / Deliverables
You get a clear report of reclaimable state, optional backups and archived moves with restore scripts, and lighter local Codex without surprise data loss.
- Read-only maintenance report of sessions, logs, worktrees, and config
- Backups, archive manifests, and restore scripts when apply mode is used
Recommended Skills
Journey fit
Operate → Iterate is where long-running agent tooling accrues drag; this skill is maintenance on your Codex environment, not feature building. Iterate covers recurring hygiene when sessions feel slow—report first, backup, then archive/move with restore paths.
How it compares
Use instead of manually deleting `~/.codex` folders or ad-hoc shell rm when you need backup-first, archive-first maintenance.
Common Questions / FAQ
Who is keep-codex-fast for?
Solo developers using Codex Desktop or CLI who need periodic local-state cleanup without losing chats, worktrees, or plugin continuity.
When should I use keep-codex-fast?
In Operate when Codex sessions lag, logs or worktrees are huge, config lists dead projects, or you want a safe maintenance pass after closing Codex.
Is keep-codex-fast safe to install?
Check the Security Audits panel on this Prism page; the skill is designed for cautious filesystem moves with backups, but you should still review paths and close Codex before applying changes.
SKILL.md
READMESKILL.md - Keep Codex Fast
# Keep Codex Fast Use this skill to inspect and safely maintain local Codex state. The goal is to reduce local drag without surprising the user or losing continuity. Primary principle: preserve continuity before applying changes. For active repo chats the user may continue, recommend a comprehensive handoff document and reactivation prompt before archiving anything. ## Safety Rules - Inspect before mutating. - The first run must be report-only. Report mode must not write files, create backups, move folders, or change local Codex state. - Back up before applying changes. Use `--backup-only` when the user wants backups without moving or changing local state. - Archive or move files instead of deleting them. Do not permanently delete user chats, logs, worktrees, memories, skills, plugins, or automations. - Write manifests and restore scripts when sessions/worktrees are moved. - If Codex is running, default to report-only. Apply changes only after Codex is closed or when the user explicitly accepts waiting for Codex to exit. - Never modify or copy credential files unless the user explicitly asks for that. Back up memory/skill/plugin/automation files before touching local state. - Treat backup folders as private local artifacts because they can contain Codex metadata. Do not ask users to publish or share backups unless they have reviewed them first. - Do not print raw thread IDs, chat titles, local paths, or process paths unless the user asks for details or runs `--details`. - Before applying changes, tell the user to create handoff docs for active repo chats they may continue. - Before archiving any active repo chat the user may want to continue, recommend creating a comprehensive handoff doc plus a reactivation prompt. - Do not archive old-but-important active repo chats until the user either confirms a handoff exists or confirms they do not need one. ## Mental Model There are three modes: - Inspect: report-only, no writes. - Maintain: normal `--apply`; backs up, archives old sessions, moves stale worktrees, rotates logs, prunes dead config, and normalizes paths. It does not trim thread title/preview metadata. - Optional repair: `--apply --repair-thread-metadata-bloat`; shortens oversized SQLite display title/preview metadata after backup. The rollout transcript stays intact. ## Default Workflow 1. Reassure the user: the first run is read-only, privacy-safe, and the skill archives instead of deleting when changes are later applied. 2. Run the bundled script in report mode: ```bash python scripts/keep_codex_fast.py ``` 3. Summarize: - active session size - archived session size - largest active sessions - thread metadata bloat: active title/preview character totals, max title/preview lengths, and over-limit counts - stale worktree candidates - log size - bad Windows `\\?\` path counts - config project prune candidates - top Node/dev processes 4. Before applying changes, recommend that the user create handoffs for all active repo chats they may continue. Explain that handoffs let them archive heavy chats and resume from docs in fresh threads. 5. Identify large/old active repo chats that may still matter. For each one the user wants to continue, create or update: - a repo-local handoff doc - a reactivation prompt that can start a fresh chat without losing the thread 6. If the user wants to apply the recommended maintenance, ask them to close Codex or use `--wait-for-codex-exit`, then run: ```bash p