Keep Codex Fast

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.

This skill helps you organize local state without losing context.

The rule is simple:

Make handoffs first. Archive, don't delete. Apply changes only when you are ready.

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.
• Hot path repair: only with --apply --hot-normalize-paths; backs up SQLite and aligns active thread path fields to Codex Desktop's running \\?\ path convention.
• Optional repair: only with --apply --repair-thread-metadata-bloat; shortens oversized SQLite display title/preview metadata after backup. The transcript stays intact.
• Optional malformed-task archive: only with --apply --archive-malformed-local-tasks; archives active no-user-event local task sessions with suspicious workspace roots such as / or OS temp folders.
• Targeted thread recovery: only with --apply --recover-thread-id THREAD_ID; backs up SQLite and matching automations, performs a storage-level archive-state refresh, and skips broad cleanup.
• Detected thread recovery: only with --apply --recover-detected-threads; backs up SQLite and matching automations, refreshes current active non-archived failure-log candidates found in logs_2.sqlite, and skips broad cleanup.

Who This Is For

Use this if Codex has started feeling slower after heavy use, especially if you:

• keep long chats around
• resume old threads often
• work across many repos
• run multiple terminals or dev servers
• want maintenance to feel safe, not scary

What It Does

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.

It helps Codex:

• see which local state has grown over time
• create handoff docs before archiving old chats
• back up important state before applying changes
• archive old chats instead of deleting them, with restore helpers
• detect pathological thread title/preview metadata that can slow chat navigation
• detect malformed active local-task sessions that can make Codex Desktop repeatedly log No cwd found for local task
• move stale worktrees out of the hot path, with restore helpers
• rotate large logs
• prune dead project references
• report heavy Node/dev processes without killing them

Quick Start

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.

Handoffs First

Before archiving old active chats, create handoff documents for any repo/session you may want to continue.

A handoff is a small continuity note. It captures:

• what you were doing
• what changed
• what files matter
• what commands or checks already ran
• what is still broken or undecided
• what to do next

That lets you archive the heavy chat and start a fresh Codex thread from the handoff.

Copy this into each active repo chat you care about:

Create a comprehensive handoff document for this repo/session before I archive Codex history.

Include:
- repo/path and branch
- current goal
- what we already completed
- files touched or investigated
- commands/tests already run
- known errors, warnings, or failing checks
- open decisions
- constraints, user preferences, and do-not-touch areas
- the next 3-7 concrete steps

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.

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.

Safe Apply

After handoffs exist for the chats you care about, use this:

Use $keep-codex-fast to apply safe Codex maintenance.

Before changing anything, confirm that important active repo chats have handoff docs or do not need them.

Then back up first, archive instead of deleting, move stale worktrees, rotate large logs, prune dead config references, and verify the result.

If Codex is currently running, do not mutate local state. Tell me to close Codex first.

Thread Title And Preview Bloat

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.

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:

python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat

With that flag, after backing up and only when Codex is not running, it trims active SQLite title/preview metadata to bounded display values. If a thread already has a friendly name in session_index.jsonl, the repair writes that name back into the SQLite display title instead of replacing it with a shortened prompt, including already-bounded prompt fallback titles from earlier repairs.

This does not remove the actual conversation transcript. The full rollout JSONL remains available unless you separately archive the session.

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.

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.

Malformed Local Task Sessions

Some app-server integrations can leave active local-task sessions that have no user event and point at a workspace root such as / or an OS temp directory. Codex Desktop may repeatedly try to resolve those sessions, log No cwd found for local task, and make the thread list sluggish.

The script reports these candidates in report mode and normal apply mode. It does not archive them unless you explicitly opt in:

python scripts/keep_codex_fast.py --apply --archive-malformed-local-tasks

With that flag, after backing up and only when Codex is not running, it moves the matching rollout JSONL files into ~/.codex/archived_sessions/, marks those threads archived in SQLite, and writes a restore manifest/script.

This does not target normal chats. The archive predicate requires has_user_event=0, an active/unarchived thread, a suspicious cwd, and a rollout file under ~/.codex/sessions.

Weekly Or Biweekly Reminder

Recurring maintenance should be a reminder, not an automatic apply.

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.

Copy this into Codex:

Use $keep-codex-fast to create a recurring Codex maintenance reminder.

Schedule it weekly if I use Codex heavily, or biweekly if that seems safer.

The reminder should:
- run the keep-codex-fast report first
- never pass --apply or run mutating maintenance automatically
- never archive, move, prune, rotate, normalize, delete, or mutate local Codex state
- remind me to create comprehensive handoff docs and reactivation prompts for active repo chats before any manual apply
- summarize active session size, archived session size, extended path candidates, old session candidates, worktree candidates, log size, and top Node/dev processes
- report heavy Node/dev processes without killing them
- tell me that manual apply should only happen after I confirm handoffs exist or are not needed and Codex is closed

Install

Ask Codex:

Install the keep-codex-fast skill from https://github.com/vibeforge1111/keep-codex-fast

Or clone/copy this folder into your Codex skills directory as keep-codex-fast.

Advanced: Manual Script Use

Most users can stay inside Codex and use the prompts above. The script is here for people who want to run it directly.

Report only. This is read-only and privacy-safe by default:

python scripts/keep_codex_fast.py

Show raw thread IDs, chat titles, paths, and process paths only when you need detail:

python scripts/keep_codex_fast.py --details

Create backups only, without moving or changing local state:

python scripts/keep_codex_fast.py --backup-only

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.

Apply core maintenance actions. This does not trim thread title/preview metadata:

python scripts/keep_codex_fast.py --apply --archive-older-than-days 10 --worktree-older-than-days 7

By default, --archive-older-than-days uses the thread's last updated_at timestamp. If you created a handoff in an old chat and that recent update should not keep it active, use created_at instead:

python scripts/keep_codex_fast.py --apply --archive-older-than-days 10 --archive-age-field created_at

Archive one known session without changing the broad age policy:

python scripts/keep_codex_fast.py --apply --archive-thread-id 00000000-0000-0000-0000-000000000000

You can also target a rollout JSONL directly:

python scripts/keep_codex_fast.py --apply --archive-rollout-path /path/to/rollout.jsonl

Optionally repair oversized title/preview metadata only when the report recommends it:

python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat

Optionally archive malformed no-user-event local tasks when the report recommends it:

python scripts/keep_codex_fast.py --apply --archive-malformed-local-tasks

Hot-repair active Codex thread paths while Codex is running:

python scripts/keep_codex_fast.py --apply --hot-normalize-paths

This mode is intentionally narrow. It creates a backup and updates active SQLite path fields to Codex Desktop's running \\?\ path convention. It does not archive sessions, rotate logs, move worktrees, prune config, or repair title/preview metadata.

If Codex writes those path fields back while it is running, use a bounded watch window:

python scripts/keep_codex_fast.py --apply --hot-normalize-paths --hot-normalize-watch-seconds 300 --hot-normalize-interval-seconds 30

Windows users can launch the same bounded watcher hidden with:

wscript.exe scripts\run_hot_normalize_paths_hidden.vbs

Back up one stuck Codex Desktop thread and matching automations, then perform a storage-level archive-state refresh:

python scripts/keep_codex_fast.py --apply --recover-thread-id 00000000-0000-0000-0000-000000000000

This mode is intentionally narrow. It creates a SQLite backup, backs up automations whose target_thread_id matches the recovered thread, toggles the target thread through an archived state in storage, restores the thread to its original final active/archived state, restores missing matching automation definitions, and exits without moving sessions, rotating logs, pruning config, or running broad cleanup.

For Codex Desktop threads that fail to start a turn because the loaded agent loop died, the app-level archive/unarchive API is the proven cache reset. Use the storage tool first when you need an automation-safe backup/restore point, then use the Codex app archive/unarchive operation if the thread still fails to start. Recheck matching automations afterward because app-level archive/unarchive can remove thread heartbeats.

Normal report mode also scans recent logs_2.sqlite entries for agent-loop/start-turn failure signatures:

python scripts/keep_codex_fast.py --details --broken-thread-lookback-hours 72

If the report shows current valid candidates and you want the storage-level recovery path, recover detected threads explicitly:

python scripts/keep_codex_fast.py --apply --recover-detected-threads

This is still narrow and backup-first. It refreshes only detected active, non-archived thread ids whose failure log is not older than later local thread activity. Archived, missing, and stale-after-activity candidates remain visible in the report for diagnostics, but are not auto-recovered by this mode.

Wait for Codex to exit before applying:

python scripts/keep_codex_fast.py --apply --wait-for-codex-exit

What Can Change

The skill can safely handle:

• old non-pinned active sessions
• stale worktrees
• large logs_2.sqlite* and log/codex-tui.log files
• dead/temp project entries in config.toml
• Windows \\?\C:\... path mismatches in local SQLite text fields and selected metadata files such as config.toml
• active Codex thread path drift while Codex is running, only with --hot-normalize-paths
• oversized thread title and first-message preview metadata in state_5.sqlite, only with --repair-thread-metadata-bloat
• malformed no-user-event local task sessions, only with --archive-malformed-local-tasks
• a single wedged thread's archive state, only with --recover-thread-id
• current broken-thread failure-log candidates from logs_2.sqlite, only with --recover-detected-threads

It does not permanently delete chats, logs, or worktrees. It moves them into archive folders and writes backup/restore artifacts before applying changes. Restore scripts are emitted with copy-paste-safe Python commands, including when the backup path contains spaces.

Mental Model

• Chats are for execution.
• Handoff docs are for memory.
• Archives are for history.
• Fresh threads are for speed.

Flow