history.max_bytes

Values

Setting	What it takes	Default
history.max_bytes	A positive integer, counted in bytes	unset (no cap)

Codex saves each session’s transcript to history.jsonl inside $CODEX_HOME (that’s ~/.codex on a default install), and max_bytes is the ceiling on that one file. Once it grows past your number, the oldest entries get dropped so the file stays under the cap. Leave the key out and there’s no ceiling, so the file just keeps growing.

[history]
persistence = "save-all"   # save-all (default) | none
max_bytes = 5242880        # 5 MiB cap; oldest entries trimmed when exceeded

When to change it

• Your ~/.codex/history.jsonl has ballooned after months of daily use and you want it bounded without switching history off.
• You’re on a small disk or a tight container volume and want a hard ceiling on what Codex writes.
• You still want session recall working (so persistence = "none" is off the table), but you don’t need years of old transcript sitting on disk.

If you want history gone completely instead of capped, that’s history.persistence = "none", a separate lever.

Gotchas

• It does nothing when history.persistence = "none". No file gets written, so there’s nothing to trim. The two keys work together: persistence decides whether the file exists, max_bytes decides how big it’s allowed to get.
• The docs don’t publish a default, so unset means unbounded. If you never set it, history.jsonl has no ceiling at all.
• Trimming drops the oldest entries, so your earliest sessions are the first to go once you cross the cap. The docs say it trims when the file is exceeded but don’t spell out exactly when that check runs (each write vs. startup), so don’t count on a precise moment.
• This caps history.jsonl only. It doesn’t touch logs under log_dir or the SQLite state DB under sqlite_home, which grow on their own rules.

Related settings

• /config/history-persistence/: the on/off switch for saving transcripts. max_bytes only matters when this is set to save-all.
• /config/sqlite-home/: directory for the SQLite-backed state DB. Separate storage that max_bytes doesn’t cover.
• /config/log-dir/: where log files land (default $CODEX_HOME/log). Another disk-usage source worth watching if space is tight.