Keep Codex Fast Tutorial: Speed Up a Sluggish Codex CLI Without Losing Chat History (2026)

After three months of heavy Codex CLI use, my ~/.codex directory was 11.4 GB. The logs_2.sqlite-wal file alone was 4.8 GB. Codex took roughly nine seconds to open a fresh thread, and the resume list took longer than that. The fix the internet keeps recommending, rm -rf ~/.codex/sessions, would have nuked an active conversation about a database migration I had not finished writing, plus three weeks of context on a refactor I planned to resume.

That kind of cleanup is not actually a "delete" problem. It is a "what do I keep, what do I archive, and how do I make sure the chats I care about can come back" problem. Keep-codex-fast is a backup-first Python skill that treats local Codex state exactly that way: inspect first, write handoff documents for the threads that still matter, archive (not delete) the rest, and verify the result. It picked up 636 GitHub stars in its first 48 hours, so the pain is clearly widely felt. This tutorial walks the full pattern end-to-end on a real install. (For an adjacent open-source CLI walkthrough, see our Claude Ads PPC audit tutorial.)

TL;DR: keep-codex-fast is a Python skill (Apache-licensed, ~28 KB single script, 636 GitHub stars in its first 48 hours as of 2026-05-04) that diagnoses why a heavy-use OpenAI Codex CLI feels slow. The four growth vectors are bloated SQLite logs (openai/codex#16270), ~/.codex/sessions/ that persist indefinitely, stale worktrees, and dead config.toml entries. The skill archives all four safely after you have created handoff documents for any chat you might want to resume. Default mode is read-only; nothing is moved or deleted until you pass --apply. Source: github.com/vibeforge1111/keep-codex-fast.

What Is keep-codex-fast?

Keep-codex-fast is a Python skill (~28 KB, single script) for OpenAI Codex CLI users that inspects local Codex state (SQLite databases, session JSON files, worktrees, and config.toml) and recommends a maintenance plan. By default it only reports. It does not write files, create backups, move folders, or change any local Codex state until you explicitly pass --apply. The repo is Apache-2.0, was published on 2 May 2026, and accumulated 636 GitHub stars in its first 48 hours, which is roughly the timeline on which "my Codex CLI is unusable" turned from a niche complaint into a shared problem.

The skill is designed for a specific user. You keep long chats around. You resume old threads often. You work across many repos. You run multiple terminals or dev servers. You want maintenance to feel safe, not scary. If any two of those are true, the SQLite databases under ~/.codex are bigger than you think and the resume list is slower than it should be.

The mental model is four lines, copied from the README:

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

The reason this matters is that every other "fix slow Codex" answer on the internet collapses those four lines into one: delete. That is what rm -rf ~/.codex/sessions does. It is also what destroys the half-finished thought you were going to come back to next week. The keep-codex-fast pattern is to keep the four lines distinct, with the human in charge of the handoff step that an automation cannot do safely.

Why Does Codex CLI Get Slow?

Codex CLI accumulates four kinds of local state that grow without bound. (1) Per-session JSON in ~/.codex/sessions/ that the CLI does not auto-prune; the open feature request to add inactivity-based archival is openai/codex#13457. (2) SQLite log databases (logs_1.sqlite, logs_2.sqlite, state_5.sqlite) that grow unboundedly because SQLite does not reclaim disk space after DELETE without an explicit VACUUM; that is documented in openai/codex#16270 with reports of databases growing "far outside any documented normal range" and triggering write-lock contention plus auto-restart loops. (3) Codex-managed worktrees from automation runs you forgot to unpin. (4) Dead project entries in ~/.codex/config.toml pointing to repos you have moved or deleted.

Each one degrades startup in a slightly different way. Per-session JSON makes the resume-list query slower. SQLite WAL replay on a 4 GB log file delays first interaction. Worktree enumeration on first open scans every pinned directory, including the dead ones. And config.toml drift triggers warnings or silent retries against paths that no longer exist. None of it is fatal on day one. All of it is cumulative.

Codex 0.114.0, the March 2026 "operations release," added an opt-in setting that auto-cleans Codex-managed worktrees, which addresses one of the four vectors. The other three are still on the user. That is the gap keep-codex-fast fills, until and unless OpenAI ships built-in equivalents.

How Do You Install keep-codex-fast?

Two install paths exist. The Codex-native install is a one-line prompt you paste into Codex itself; the agent clones the repo into your skills directory. The manual path is a regular git clone, which is what I recommend for a first run because it makes the script directly inspectable. The repo is two days old at the time of writing, so a commit-SHA pin matters more than a tag.

# Manual install (recommended for the first run)
git clone https://github.com/vibeforge1111/keep-codex-fast
cd keep-codex-fast

# Pin to a known commit so an upstream change does not surprise you
git rev-parse HEAD > .pinned-sha

# Confirm the script works (--help is read-only and harmless)
python3 scripts/keep_codex_fast.py --help

The script is a single Python file with no third-party dependencies; Python 3.9 or later is enough. The Codex-native install is the prompt the README documents, pasted directly into a Codex chat:

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

Either path produces the same result: a runnable Python script that operates on your ~/.codex directory. Nothing about install touches local state, so this step is inert.

Step 1: Inspect First (Read-Only Report)

Always run the report mode first. The default invocation is python scripts/keep_codex_fast.py with no flags. This is privacy-safe and read-only. The README is unambiguous: "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."

# The default report. Read-only, nothing is touched on disk.
python3 scripts/keep_codex_fast.py

# Add --details when you need to see thread IDs, chat titles, and process paths
python3 scripts/keep_codex_fast.py --details

The output groups findings into seven buckets: active session size, archived session size, extended path candidates, old session candidates, worktree candidates, log size, and the top Node and dev processes Codex has spawned. "Extended path" is the Windows-specific case where Codex stores paths as \\?\C:\... in SQLite text fields and resolves them inconsistently on subsequent loads, which surfaces as dead resume entries.

Backup folders, when they exist, contain private local Codex metadata. Keep them on your machine and do not publish or share them unless you have reviewed the contents. The --details output in particular includes raw chat titles and thread IDs.

Step 2: Write Handoff Docs Before Archiving

This is the step that separates keep-codex-fast from rm -rf. Before archiving any active chat you might want to resume, paste a handoff prompt into that chat to generate a continuity document. The handoff captures repo and branch, current goal, what is already done, files touched, commands run, known errors, open decisions, and the next 3 to 7 concrete steps. It also produces a reactivation prompt you paste into a fresh Codex thread.

The verbatim handoff prompt from the README, which you paste into the chat you are about to archive:

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.

I ran this against an 11-week-old chat I had been resuming intermittently for a database-migration project. The handoff came back as a 240-line markdown file with three things that mattered: a precise list of the migrations that had been written, a flagged "do-not-touch" note about a column rename that had been controversial, and a reactivation prompt that started "You are continuing a Postgres-to-Aurora migration paused on 2026-04-22…". I pasted the reactivation prompt into a fresh Codex thread, and the second turn of the new thread suggested the exact next migration I was planning to write next. The handoff worked.

The pattern is worth doing for every active chat you might want to come back to, even if you do not plan to archive it this week. A handoff is cheap to write and free to keep. The chat that does get archived eventually is recoverable from the archive folder regardless, but the handoff is what lets you skip rehydrating it.

Step 3: Apply Maintenance Safely

Once handoffs exist for the chats you care about and Codex itself is closed, run the apply step. The README lists four invocations. The one most users will reach for first is the threshold-driven apply, which archives sessions older than ten days and worktrees older than seven, and rotates SQLite logs in place:

# Backup-only. Write a snapshot but do not move anything.
python3 scripts/keep_codex_fast.py --backup-only

# The standard apply with conservative thresholds
python3 scripts/keep_codex_fast.py --apply \
  --archive-older-than-days 10 \
  --worktree-older-than-days 7

# Block until Codex is closed before applying
python3 scripts/keep_codex_fast.py --apply --wait-for-codex-exit

What changes on disk: old non-pinned active sessions are moved to an archive folder; stale worktrees are moved out of the hot path; large logs_2.sqlite* files are rotated; dead and temporary project entries in config.toml are pruned; Windows extended-path mismatches in SQLite text fields are normalized. What does not change: any pinned session, any chat with an explicit "do not touch" marker, anything inside the archive folder itself, and anything that was already backed up by the --backup-only step. The README is direct on this point: the script "does not permanently delete chats, logs, or worktrees. It moves them into archive folders and writes backup/restore artifacts before applying changes."

Step 4: Verify the Result

Re-run the report after --apply and check three things. The ~/.codex total size has dropped by the amount the report predicted; one of the archived sessions is restorable from the archive folder (test it by moving the file back); and Codex CLI cold-start is faster. A rough time codex --help works as a sanity check. On the install I started this post with, that dropped from roughly 9 seconds to under 2 seconds after the first apply. Restoring a chat from the archive folder is a file-move, not a recovery operation, because the script writes the original paths into the archive index.

# Re-run the report and compare to the pre-apply numbers
python3 scripts/keep_codex_fast.py

# Sanity-check Codex cold start
time codex --help

# Restore an archived chat by moving it back (paths are preserved)
mv ~/.codex/archive/sessions/<archived-thread-file> ~/.codex/sessions/

If anything went wrong, the backup artifact written before --apply is the escape hatch. The README is explicit that the script is non-destructive by design; the worst case is that a chat you wanted is in the archive folder rather than the active folder, and you move it back.

How Do You Make Codex Maintenance a Habit?

Schedule the report (not --apply) weekly if you are a heavy Codex user, biweekly if you are moderate. The README is explicit about why: an automation cannot know whether you have created handoffs for the chats you still care about, so it should inspect and remind, never archive automatically. The reminder pattern is the third leg of the workflow, after inspect-first and handoff-before-archive.

The README provides a verbatim Codex-native reminder prompt. Paste it into Codex once, and Codex schedules the recurring report:

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

The reminder is doing the work that openai/codex#13457 has been asking for since early 2026, except in a way that intentionally refuses to auto-apply. (For a similar "the human is the only one who can decide" pattern in a different domain, see our Meta Ads MCP tutorial.) That is the design choice. An automation cannot evaluate whether the half-finished refactor in thread 9482 still matters; you can.

How Does keep-codex-fast Compare to Codex 0.114.0's Built-in Cleanup?

Codex 0.114.0, the March 2026 release that was widely framed as an "operations release," shipped three things relevant to local-state hygiene: an opt-in setting that auto-cleans Codex-managed worktrees, edge-case fixes for stdio MCP server cleanup and plugin MCP approval persistence, and removal of the legacy artifact tool plus the old read_file and grep_files handlers as part of ongoing tool-surface cleanup. None of those touch the SQLite log databases, the indefinite session retention, or config.toml drift. (Source: Codex changelog.)

The two are complementary, not competing. Leave the built-in worktree cleanup on. Run keep-codex-fast for the SQLite, sessions, and config layers. If OpenAI ships built-in equivalents in a later release, the keep-codex-fast pattern still has value because the handoff-before-archive step is the part that depends on a human, not an automation.

Frequently Asked Questions

Why is my OpenAI Codex CLI so slow?

Codex CLI accumulates four kinds of unbounded local state: per-session JSON in ~/.codex/sessions/ that the CLI does not auto-prune, SQLite log databases (logs_1.sqlite, logs_2.sqlite, state_5.sqlite) that grow without bound because SQLite does not reclaim space after DELETE without an explicit VACUUM, Codex-managed worktrees from automation runs you never unpinned, and dead project entries in ~/.codex/config.toml. On heavy-use installs that translates to multi-gigabyte databases, write-lock contention, and multi-second cold-start latency. The unbounded SQLite growth is documented in openai/codex#16270 and the missing session auto-archive is the open feature request openai/codex#13457.

Is it safe to delete the ~/.codex/sessions folder?

Not without a handoff document for any chat you might want to resume. The folder contains every active and resumable Codex thread, and the CLI uses those files to populate the resume list and reload context. The keep-codex-fast skill archives instead of deletes: old sessions are moved into an archive folder and a backup artifact is written before any change, so restoration is a file-move rather than a recovery operation. Run the keep-codex-fast report first, write handoffs for the threads that matter, and then apply maintenance.

What is keep-codex-fast?

Keep-codex-fast is a backup-first Python skill for OpenAI Codex CLI users that inspects local Codex state and recommends a safe maintenance plan. By default it only reports; it does not write files, create backups, move folders, or change local Codex state until you explicitly pass --apply. The skill handles old non-pinned active sessions, stale worktrees, large logs_2.sqlite files, dead project entries in config.toml, and Windows extended-path mismatches in SQLite text fields. Source: github.com/vibeforge1111/keep-codex-fast (Apache-2.0, 636 GitHub stars in its first 48 hours as of 2026-05-04).

Does keep-codex-fast work on Windows?

Yes. The skill specifically handles the Windows extended-path mismatch where Codex stores paths as \\?\C:\… in SQLite text fields but resolves them differently on subsequent loads, causing dead references that slow the resume list. macOS and Linux are also supported. The single Python script has no third-party dependencies and runs on Python 3.9 or later on all three platforms.

What happens if Codex is open while I run --apply?

Do not. The keep-codex-fast README is explicit: if Codex is currently running, do not mutate local state. Codex holds open file handles on the SQLite databases and on the active session JSON, so concurrent mutation can corrupt state. The script provides --apply --wait-for-codex-exit which blocks until Codex closes before applying changes. The safer pattern is to close Codex manually first, then run --apply on a quiet machine, then restart Codex and verify the resume list still works.

How is this different from the worktree cleanup that shipped in Codex 0.114.0?

Codex 0.114.0 added an opt-in setting that auto-cleans Codex-managed worktrees, but it does not address the other three growth vectors: SQLite log bloat, indefinite session retention, or config.toml drift. Keep-codex-fast covers all four, and it does so with a handoff-before-archive workflow that Codex itself does not provide. The two are complementary: leave the built-in worktree cleanup on, and run keep-codex-fast for the SQLite, sessions, and config layers.

The Bottom Line

The Codex CLI does not yet manage its own local state. After three months of heavy use, the ~/.codex directory accumulates multi-gigabyte SQLite logs that never get VACUUM-ed, sessions that never get pruned, worktrees that never get unpinned, and config.toml entries that point at directories that no longer exist. The community workarounds (rm -rf ~/.codex/sessions, manual VACUUM, deleting worktrees by hand) work mechanically and lose context aggressively. Keep-codex-fast is the first public approach that treats local Codex state as a backup problem first and a maintenance problem second: inspect read-only, write handoffs, archive instead of delete, verify the result.

Clone the repo, run python3 scripts/keep_codex_fast.py against your own ~/.codex, and read the report before you do anything else. Most heavy users will find at least one log file over a gigabyte and at least one session that is older than they remember. Write handoffs for the threads that still matter, then apply with conservative thresholds, then re-run the report to confirm the dial moved. Total time is under thirty minutes, and what you keep is everything except the bloat. (For adjacent open-source AI tooling on the same axis of "local-first, restorable, no vendor lock-in," see our coverage of Agent Zero, the Matt Pocock dictionary of AI coding, and the self-hosted Meetily install guide.)