keep-codex-fast: a backup-first maintenance skill for local Codex state

The problem: Codex local state grows and nothing prunes it

Codex accumulates state on disk. Chats, terminals, logs, worktrees and project history all persist, and after weeks of use the local footprint gets heavy. The README frames the symptom plainly: Codex starts feeling heavy after weeks of chats, terminals, logs, worktrees and project history. Nothing in the description suggests a background daemon that fixes this. The skill is a maintenance pass you run deliberately.

The intended audience is narrow and specific. You keep long chats, you resume old threads often, you work across many repos, you run multiple terminals or dev servers, and you want maintenance to feel safe rather than scary. If you start a fresh Codex session every day and never resume anything, the archiving half of this tool has little to act on. The worktree and log rotation parts could still apply, but the value proposition is weakest for short-lived, single-repo use.

The design rule the README states is: make handoffs first, archive, don't delete, apply changes only when you are ready. That ordering is the whole product. Everything else is file movement.

Report mode, maintain mode and the opt-in SQLite repair

The skill has three modes. Inspect is report-only with no writes. Maintain is the normal apply: it backs up, archives old sessions, moves stale worktrees, rotates logs, prunes dead config, and normalizes paths. It explicitly does not trim thread title or preview metadata. The third mode is optional repair, gated behind `--apply --repair-thread-metadata-bloat`, which shortens oversized SQLite display title and preview metadata after a backup.

The mechanism behind that repair is worth understanding because it is the most unusual part of the project. According to the README, some Codex builds store a full first user prompt as both the thread title and the list preview. When those fields reach hundreds of thousands of characters, thread navigation gets sluggish before you even open the large chat. The script reports the size of those payloads in both report mode and normal apply mode, and trims them only when you opt in. The transcript is not touched: the full rollout JSONL remains unless you separately archive the session.

That separation is the correct call. Title and preview are display data; the transcript is the record. Trimming display data while leaving the record alone is a small, reversible operation. The repair manifest stores the old full title and preview values so they can be restored, and repaired titles are appended to `session_index.jsonl`, which the README says matches current Codex name-update storage.

Installing keep-codex-fast and running a first report

The README gives two install routes. The first is to ask Codex to install the skill from the repository URL. The second is to clone or copy the folder into your Codex skills directory under the name `keep-codex-fast`.

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

Once it is in place, the first real use is an inspection, not a cleanup. Ask Codex for a report and a recommended plan:

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

Codex should show you what it found before anything changes. You then decide what to hand off, what stays active and what can be archived. If you prefer the command line, the script lives at `scripts/keep_codex_fast.py` and the bare invocation is read-only:

python scripts/keep_codex_fast.py

Add `--details` when you need raw thread IDs, chat titles, paths and process paths. Add `--backup-only` to create backups without moving or changing local state. Note that the README ends mid-sentence at the apply section, so the exact flags for core maintenance actions are not fully spelled out in the text available; read the script before running an apply.

Handoffs are the precondition, not an optional extra

The skill will archive old chats. Before that, you are expected to create handoff documents for any repo or session you may want to continue. The README defines a handoff as a small continuity note capturing what you were doing, what changed, which files matter, which commands or checks already ran, what is still broken or undecided, and what to do next. It also asks for a reactivation prompt you can paste into a fresh Codex chat so the new thread can continue without the old context.

The suggested location is `docs/codex-handoffs/YYYY-MM-DD-topic.md` unless the repo already has a better place. This is the part of the workflow with the most manual effort and the least automation, and that is deliberate. The README states the reason for the reminder-only design directly: an automation cannot know whether you created handoffs for chats you still care about. So the recurring reminder runs the report, never passes `--apply`, and never archives, moves, prunes, rotates, normalizes or deletes anything on its own.

That is a defensible trade-off, but it is a trade-off. A tool that refuses to act unattended will not keep your state small unless you actually do the handoff work. If you ignore the reminders, the skill reports the same growth every week.

What it will not do: close Codex, kill processes, or replace fast mode

Several real limits are visible in the documentation. The skill does not kill heavy Node or dev processes; it reports them. If your machine is slow because a dev server is eating CPU, this tool tells you and stops there.

It also will not mutate local state while Codex is running. The safe-apply prompt tells Codex to refuse and ask you to close Codex first. So maintenance is a stop-the-world operation: you close the app, run the apply, then reopen. For anyone who keeps Codex open all day, that is friction you have to schedule around.

The biggest mismatch is in the name. This is not Codex fast mode. It does not change model routing, response latency or inference speed. The search results around this project mix the two ideas, and the repository does nothing about the second one. If your complaint is that Codex replies slowly, this skill is the wrong tool. It addresses disk state: session size, worktree placement, log size, dead config references and oversized display metadata. Those can make navigation sluggish, but they are not the same thing as a slow model.

One more boundary: the backup folders contain private local Codex metadata. The README says to keep them on your machine and not publish or share them without reviewing the contents, and to treat `thread-metadata-repairs.jsonl` and `restore-thread-metadata.py` as especially sensitive.

How it differs from a general cleanup script

The obvious alternative is a shell script that deletes old session files and moves worktrees. That approach is faster to write and needs no skill runtime, but it has no notion of a handoff and no report-only default. You point it at a directory and it removes things.

keep-codex-fast inverts the default: report first, write only on request, and archive rather than delete. It also carries domain knowledge a generic script would not have, specifically the SQLite title and preview bloat pattern and the `session_index.jsonl` name-update storage that repaired titles are appended to. A generic cleaner would either ignore that metadata or delete the rows outright.

The cost of the difference is that keep-codex-fast is a Codex skill, so it is meant to be driven through prompts inside Codex, with the Python script as an advanced escape hatch. If you want a cron job that runs unattended at 3am, this is not that, and the README argues explicitly that it should not be.

Maintenance, licence and what to verify before you rely on it

The repository is not archived. The last push was on 2026-05-06, which is more than four months before the date used for this review, so treat it as a project that has not seen recent commits rather than one under active development. There are no releases, so installation means copying the folder or asking Codex to pull it from the repository URL. There is no version pin to hold, which matters if you want reproducible behaviour across machines.

The licence is MIT, which permits use, modification and redistribution with the licence and copyright notice retained. That is a permissive choice with few obligations, but it also means no warranty and no support commitment. Nothing here is legal advice; read the LICENSE file in the repository root.

Upgrade cost is the thing to think about. Because the skill copies into your Codex skills directory, updating means replacing that folder, and any local edits you made to `scripts/keep_codex_fast.py` would be overwritten. Keep your changes in a separate file or a fork. The script is Python, so a mismatch between your Python version and what the script expects is a plausible failure mode, though the README does not state a minimum version.

Editorial conclusion

Adopt keep-codex-fast if your Codex threads, logs and worktrees have grown over months and you want a report-only first pass that never mutates state without --apply. Skip it if you want Codex's own fast mode, since this skill does not change model routing or latency at all, and skip it if you are not willing to close Codex during a repair. Before running anything, read scripts/keep_codex_fast.py and confirm what --apply touches; then run the report and check that it names your session directories and worktree paths correctly.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. vibeforge1111/keep-codex-fast on GitHub