CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-openai--codex

OpenAI Codex CLI is a lightweight coding agent that runs locally, providing multimodal inputs, rich approvals workflow, and terminal-based AI-assisted development

Overview
Eval results
Files

session-management.mddocs/

Session Management

Session management allows you to resume previous interactive Codex sessions, maintaining conversation history and context across multiple CLI invocations.

Resume Command

codex resume [OPTIONS] [SESSION_ID]

Arguments

[SESSION_ID]    # UUID of specific session to resume (optional)

Options

--last                                       # Continue the most recent session without picker
-m, --model <MODEL>                          # Override model for resumed session
--oss                                        # Use open source models
-p, --profile <PROFILE>                      # Use specific config profile
-c, --config <KEY=VALUE>                    # Runtime configuration overrides
-s, --sandbox <MODE>                         # Override sandbox mode
-a, --ask-for-approval <POLICY>              # Override approval policy
--full-auto                                 # Enable full automation mode
--dangerously-bypass-approvals-and-sandbox  # Bypass safety controls (dangerous)
-C, --cd <DIRECTORY>                         # Override working directory
--search                                    # Enable web search
-i, --image <FILE>                           # Include additional images (comma-separated)
[PROMPT]                                     # Additional prompt text (positional argument)

Resume Modes

Interactive Picker (Default)

# Show picker to select from available sessions
codex resume

When no session ID is specified and --last is not used, Codex displays an interactive picker showing:

  • Session IDs
  • Creation timestamps
  • Last activity times
  • Brief context or first message

Resume Latest Session

# Resume the most recently active session
codex resume --last

Resume Specific Session

# Resume a specific session by UUID
codex resume 550e8400-e29b-41d4-a716-446655440000

Examples

Basic Resume Operations

# Show session picker
codex resume

# Resume latest session
codex resume --last

# Resume specific session
codex resume 550e8400-e29b-41d4-a716-446655440000

Resume with Configuration Overrides

# Resume with different model
codex resume --last -m gpt-4

# Resume with full automation enabled
codex resume --last --full-auto

# Resume with different sandbox mode
codex resume 550e8400-e29b-41d4-a716-446655440000 -s workspace-write

# Resume with additional configuration
codex resume --last -c approval_policy=never -c max_tokens=4000

Resume with Context Updates

# Resume with additional images
codex resume --last -i "new-screenshot.png,updated-diagram.svg"

# Resume in different working directory
codex resume --last -C /different/project/path

# Resume with additional prompt
codex resume --last -p "Continue working on the authentication feature"

# Resume with web search enabled
codex resume --last --search

Advanced Resume Scenarios

# Resume with multiple overrides
codex resume --last \
  -m gpt-4 \
  -s workspace-write \
  --full-auto \
  -C /path/to/project \
  -i "updated-requirements.png" \
  -p "Apply the new requirements shown in the image"

# Resume using configuration profile
codex resume -p production --last

# Resume with complete configuration override
codex resume 550e8400-e29b-41d4-a716-446655440000 \
  -p team \
  -c model=gpt-4 \
  -c sandbox_mode=workspace-write \
  -c approval_policy=on-request

Session Storage

Location

Sessions are stored in:

~/.codex/sessions/
├── 550e8400-e29b-41d4-a716-446655440000/
├── 6ba7b810-9dad-11d1-80b4-00c04fd430c8/
└── ...

Persistence

Each session directory contains:

  • Conversation history
  • Configuration snapshots
  • File attachments and images
  • Context and metadata

Session Lifecycle

Creation

Sessions are automatically created when starting interactive mode:

codex  # Creates new session with UUID

Resumption

Sessions can be resumed multiple times:

  • Configuration can be overridden per resumption
  • New images and prompts can be added
  • Original context is preserved

Cleanup

Sessions persist until manually cleaned up:

# Manual cleanup (example)
rm -rf ~/.codex/sessions/old-session-uuid

Configuration Override Behavior

When resuming sessions, configuration precedence is:

  1. Resume-specific flags: Highest precedence
  2. Root-level flags: Medium precedence
  3. Original session config: Lowest precedence
# Example: This command overrides the original session's model and sandbox
codex resume --last -m gpt-4 -s workspace-write

Integration Patterns

Workflow Continuation

#!/bin/bash
# Continue work from yesterday
codex resume --last -p "Continue where we left off yesterday"

Context Switching

# Resume specific project session
codex resume $(cat .codex-session-id) -C $(pwd)

Automated Resume

# Resume with predefined settings
alias codex-dev='codex resume --last -m gpt-4 --full-auto -s workspace-write'

Best Practices

  1. Use meaningful prompts: Add context when resuming sessions
  2. Override configuration appropriately: Adjust settings based on current needs
  3. Manage session lifecycle: Clean up old sessions periodically
  4. Document session purposes: Use initial prompts to establish session context
  5. Leverage session IDs: Save important session IDs for future reference

Troubleshooting

Session Not Found

# If specific session UUID doesn't exist
codex resume nonexistent-uuid
# Error: No session found with ID: nonexistent-uuid

No Sessions Available

# If no sessions exist yet
codex resume
# Shows: No previous sessions found. Starting new session.

Configuration Conflicts

Resume-time configuration always takes precedence over stored session configuration, allowing you to adapt sessions to current needs.

Install with Tessl CLI

npx tessl i tessl/npm-openai--codex

docs

authentication.md

development-utilities.md

execution-mode.md

index.md

interactive-mode.md

mcp-management.md

protocol-mode.md

session-management.md

tile.json