Skip to content
Back to search

"keep-codex-fast"

SkillWorks with Claude CodeGitHub

"Use when Codex feels slow or bloated, when local sessions/logs/worktrees/config have grown over time, or when a user wants safe maintenance for Codex Desktop/CLI state. Provides a read-only report by default, backs up before applying changes, archives instead of deleting, normalizes Windows extended paths, prunes dead config projects, rotates large logs, and moves stale worktrees."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vibeforge1111-keep-codex-fast/badge.svg)](/listings/vibeforge1111-keep-codex-fast)

HTML

<a href="/listings/vibeforge1111-keep-codex-fast"><img src="/api/listings/vibeforge1111-keep-codex-fast/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Ask Codex:

Use $keep-codex-fast to inspect my Codex local state and recommend a safe maintenance plan.

Codex should show you what it found first. Then you decide what to hand off, what to keep active, and what can be archived.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 207 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: "keep-codex-fast"
  3. description: "Use when Codex feels slow or bloated, when local sessions/logs/worktrees/config have grown over time, or when a user wants safe maintenance for Codex Desktop/CLI state. Provides a read-only report by default, backs up before applying changes, archives instead of deleting, normalizes Windows extended paths, prunes dead config projects, rotates large logs, and moves stale worktrees."
  4. metadata:
  5. short-description: "Safe Codex local-state maintenance"
  6. ---
  7. # Keep Codex Fast
  8. 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.
  9. 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.
  10. ## Safety Rules
  11. - Inspect before mutating.
  12. - The first run must be report-only. Report mode must not write files, create backups, move folders, or change local Codex state.
  13. - Back up before applying changes. Use `--backup-only` when the user wants backups without moving or changing local state.
  14. - Archive or move files instead of deleting them. Do not permanently delete user chats, logs, worktrees, memories, skills, plugins, or automations.
  15. - Write manifests and restore scripts when sessions/worktrees are moved.
  16. - 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.
  17. - Never modify or copy credential files unless the user explicitly asks for that. Back up memory/skill/plugin/automation files before touching local state.
  18. - 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.
  19. - Do not print raw thread IDs, chat titles, local paths, or process paths unless the user asks for details or runs `--details`.
  20. - Before applying changes, tell the user to create handoff docs for active repo chats they may continue.
  21. - Before archiving any active repo chat the user may want to continue, recommend creating a comprehensive handoff doc plus a reactivation prompt.
  22. - Do not archive old-but-important active repo chats until the user either confirms a handoff exists or confirms they do not need one.
  23. ## Mental Model
  24. There are three modes:
  25. - Inspect: report-only, no writes.
  26. - 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.
  27. - Optional repair: `--apply --repair-thread-metadata-bloat`; shortens oversized SQLite display title/preview metadata after backup. The rollout transcript stays intact.
  28. ## Default Workflow
  29. 1. Reassure the user: the first run is read-only, privacy-safe, and the skill archives instead of deleting when changes are later applied.
  30. 2. Run the bundled script in report mode:
  31. ```bash
  32. python scripts/keep_codex_fast.py
  33. ```
  34. 3. Summarize:
  35. - active session size
  36. - archived session size
  37. - largest active sessions
  38. - thread metadata bloat: active title/preview character totals, max title/preview lengths, and over-limit counts
  39. - stale worktree candidates
  40. - log size
  41. - bad Windows `\\?\` path counts
  42. - config project prune candidates
  43. - top Node/dev processes
  44. 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.
  45. 5. Identify large/old active repo chats that may still matter. For each one the user wants to continue, create or update:
  46. - a repo-local handoff doc
  47. - a reactivation prompt that can start a fresh chat without losing the thread
  48. 6. If the user wants to apply the recommended maintenance, ask them to close Codex or use `--wait-for-codex-exit`, then run:
  49. ```bash
  50. python scripts/keep_codex_fast.py --apply --archive-older-than-days 10 --worktree-older-than-days 7
  51. ```
  52. 7. Verify after applying:
  53. ```bash
  54. python scripts/keep_codex_fast.py
  55. ```
  56. 8. Ask whether the user wants a recurring report-only reminder:
  57. - weekly for heavy Codex use across many repos/terminals
  58. - biweekly for lighter use
  59. - no reminder if they prefer manual maintenance
  60. If the user wants automation and the Codex app automation tool is available, create only a recurring report/reminder automation. Do not recommend recurring mutating maintenance, because automation cannot know whether the user created handoffs. The prompt must say not to pass `--apply`, not to archive/move/prune/rotate/normalize/delete/mutate local state, and to remind the user that manual apply should happen only after handoffs are confirmed and Codex is closed.
  61. ## What Apply Does
  62. - Backs up important metadata to `~/Documents/Codex/codex-backups/keep-codex-fast-*`.
  63. - Archives old non-pinned sessions to `~/.codex/archived_sessions/`.
  64. - Normalizes Windows extended paths like `\\?\C:\...` inside local SQLite text fields.
  65. - Prunes missing/temp project blocks from `config.toml` and writes UTF-8 without BOM.
  66. - Moves stale worktrees to `~/.codex/archived_worktrees/`.
  67. - Rotates `logs_2.sqlite*` into `~/.codex/archived_logs/` only when above the threshold.
  68. - Reports heavy Node processes without killing them.
  69. - Reports pathological active thread titles and `first_user_message` previews. It only repairs them when the user explicitly opts in with `--repair-thread-metadata-bloat`.
  70. Report mode does none of those mutations. It only prints counts and pseudonymous candidates. Use `--details` when raw IDs, titles, or paths are needed for diagnosis.
  71. ## Recommended Policy
  72. - Keep only the last 7-10 days of non-pinned chats active.
  73. - Use handoff docs for important old threads.
  74. - Start fresh threads from handoff docs instead of repeatedly resuming giant chats.
  75. - Run weekly maintenance if Codex is used daily across many repos/terminals.
  76. - Offer weekly or biweekly report-only reminders after the first successful apply; do not assume the user wants recurring maintenance.
  77. - When in doubt, leave a chat active or ask the user. Never archive a chat that is pinned, current, or explicitly marked as still needed without a handoff.
  78. - Treat title/preview repair as metadata repair only. The full rollout transcript remains in the session JSONL; bounded SQLite fields are for list/navigation display.
  79. ## Thread Metadata Bloat
  80. Codex Desktop can become slow when `threads.title` or `threads.first_user_message` stores a full prompt/history-sized value instead of a display title or preview. This affects the thread list/navigation path before the UI renders anything.
  81. The script reports active thread count, total title/preview characters, maximum title/preview length, active titles over the configured title limit, and active previews over the configured preview limit and over 10k characters.
  82. Normal apply mode reports metadata-bloat candidates but does not repair them. If the user explicitly opts in, after backups and only when Codex is not running, run:
  83. ```bash
  84. python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat
  85. ```
  86. That bounds active `threads.title` and `threads.first_user_message` values. Defaults are 120 characters for titles and 240 characters for previews. It also appends repaired titles to `session_index.jsonl`, matching current upstream name-update storage, so reconciliation/name lookup does not immediately prefer the old full-message fallback.
  87. The targeted repair manifest stores the old full title/preview values so the change can be reversed. Treat `thread-metadata-repairs.jsonl`, `restore-thread-metadata.py`, and the whole backup folder as private local artifacts.
  88. This is a local maintenance workaround for metadata bloat. It does not solve app renderer hydration of very large rollout histories; that needs upstream staged/paged thread loading.
  89. ## Handoff Doc + Reactivation Prompt
  90. For important active repo chats, create a handoff before archiving. Prefer a repo-local path such as `docs/codex-handoffs/YYYY-MM-DD-topic.md` or a user-approved docs location.
  91. Use `references/handoff-template.md` when the user wants a concrete template.
  92. A handoff document converts an old chat into durable project memory. It should let a fresh Codex thread continue after reading the repo and the handoff, without needing the original chat history.
  93. Offer this prompt for each active repo chat the user may want to continue:
  94. ```text
  95. Create a comprehensive handoff document for this repo/session before I archive Codex history.
  96. Include:
  97. - repo/path and branch
  98. - current goal
  99. - what we already completed
  100. - files touched or investigated
  101. - commands/tests already run
  102. - known errors, warnings, or failing checks
  103. - open decisions
  104. - constraints, user preferences, and do-not-touch areas
  105. - the next 3-7 concrete steps
  106. Also include a reactivation prompt I can paste into a fresh Codex chat so it can continue from this handoff without relying on the old chat context.
  107. Save the handoff in a sensible repo-local place like docs/codex-handoffs/YYYY-MM-DD-topic.md unless this repo already has a better handoff location.
  108. ```
  109. The handoff should capture:
  110. - repo/path and branch
  111. - current goal
  112. - what was already done
  113. - key files touched or investigated
  114. - commands/tests already run
  115. - known failures or warnings
  116. - open decisions
  117. - next 3-7 concrete steps
  118. - any constraints, user preferences, or "do not touch" areas
  119. Add a reactivation prompt at the top or bottom:
  120. ```text
  121. We are continuing from this handoff. Read this document first, inspect the current repo state, verify what still applies, and continue from the next steps without assuming the old chat context is available.
  122. ```
  123. ## Automation Reminder Prompt
  124. Offer this after the first report/apply/verify cycle:
  125. ```text
  126. Use $keep-codex-fast to create a recurring Codex maintenance reminder.
  127. Schedule it weekly if I use Codex heavily, or biweekly if that seems safer.
  128. The reminder should:
  129. - run the keep-codex-fast report first
  130. - never pass --apply or run mutating maintenance automatically
  131. - never archive, move, prune, rotate, normalize, delete, or mutate local Codex state
  132. - remind me to create comprehensive handoff docs and reactivation prompts for active repo chats before any manual apply
  133. - summarize active session size, archived session size, extended path candidates, old session candidates, worktree candidates, log size, and top Node/dev processes
  134. - report heavy Node/dev processes without killing them
  135. - tell me that manual apply should only happen after I confirm handoffs exist or are not needed and Codex is closed
  136. ```
  137. ## Anti-Patterns
  138. Avoid these behaviors:
  139. - deleting sessions, logs, worktrees, memories, plugins, or skills permanently
  140. - applying changes while Codex is actively writing the DB
  141. - archiving important repo chats before creating handoff docs
  142. - treating active history size as "bad" without checking whether the user needs continuity
  143. - treating preview metadata repair as deletion of the actual rollout transcript
  144. - killing Node/dev processes automatically
  145. - rewriting `config.toml` without a backup and parse check
  146. - writing UTF-8 TOML with a BOM on Windows
  147. - promising speed gains as universal fact; frame improvements as local-state maintenance results
  148. - making users feel like they did something wrong by using Codex heavily
  149. ## User-Facing Caution
  150. Tell users this does not permanently delete chats, worktrees, or logs. It moves them into archive folders and writes restore helpers. The only removed content is stale metadata, such as project entries pointing to folders that no longer exist, and even that happens after backing up `config.toml`.
  151. Also tell users that thread title/preview bloat repair is not part of normal apply. Normal use only reports title/preview bloat. Recommend `--repair-thread-metadata-bloat` only as an optional extra when the report shows large metadata payloads and the user understands that SQLite display metadata will be shortened while the real transcript remains in rollout JSONL.
  152. Also tell users backup folders can contain private local Codex metadata, including old thread titles and first-message previews. They should keep backups local and avoid publishing or sharing them unless they have reviewed what is inside.
README.md · README · 220 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Keep Codex Fast
  2. ![Keep Codex Fast cover](assets/keep-codex-fast-cover.png)
  3. When Codex starts feeling heavy after weeks of chats, terminals, logs, worktrees, and project history, this gives you a calm way to inspect what is going on and reduce local drag.
  4. This skill helps you organize local state without losing context.
  5. The rule is simple:
  6. > Make handoffs first. Archive, don't delete. Apply changes only when you are ready.
  7. ## Three Modes
  8. - **Inspect:** report-only, no writes.
  9. - **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.
  10. - **Optional repair:** only with `--apply --repair-thread-metadata-bloat`; shortens oversized SQLite display title/preview metadata after backup. The transcript stays intact.
  11. ## Who This Is For
  12. Use this if Codex has started feeling slower after heavy use, especially if you:
  13. - keep long chats around
  14. - resume old threads often
  15. - work across many repos
  16. - run multiple terminals or dev servers
  17. - want maintenance to feel safe, not scary
  18. ## What It Does
  19. By default, this skill only reports. It does not write files, create backups, move folders, or change local Codex state until you explicitly ask it to.
  20. It helps Codex:
  21. - see which local state has grown over time
  22. - create handoff docs before archiving old chats
  23. - back up important state before applying changes
  24. - archive old chats instead of deleting them
  25. - detect pathological thread title/preview metadata that can slow chat navigation
  26. - move stale worktrees out of the hot path
  27. - rotate large logs
  28. - prune dead project references
  29. - report heavy Node/dev processes without killing them
  30. ## Quick Start
  31. Ask Codex:
  32. ```text
  33. Use $keep-codex-fast to inspect my Codex local state and recommend a safe maintenance plan.
  34. ```
  35. Codex should show you what it found first. Then you decide what to hand off, what to keep active, and what can be archived.
  36. ## Handoffs First
  37. Before archiving old active chats, create handoff documents for any repo/session you may want to continue.
  38. A handoff is a small continuity note. It captures:
  39. - what you were doing
  40. - what changed
  41. - what files matter
  42. - what commands or checks already ran
  43. - what is still broken or undecided
  44. - what to do next
  45. That lets you archive the heavy chat and start a fresh Codex thread from the handoff.
  46. Copy this into each active repo chat you care about:
  47. ```text
  48. Create a comprehensive handoff document for this repo/session before I archive Codex history.
  49. Include:
  50. - repo/path and branch
  51. - current goal
  52. - what we already completed
  53. - files touched or investigated
  54. - commands/tests already run
  55. - known errors, warnings, or failing checks
  56. - open decisions
  57. - constraints, user preferences, and do-not-touch areas
  58. - the next 3-7 concrete steps
  59. Also include a reactivation prompt I can paste into a fresh Codex chat so it can continue from this handoff without relying on the old chat context.
  60. Save the handoff in a sensible repo-local place like docs/codex-handoffs/YYYY-MM-DD-topic.md unless this repo already has a better handoff location.
  61. ```
  62. ## Safe Apply
  63. After handoffs exist for the chats you care about, use this:
  64. ```text
  65. Use $keep-codex-fast to apply safe Codex maintenance.
  66. Before changing anything, confirm that important active repo chats have handoff docs or do not need them.
  67. Then back up first, archive instead of deleting, move stale worktrees, rotate large logs, prune dead config references, and verify the result.
  68. If Codex is currently running, do not mutate local state. Tell me to close Codex first.
  69. ```
  70. ## Thread Title And Preview Bloat
  71. Some Codex builds can store a full first user prompt as both the thread title and the list preview. When those fields grow into hundreds of thousands of characters, thread navigation can become sluggish even before a large chat is opened.
  72. The script reports title and preview payload size in report mode and normal apply mode. It does not trim this metadata unless you explicitly opt in:
  73. ```bash
  74. python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat
  75. ```
  76. With that flag, after backing up and only when Codex is not running, it trims active SQLite title/preview metadata to bounded display values. It also appends repaired titles to `session_index.jsonl`, which matches current Codex name-update storage.
  77. This does not remove the actual conversation transcript. The full rollout JSONL remains available unless you separately archive the session.
  78. The repair manifest stores the old full title/preview values so you can restore them. Keep the backup folder private, especially `thread-metadata-repairs.jsonl` and `restore-thread-metadata.py`.
  79. If you are using the skill normally, this repair does not happen automatically. Treat it as an extra recommendation only when the report shows unusually large title/preview metadata.
  80. ## Weekly Or Biweekly Reminder
  81. Recurring maintenance should be a reminder, not an automatic apply.
  82. Why: an automation cannot know whether you created handoffs for chats you still care about. It should inspect and remind you, but not archive, move, prune, rotate, normalize, delete, or mutate anything by itself.
  83. Copy this into Codex:
  84. ```text
  85. Use $keep-codex-fast to create a recurring Codex maintenance reminder.
  86. Schedule it weekly if I use Codex heavily, or biweekly if that seems safer.
  87. The reminder should:
  88. - run the keep-codex-fast report first
  89. - never pass --apply or run mutating maintenance automatically
  90. - never archive, move, prune, rotate, normalize, delete, or mutate local Codex state
  91. - remind me to create comprehensive handoff docs and reactivation prompts for active repo chats before any manual apply
  92. - summarize active session size, archived session size, extended path candidates, old session candidates, worktree candidates, log size, and top Node/dev processes
  93. - report heavy Node/dev processes without killing them
  94. - tell me that manual apply should only happen after I confirm handoffs exist or are not needed and Codex is closed
  95. ```
  96. ## Install
  97. Ask Codex:
  98. ```text
  99. Install the keep-codex-fast skill from https://github.com/vibeforge1111/keep-codex-fast
  100. ```
  101. Or clone/copy this folder into your Codex skills directory as `keep-codex-fast`.
  102. ## Advanced: Manual Script Use
  103. Most users can stay inside Codex and use the prompts above. The script is here for people who want to run it directly.
  104. Report only. This is read-only and privacy-safe by default:
  105. ```bash
  106. python scripts/keep_codex_fast.py
  107. ```
  108. Show raw thread IDs, chat titles, paths, and process paths only when you need detail:
  109. ```bash
  110. python scripts/keep_codex_fast.py --details
  111. ```
  112. Create backups only, without moving or changing local state:
  113. ```bash
  114. python scripts/keep_codex_fast.py --backup-only
  115. ```
  116. Backup folders can contain private local Codex metadata. Keep them on your machine, and do not publish or share them unless you have reviewed what is inside.
  117. Apply core maintenance actions. This does not trim thread title/preview metadata:
  118. ```bash
  119. python scripts/keep_codex_fast.py --apply --archive-older-than-days 10 --worktree-older-than-days 7
  120. ```
  121. Optionally repair oversized title/preview metadata only when the report recommends it:
  122. ```bash
  123. python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat
  124. ```
  125. Wait for Codex to exit before applying:
  126. ```bash
  127. python scripts/keep_codex_fast.py --apply --wait-for-codex-exit
  128. ```
  129. ## What Can Change
  130. The skill can safely handle:
  131. - old non-pinned active sessions
  132. - stale worktrees
  133. - large `logs_2.sqlite*` files
  134. - dead/temp project entries in `config.toml`
  135. - Windows `\\?\C:\...` path mismatches in local SQLite text fields
  136. - oversized thread title and first-message preview metadata in `state_5.sqlite`, only with `--repair-thread-metadata-bloat`
  137. It does not permanently delete chats, logs, or worktrees. It moves them into archive folders and writes backup/restore artifacts before applying changes.
  138. ## Mental Model
  139. - Chats are for execution.
  140. - Handoff docs are for memory.
  141. - Archives are for history.
  142. - Fresh threads are for speed.
  143. ## Flow
  144. ![Keep Codex Fast flow](assets/keep-codex-fast-flow.svg)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.