If you use Codex CLI every day, you’ve definitely lived this: your session list gradually turns into a graveyard. That bugfix from last Tuesday. That spike you abandoned halfway through. Three nearly identical “quick test” sessions you never named. None of them serve you anymore, but they’re all still there — and every time you run codex resume to find the one session that actually matters, you have to wade through all the junk.
OpenAI released a solution for exactly this problem, and almost nobody is using it yet: session archiving. Here’s the complete workflow — archiving, restoring, and how it works with resume and fork.
The problem that archive actually solves
codex resume --last finds the most recent matching session by reading your local state DB. On a fresh install that’s instant. After a few months of heavy use, with hundreds of sessions piled up locally, the restore becomes noticeably slower — OpenAI’s recent release notes explicitly mention that they sped up resume --last on “large local histories”. The more dead sessions you drag along, the more weight each search carries.
Archiving is the cleanup. It takes a session off your active list without deleting anything. The work is still there if you need it back — it’s just out of the way.
Archiving from inside a session
The simplest way is the slash command. Inside an active Codex session, you type:
/archive
Codex asks for confirmation, then archives the current session and closes the TUI. One detail worth knowing: it archives and exits in one move. So /archive isn’t a command to “tidy up and keep working” — it’s the clean way to close a session you’re done with. (If you just want to exit without archiving, that’s still /quit or /exit.)
Codex also disables /archive while a task is running. You can’t archive a session in the middle of a turn — finish or cancel the work first.
Archiving from the command line
You don’t need to be inside a session to archive it. From your shell:
codex archive
codex unarchive
codex archive moves a session to archived status; codex unarchive brings it back to your active list. This is the part that makes archive genuinely useful for cleanup — you can organize your history in bulk from outside the TUI, then restore any session the moment you need it again.
The rule that prevents accidents: archived ≠deleted
This is what makes archiving safe to use without worry. Archived sessions are protected from resume and fork until you restore them.
In practice that means:
- An archived session doesn’t show up when you do
resume— that’s the whole point, it’s off your active list. - You can’t accidentally
forkan archived session into a new branch. Codex blocks it. - Nothing gets destroyed. The session is intact; it’s just behind an
unarchivefirst.
So the mental model is clear: archive is a reversible “save this” not a destructive “throw this away”. If you’ve been hesitant to clean up old sessions because you’re afraid of losing context you might need later — that fear doesn’t apply here. Archive without worry. Restore when you actually need it.
A workflow that keeps your list usable
Putting it all together, here’s a habit worth adopting:
- You finish a piece of work → archive it with
/archive. Closing a session you’re done with should be the default ending, not leaving it open “just in case”. - Once a week, run
codex archiveon obviously dead sessions — abandoned spikes, throwaway tests, anything you know you won’t touch again. - When you need an archived session back, run
codex unarchiveand it returns to your active list, untouched.**
The benefit is that resume and resume --last stay fast and actually show you the sessions you’re working on now — not six months of accumulated noise.
An honest caveat
Archive manages your local session list. It’s a housekeeping tool, not a backup strategy or sync mechanism — don’t treat archiving as “saving” work somewhere safe. Commit your code the normal way. What archive does well, and all it claims to do, is keep your day-to-day session list clean and your restores fast. For that specific job, it’s the feature most power users don’t know they already have.