codex-tmpram

English · 繁體中文

Keep OpenAI Codex's runaway SQLite log and temp files off your SSD by redirecting them to a RAM disk.

Not affiliated with OpenAI. This is an independent, third-party utility — not affiliated with, endorsed by, or sponsored by OpenAI. "Codex" and "OpenAI" are trademarks of OpenAI, referenced here only to describe the software this tool works with.

The problem

OpenAI Codex ships an unpatched, TRACE-level SQLite logger at ~/.codex/logs_2.sqlite. It:

• ignores RUST_LOG — you can't turn it down,
• rewrites the same pages every ~1.7s via WAL/checkpoint churn (massive write amplification),
• spills SQLite temp files (etilqs_*) into $TMPDIR on the SSD as well.

Real-world reports show tens of TB written in a few weeks from this alone. As a bonus bug, once logs_2.sqlite grows past ~200 MB the Codex CLI tends to crash mid-session.

The data in that log is disposable telemetry meant for OpenAI's own debugging — it's of no use to you, and it's wiped every reboot anyway.

Refs: openai/codex#28224, #29876

The fix

This tool creates a real macOS RAM disk (hdiutil attach ram://…, fixed volume name CodexTmpRam) and:

1. Symlinks ~/.codex/logs_*.sqlite → the RAM disk (wildcard survives future renames like logs_3.sqlite).
2. Exports SQLITE_TMPDIR → …/tmp on the RAM disk via your ~/.zshrc, so Codex's temp spill lands in RAM too.
3. Installs a LaunchAgent that rebuilds + relinks the RAM disk every 5 minutes (self-heals after reboot / accidental eject) and truncates the log if the RAM disk ever runs low on space — so Codex never hits an out-of-space crash.

Your real data (OrbStack, browser profiles, etc.) is never touched. Only Codex's disposable log/temp moves, and only into RAM.

✅ Net effect: for the SSD this is equivalent to /dev/null (zero persistent writes), but Codex still sees a fully functional file — so SQLite doesn't break the way it would with an actual /dev/null symlink.

Requirements

• macOS (Apple Silicon or Intel)
• zsh as your shell (default on modern macOS)
• Enough free RAM for the disk you choose (default 1 GB)

Install

git clone https://github.com/taigadit/codex-tmpram.git
cd codex-tmpram
chmod +x codex-tmpram.sh

# 1 GB RAM disk (default)
./codex-tmpram.sh install

# or pick a size in MB
./codex-tmpram.sh install 512

Or use the one-shot installer, which chmods everything and runs the steps for you:

./install.sh          # 1 GB
./install.sh 512      # custom MB

Then, as the installer reminds you:

source ~/.zshrc        # or just open a new terminal
pkill -f codex         # restart Codex so it re-reads SQLITE_TMPDIR

Verify

./codex-tmpram.sh status

You want to see the log as a symlink to /Volumes/CodexTmpRam/…, the LaunchAgent loaded, and SQLITE_TMPDIR set. To watch writes actually land in RAM:

sudo fs_usage -w -f diskio | grep -E 'logs_.*sqlite|etilqs'
# device column should be the RAM disk's /dev/diskN, never your SSD's disk3s5

Uninstall

./codex-tmpram.sh uninstall
source ~/.zshrc        # clear SQLITE_TMPDIR
pkill -f codex

This removes the LaunchAgent, the ~/.zshrc block, the symlinks, and ejects the RAM disk. Codex will create a normal log on the SSD again on next launch.

⚠️ Uninstalling re-enables Codex's SSD-burning logger. Until OpenAI fixes the upstream bug, you probably want to leave this installed.

Removing the original (pre-open-source) setup

If you previously ran the first-generation install (LaunchDaemon com.osdog.codex-ramdisk, volume CodexRAM), uninstall-legacy.sh detects and removes only that — it never touches the newer CodexTmpRam install:

./uninstall-legacy.sh --check     # detect only, change nothing (no sudo)
sudo ./uninstall-legacy.sh        # remove (asks before destructive steps)
sudo ./uninstall-legacy.sh --yes  # remove without prompts (headless)

How it survives reboots

A RAM disk vanishes on shutdown. The LaunchAgent's RunAtLoad rebuilds it at login, and StartInterval (every 300 s) re-checks and re-links continuously, so even if something is started before the RAM disk is ready, it's repaired within minutes. The ~/.zshrc export is guarded by [ -d …/tmp ] so a shell opened too early simply doesn't set a stale value.

What's on the RAM disk (all disposable)

File	Purpose	Safe to lose on reboot?
logs_*.sqlite (+ -wal/-shm)	Codex TRACE telemetry	Yes
tmp/etilqs_*	SQLite temp spill	Yes

Nothing else. No application data is relocated.

Checking your SSD's actual wear

smartctl -A /dev/disk0 | grep -E 'Percentage Used|Data Units Written'

Percentage Used is the SSD's own lifetime-wear estimate. Record it occasionally to confirm the redirect is keeping your write rate down. (Some Apple Silicon machines can't expose SMART; that's normal.)

Bonus: measure how much you're saving

codex-tmpram-stats.sh logs the writes diverted from your SSD into a CSV and renders a one-click HTML dashboard.

The idea: every byte written to the RAM disk is a byte that would have hit the SSD (WAL rewrites and all). Sampling the RAM disk's write throughput and extrapolating over time gives you a running "saved" total — shown next to your SMART Percentage Used, which should barely move.

chmod +x codex-tmpram-stats.sh

# interactive — pick auto-sampling or manual, the script asks you
./codex-tmpram-stats.sh setup

# on/off switch for auto-sampling (your CSV/history is always kept)
sudo ./codex-tmpram-stats.sh start      # turn ON (every 30 min)
sudo ./codex-tmpram-stats.sh start 15   # ON, every 15 min
sudo ./codex-tmpram-stats.sh stop       # turn OFF — stops sampling, keeps all data
sudo ./codex-tmpram-stats.sh toggle     # flip on/off

# ── or drive it directly ──
# take one measurement (needs sudo — fs_usage is root-only)
sudo ./codex-tmpram-stats.sh sample          # 20s window, default
sudo ./codex-tmpram-stats.sh sample 30        # 30s window

# build & open the HTML dashboard (no sudo, no internet)
./codex-tmpram-stats.sh report

# quick text summary
./codex-tmpram-stats.sh show

# optional: auto-sample every 30 min so the CSV builds itself
sudo ./codex-tmpram-stats.sh install-timer 30
sudo ./codex-tmpram-stats.sh uninstall-timer

Outputs live in ~/.codex/tmpram-stats/:

• savings.csv — open in Excel/Numbers; columns include SMART DUW, Percentage Used, RAM-disk MB/s, and the cumulative saved total.
• report.html — self-contained dashboard: headline "saved" figure, SMART wear, and two trend charts. Double-click to open offline.

The saved figure is an estimate (sample-window throughput extrapolated across the interval between samples). More frequent sampling = a tighter estimate. SMART Data Units Written / Percentage Used remain the ground-truth cross-check.

Notes on sampling

• Throughput is measured with iostat, not fs_usage. fs_usage needs a controlling tty and silently captures nothing from a non-interactive script. iostat reads the RAM disk's whole-device write rate — and since the RAM disk holds essentially only Codex's log/temp, that rate is the SSD writes you're avoiding.
• Sample while Codex is actually working. The logger only churns when Codex runs a task; idle, it's near zero. A single sample that happens to land in an idle window will read ~0 MB/s — that's correct, not a bug. The auto-sampler (start) catches busy and idle windows over time, so the cumulative total reflects reality.
• Always run via bash/the shebang, not sh script.sh. The scripts re-exec themselves under bash if invoked as sh, but the cleanest path is ./codex-tmpram-stats.sh ….
• Running as sudo keeps the CSV under the invoking root's home if you sudo -i first. Prefer sudo ./codex-tmpram-stats.sh sample (single command) so $HOME stays your own user's.

License

MIT — see LICENSE.

Trademarks

"OpenAI" and "Codex" are trademarks of OpenAI. This project is independent and is not affiliated with, endorsed by, or sponsored by OpenAI; those names are used solely to identify the software with which this tool is compatible.