How to Resume Sessions in Codex CLI

One of the most powerful features of OpenAI Codex CLI is its ability to preserve and resume conversations. Unlike traditional terminal sessions that lose context when closed, Codex saves your entire conversation history locally, allowing you to pick up exactly where you left off.

Understanding Session Transcripts

Every Codex CLI session is automatically saved as a JSONL (JSON Lines) file. These transcript files contain:

• User messages and assistant responses
• Tool calls and their outputs
• File changes and command executions
• Token usage and timing information
• Plan updates and decision history

Session Storage Location

Sessions are organized by date in your Codex home directory:

Each session file follows the naming pattern: rollout-YYYY-MM-DDTHH-MM-SS-*.jsonl

Resuming Sessions from the Command Line

Quick Resume: Continue Your Last Session

The fastest way to continue your most recent conversation:

codex resume --last

Or use the short flag:

codex resume -l

This immediately reopens your last session without showing the picker interface.

Interactive Session Picker

To browse and select from recent sessions:

codex resume

This launches an interactive picker showing:

• Session timestamps
• Working directory context
• Summary of conversation topics
• Session IDs for reference

Use arrow keys to navigate, and press Enter to select a session.

Resume a Specific Session

If you know the session ID (visible in the picker or session files):

codex resume 7f9f9a2e-1b3c-4c7a-9b0e-example-id

Resume with a Follow-Up Prompt

Continue a session and immediately send a new instruction:

codex resume --last "Fix the race conditions you found earlier"

Or for a specific session:

codex resume 7f9f9a2e-1b3c-4c7a-9b0e-example-id "Implement the plan we discussed"

View All Sessions (Cross-Directory)

By default, the session picker shows sessions from your current working directory. To see all sessions:

codex resume --all

This is useful when you have moved between projects but want to resume work from a different directory.

Using Slash Commands for Session Management

Within an active Codex session, you can use slash commands for session management.

/resume - Switch to a Previous Session

Type /resume and press Enter to open the session picker without exiting Codex. Select any previous session to switch context immediately.

/fork - Branch from a Previous Session

The /fork command creates a new session branched from an existing one:

1. Type /fork and press Enter
2. Select the session you want to branch from
3. Codex creates a new session with a fresh ID
4. The original session remains untouched

This is valuable when you want to explore an alternative approach without losing your original conversation thread.

/status - Check Current Session Info

Type /status to view information about your current session, including:

• Session ID
• Token usage
• Context window utilization
• Working directory

Context Preservation for Long-Running Tasks

Codex CLI can handle tasks that span hours by using context compaction and smart session management.

Using /compact to Manage Context

When your conversation grows long, the /compact command summarizes the history while preserving essential context:

/compact

This command:

1. Summarizes the current conversation
2. Preserves key decisions and context
3. Frees up tokens for new interactions
4. Maintains continuity for ongoing tasks

When to use /compact:

• Context usage reaches 80-85% (check with /status)
• Responses become slower or less coherent
• You are planning an extended coding session

Starting Fresh with /new

When you need a completely fresh start:

/new

This clears the current context and begins a new session. Use this when:

• Switching to an unrelated task
• The current context is no longer relevant
• You want to start with a clean slate

Automatic Compaction in Long Tasks

For extended tasks, Codex automatically handles context limits:

1. The model works on your task
2. When approaching context boundaries, it compacts its state
3. A summary is created for continuity
4. Work resumes with the condensed context

Codex has demonstrated running continuously for up to seven hours on complex tasks using this mechanism.

Non-Interactive Session Resume

For automation and scripting, use the exec subcommand with resume:

Continue Last Session Non-Interactively

codex exec resume --last "Complete the refactoring task"

Resume Specific Session in Scripts

codex exec resume 7f9f9a2e-1b3c-4c7a-9b0e-example-id "Run the test suite"

This is useful for:

• CI/CD pipelines
• Scheduled tasks
• Multi-stage workflows
• Automated code reviews

Advanced: Manual Session Loading

For advanced use cases, you can manually load a specific session file using the experimental resume configuration:

codex -c experimental_resume="~/.codex/sessions/2025/01/22/rollout-2025-01-22T10-30-00-abc123.jsonl"

This allows precise control over which session context to load.

Platform-Specific Notes

macOS

• Sessions sync between Codex CLI and VS Code/Cursor extensions
• Use Homebrew for easy updates: brew upgrade codex
• Terminal.app and iTerm2 both work well

Windows

• WSL is recommended for the best session management experience
• Sessions created in WSL are stored in the WSL filesystem
• Windows native sessions may have path differences
• Use PowerShell for running Codex commands outside WSL

Linux

• Standard session paths apply
• Works consistently across distributions
• Sessions are portable between machines (copy the ~/.codex/sessions directory)

Best Practices for Session Management

1. Use Meaningful Starting Points

Begin sessions with clear context:

codex "We're working on the user authentication module. The goal is to add OAuth2 support."

This creates a better foundation for resuming later.

2. Checkpoint Before Major Changes

Before significant code changes, note the session ID:

/status

Save this ID in case you need to fork or reference the conversation later.

3. Keep Sessions Focused

One project or task per session works better than mixing unrelated work. Use /new when switching contexts.

4. Leverage AGENTS.md for Persistent Context

Create an AGENTS.md file in your project root with persistent instructions:

# Project Context
- This is a Node.js backend service
- We use TypeScript with strict mode
- Tests should use Jest
- Follow the existing code style

Codex automatically loads this file in every session, reducing the need to repeat context.

5. Summarize Before Ending

Before closing a long session, ask Codex to summarize:

Summarize what we accomplished and what remains to be done

This creates a clear record for when you resume.

Troubleshooting

Session Not Appearing in Picker

If a recent session does not appear:

1. Check the session directory manually:

   ls -la ~/.codex/sessions/$(date +%Y/%m/%d)/
   

   Copy

2. Verify Codex has write permissions to ~/.codex

3. Try codex resume --all to see cross-directory sessions

Context Not Restored Properly

If resumed sessions seem to lack context:

1. Verify the session file is not corrupted:

   tail -5 ~/.codex/sessions/2025/01/22/rollout-*.jsonl
   

   Copy

2. The JSONL should contain valid JSON objects

3. Try asking Codex what it remembers from the conversation

Resume Command Not Available

Ensure you have Codex CLI version 0.30.0 or later:

codex --version

Update if needed:

# Homebrew
brew upgrade codex

# npm
npm update -g @openai/codex

Next Steps

• Learn the fundamentals with How to Install OpenAI Codex CLI
• Explore Codex CLI slash commands
• Review the official session documentation
• Compare with Gemini CLI for tasks requiring larger context windows