No “resume” in Codex CLI, so I built one: quickly “continue” with `codex-history-list`

[Yuki Shindo]

Codex CLI is an AI coding agent that runs in your terminal, but there’s still no official “resume” feature.

If a session drops or you want to pick it up later, you can’t resume as-is—super inconvenient.
So, as a stopgap, I built a small CLI that lists past sessions so you can manually resume them quickly. That’s codex-history-list.
(I’m assuming Codex CLI will eventually get resume, so I haven’t published this to npm; it’s open source for personal use, macOS-first.)

Note: As of 2025-09-03, there’s no official /resume command. There are feature requests on GitHub.

Problem: Continuing a session is hard​

• Once you close the CLI, the context is gone, which makes longer tasks or picking things up later a pain.
• Codex CLI does save each session’s log as JSONL under ~/.codex/sessions, but there’s no official flow to load and resume those logs.

Background: There is a door to “experimental resume”​

Codex CLI has a config file (~/.codex/config.toml) and a -c key=value flag to temporarily override settings. There’s even an experimental_resume key in the template.
In other words, if you pass the path to a JSONL when launching, you can pseudo-resume a session (but it’s “experimental,” so handle with care).

Solution: Use codex-history-list to quickly pick the right log to resume​

codex-history-list recursively scans ~/.codex/sessions and minimally parses each JSONL to display a table with just the essentials.

• cwd (the working directory for that session, extracted from <environment_context>)
• first user prompt (ask) (environment/instruction blocks are skipped for readability)
• time (mtime or internal timestamp)
• path (full path, not truncated—ready to copy/paste)

Other niceties: multibyte-safe alignment, JSON output, date/dir filters, sorting, etc.
The project README shows sample output, options, and design notes.

How to use it: install → list → launch Codex with “experimental resume”​

1) Install (local-use oriented; not on npm)​

git clone https://github.com/shinshin86/codex-history-list.git
cd codex-history-list
npm i
npm run build
# run
node dist/cli.js --help

This tool is meant for local use (not on npm).

2) List your sessions​

# quick look at the latest
node dist/cli.js

# examples
node dist/cli.js --limit 20
node dist/cli.js --since 2025-08-01 --before 2025-09-01
node dist/cli.js --cwd-filter /Users/you/projects/foo
node dist/cli.js --json

• The table has time | cwd | ask | path. cwd/ask are width-trimmed for readability; path is full for easy copy/paste.

3) Launch Codex CLI with the selected log (“experimental resume”)​

Once you’ve found the target row, copy the path and launch Codex like this:

codex -c experimental_resume="/Users/you/.codex/sessions/2025/08/31/rollout-2025-08-31T17-06-00-...jsonl"

• -c key=value is the official way to override config at launch.
• experimental_resume appears in the template as an experimental key. Combine those two and you can start Codex with the previous session’s context loaded.

Note: Installing Codex CLI itself is npm i -g @openai/codex or brew install codex.

Wrap-up: A stopgap until official resume lands​

• Problem: No official resume; continuing past sessions is tedious.
• Premise: Codex stores sessions as JSONL under ~/.codex/sessions.
• Approach: Make saved logs easy to find and launch Codex with an experimental key to pseudo-resume.
• Tool: codex-history-list is mac-first, personal-use OSS. Not on npm / local-use oriented.

When /resume or a session list lands officially, this tool will have served its purpose. For the latest progress, keep an eye on the Codex repo (Issues/Discussions).

References​

• codex-history-list repository (README: features, usage, how to resume)
• OpenAI Codex CLI (official repo / README)
• Config template including the experimental key experimental_resume (Issue)
• Mention of the session save location (~/.codex/sessions) (Discussion)
• /resume feature request (Issue)

Note (author’s intent)
Until official resume ships, the goal is the shortest path: a readable list plus a “launch with log path” recipe. Nothing fancy, but you should be able to reach the right JSONL without getting lost.

Continue reading...

 

Join 𝕋𝕄𝕋 on Telegram
Channel PREVIEW: