The apply prompt in Keep Codex Fast tells Codex to stop while Codex is running

Report only is the default, and even process findings stay hands off

The whole design rests on doing nothing until asked. The script with no arguments at all is read only:

python scripts/keep_codex_fast.py

Add `--details` and it will additionally show raw thread IDs, chat titles, paths and process paths, which the summary mode keeps back. Add `--backup-only` and it writes backup folders without moving or changing local state. That third flag is the one worth knowing about, because it separates copying from mutating in a way the three named modes do not.

The report itself is aimed at finding growth rather than fixing it. It covers which local state has grown over time, active and archived session size, extended path candidates, old session candidates, stale worktrees, large logs and dead project references. Heavy Node and dev processes get reported too, and the README is explicit that they are listed, not killed.

The opening prompt you paste into Codex asks for exactly that first pass:

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

The apply prompt refuses to run in the session that asks for it

Maintenance is meant to run through a prompt, and the prompt the README offers for it is 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.

The last paragraph undoes the first. You are talking to Codex when you send this, Codex is therefore running, and the rule it is given is to decline and ask you to close it. Read literally, the prompt can only ever produce a refusal and a request that you quit the tool mid-conversation.

The underlying reason is sound. Trimming a title in a SQLite database or moving a worktree directory while another process has the same files open is a good way to corrupt state, so requiring the application to be closed is the correct precondition. The gap is that the skill is invoked from inside the application, so the manual script path is the only route that can actually satisfy it. The README does not say this plainly, and the reader has to notice the paragraph for themselves.

Thread title repair rewrites SQLite and mirrors the result into a JSONL index

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 slow before you even open a chat. The skill measures those two fields in report mode and in normal apply mode, and leaves them alone unless you ask:

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

With the flag, and only after backing up and only when Codex is closed, it trims the active SQLite title and preview values down to bounded display values. It also appends the repaired titles to `session_index.jsonl`, which the README describes as matching current Codex name-update storage. That is the load-bearing detail: the repair is not only a database edit, it also has to reproduce whatever side file Codex keeps names in, and the compatibility claim is scoped to how Codex stores names now.

Two restore artifacts land in the backup folder: a manifest holding the old full title and preview values, and `thread-metadata-repairs.jsonl` alongside a `restore-thread-metadata.py` script. The transcript itself is untouched, and the full rollout JSONL stays available unless you archive the session separately. The README's own warning is that backup folders contain private local metadata and should not be published unreviewed.

The recurring reminder template stops on the bare word worktree

Recurring maintenance is argued against automation rather than for it, on the grounds that no scheduled job can know whether you wrote handoffs for the chats you still care about. The template offered for setting one up is a longer prompt with a list of things the reminder must not do:

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

The final bullet is the last line of the block. It names five things to summarize and stops after the word `worktree`, with no noun completing the phrase and nothing after it. That matters more than a cosmetic slip, because this is the one template you hand to a scheduler rather than read yourself, and it is the template that would summarize worktree findings on a recurring basis.

Past that line, the section ends and the Install heading begins. Whether worktree paths, worktree count or worktree size belonged there is not recoverable from the text as published.

The manual section's last warning is one word short of finishing

The advanced section for running the script directly walks through the flags in order and closes on a safety note. The note is the last thing in the document, and it reads:

Wait for Codex to exit befo

There is nothing after it. The word `befo` is where the sentence stops, so the instruction that was meant to keep you from mutating state during a running session is present only as a fragment.

Read together with the second section, the two cuts line up awkwardly. The full sentence in the Safe Apply prompt already tells Codex not to mutate while it is running, and the truncated fragment in the manual section is the same warning aimed at someone running the script by hand. So the precondition is stated clearly in one place, cut off in the other, and the README never adds a closing note about verification, exit codes or what to check after a run.

The flags themselves are documented up to that point, including the only example that shows thresholds:

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

Nothing states what those two numbers mean when you leave them off.

Three named modes and six flags do not line up

The documentation offers three modes. Inspect is report only with no writes. Maintain backs up, archives old sessions, moves stale worktrees, rotates logs, prunes dead config and normalizes paths, and explicitly does not trim thread title or preview metadata. Optional repair is reachable only with `--apply --repair-thread-metadata-bloat` and shortens oversized SQLite display values after a backup.

The script takes more shapes than that. `--details` widens the report without changing what is written, and `--backup-only` creates backups while moving nothing, which is a distinct mode with no name in the three. The repair flag is not a mode either, since it is refused on its own and only takes effect alongside `--apply`.

The age thresholds have no documented defaults. The example passes `--archive-older-than-days 10 --worktree-older-than-days 7`, two specific values presented as an example with no explanation of the arithmetic behind them and no statement of what the script uses when the flags are absent. A user who copies the command gets a policy they did not choose; a user who omits the flags gets a policy they cannot see.

Path normalization is listed as part of Maintain and never appears in any of the commands.

The tree ships tests and four directories the README never mentions

The repository root is short: .github, .gitignore, LICENSE, README.md, SKILL.md, and the directories agents, assets, references, scripts and tests. LICENSE is present and the project is MIT licensed. The repository publishes no releases, and the default branch was last pushed to on 2026-05-06.

`tests/` is the entry that stands out. A directory of tests exists in the tree, and nothing in the README, the SKILL.md reference or any of the prompt templates says how to run them, what they cover or what they assert about the archive and repair paths. The same goes for `agents/`, `references/` and `assets/`: all three are in the tree, none is referenced from the visible text.

Installation has two routes, and both name the folder. You ask Codex to install the skill from the repository URL, or you clone or copy the folder into your Codex skills directory as `keep-codex-fast`. The name is not cosmetic, since every prompt in the document invokes it as `$keep-codex-fast`, so a folder installed under any other name breaks the calls that drive it.

The entry point for humans is the `$` prompt. Everything the README offers is a prompt template to paste, plus the script underneath for people who would rather stay at a shell.

Editorial conclusion

Use keep-codex-fast in its report-only mode and decide for yourself what to keep. The archiving, handoff and stale-worktree logic is the useful part, and the skill is unusually clear that it should never delete. Two things to check before you let it write: the repair path edits SQLite fields inside Codex's own state and mirrors titles into a separate JSONL index that matches what Codex currently does, so it is coupled to a format that can change under you; and the Safe Apply prompt cannot complete inside the session that runs it, because it also instructs Codex to refuse to mutate anything while Codex is open. The tree ships tests, but the README says nothing about running them.

Frequently asked questions

Official sources

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