In Short

  • Problem: Codex Desktop felt slower and slower on my Mac.
  • What I tested: the size of ~/.codex, SQLite databases, WAL files, and archived JSONL sessions.
  • Result: ~/.codex went from roughly 18 GB to 9.3 GB, and a broad aggregation on logs_2.sqlite went from 13.96s to 0.09s.
  • Lesson: before blaming the model or the network, inspect the local state.
  • Linked repo: pezzos/codex-local-maintenance.

The Slowdown That Made Me Look Under The Hood

I started from a simple feeling: Codex was getting slower. Not a clear bug, not a reproducible error, more the impression that the app was carrying local weight before a conversation had even really started.

My first hypothesis was broad. Inside ~/.codex, several files looked like they could accumulate history: SQLite databases, write-ahead logs, .codex-global-state.json, and archived sessions. None of that proves a slowdown by itself, but the size was large enough to justify measuring instead of guessing.

The first numbers moved the suspicion away from a small preference file. The global JSON was only about 252 KB. The heavier pieces were elsewhere: ~/.codex was around 18 GB, logs_2.sqlite was 2.1 GB, its WAL could climb past 301 MB, archived sessions were 5.4 GB, and a broad aggregation on logs_2.sqlite took 13.96s.

The useful move was to stay local and factual. I checked directory sizes, identified the largest files, measured a representative SQLite query, then cleaned only what could be quarantined or compacted safely.

What Changed

The cleanup had two parts.

First, old JSONL sessions were moved into quarantine instead of being deleted blindly. That made the operation reversible and kept the evidence available if something turned out to be missing.

Second, the SQLite files were compacted. The important result was not only disk space: the same broad aggregation that previously took nearly fourteen seconds dropped to less than a tenth of a second.

That does not prove every perceived delay came from local storage. It does prove that the local state had become heavy enough to deserve maintenance.

After the pass, ~/.codex was down to 9.3 GB, archived_sessions to 894 MB, and logs_2.sqlite plus its WAL to roughly 595 MB. The numbers matter because they keep the note from becoming “I cleaned something and it felt better”.

What I Would Reuse

I would reuse the inspection pattern:

  • measure before cleaning;
  • quarantine instead of deleting immediately;
  • keep commands explicit;
  • test the same query before and after;
  • document what the script does and what it refuses to do.

The small maintenance script in the linked repo is intentionally modest. It is not a general Codex performance fix. It is a local housekeeping tool for one specific class of problem.

What Not To Copy Blindly

Do not run cleanup commands against ~/.codex without understanding what they move or compact. The directory contains account, session, and project state. A reversible quarantine is the bare minimum.

I also would not turn this into a scheduled cleanup without watching the first runs. A maintenance script is useful only if it remains more boring than the problem it fixes.

The retention thresholds are not a recommendation either. 14 days for archived sessions and 3 days for low-level logs fit this local case; they are not proof of a good default for someone else’s Codex home.

Before Reusing The Script

The linked repo contains the maintenance script, a macOS LaunchAgent template, RESULTATS.md with before/after measurements, investigation notes, and a simple credential scan.

It is there to make the local investigation inspectable before someone adapts the script to their own ~/.codex. It is not a promise of general Codex acceleration, a safe cleanup to run while Codex is writing, or a replacement for reading what will be moved.

The Lesson I Keep

When an agent tool feels slow, the interesting cause is not always remote. Sometimes the first useful investigation is local: files, logs, databases, and the boring state that quietly grows between sessions.

The rule I keep is smaller than “clean Codex regularly”: measure before cleaning, move before deleting, and automate only after one manual pass is understood.