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

#codexcli #codex #chatgpt

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.