0
# Session Management
1

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

4
## Resume Command
5

6
```bash { .api }
7
codex resume [OPTIONS] [SESSION_ID]
8
```
9

10
## Arguments
11

12
```bash { .api }
13
[SESSION_ID]    # UUID of specific session to resume (optional)
14
```
15

16
## Options
17

18
```bash { .api }
19
--last                                       # Continue the most recent session without picker
20
-m, --model <MODEL>                          # Override model for resumed session
21
--oss                                        # Use open source models
22
-p, --profile <PROFILE>                      # Use specific config profile
23
-c, --config <KEY=VALUE>                    # Runtime configuration overrides
24
-s, --sandbox <MODE>                         # Override sandbox mode
25
-a, --ask-for-approval <POLICY>              # Override approval policy
26
--full-auto                                 # Enable full automation mode
27
--dangerously-bypass-approvals-and-sandbox  # Bypass safety controls (dangerous)
28
-C, --cd <DIRECTORY>                         # Override working directory
29
--search                                    # Enable web search
30
-i, --image <FILE>                           # Include additional images (comma-separated)
31
[PROMPT]                                     # Additional prompt text (positional argument)
32
```
33

34
## Resume Modes
35

36
### Interactive Picker (Default)
37

38
```bash
39
# Show picker to select from available sessions
40
codex resume
41
```
42

43
When no session ID is specified and `--last` is not used, Codex displays an interactive picker showing:
44
- Session IDs
45
- Creation timestamps
46
- Last activity times
47
- Brief context or first message
48

49
### Resume Latest Session
50

51
```bash
52
# Resume the most recently active session
53
codex resume --last
54
```
55

56
### Resume Specific Session
57

58
```bash
59
# Resume a specific session by UUID
60
codex resume 550e8400-e29b-41d4-a716-446655440000
61
```
62

63
## Examples
64

65
### Basic Resume Operations
66

67
```bash
68
# Show session picker
69
codex resume
70

71
# Resume latest session
72
codex resume --last
73

74
# Resume specific session
75
codex resume 550e8400-e29b-41d4-a716-446655440000
76
```
77

78
### Resume with Configuration Overrides
79

80
```bash
81
# Resume with different model
82
codex resume --last -m gpt-4
83

84
# Resume with full automation enabled
85
codex resume --last --full-auto
86

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

90
# Resume with additional configuration
91
codex resume --last -c approval_policy=never -c max_tokens=4000
92
```
93

94
### Resume with Context Updates
95

96
```bash
97
# Resume with additional images
98
codex resume --last -i "new-screenshot.png,updated-diagram.svg"
99

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

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

106
# Resume with web search enabled
107
codex resume --last --search
108
```
109

110
### Advanced Resume Scenarios
111

112
```bash
113
# Resume with multiple overrides
114
codex resume --last \
115
  -m gpt-4 \
116
  -s workspace-write \
117
  --full-auto \
118
  -C /path/to/project \
119
  -i "updated-requirements.png" \
120
  -p "Apply the new requirements shown in the image"
121

122
# Resume using configuration profile
123
codex resume -p production --last
124

125
# Resume with complete configuration override
126
codex resume 550e8400-e29b-41d4-a716-446655440000 \
127
  -p team \
128
  -c model=gpt-4 \
129
  -c sandbox_mode=workspace-write \
130
  -c approval_policy=on-request
131
```
132

133
## Session Storage
134

135
### Location
136

137
Sessions are stored in:
138
```
139
~/.codex/sessions/
140
├── 550e8400-e29b-41d4-a716-446655440000/
141
├── 6ba7b810-9dad-11d1-80b4-00c04fd430c8/
142
└── ...
143
```
144

145
### Persistence
146

147
Each session directory contains:
148
- Conversation history
149
- Configuration snapshots
150
- File attachments and images
151
- Context and metadata
152

153
## Session Lifecycle
154

155
### Creation
156

157
Sessions are automatically created when starting interactive mode:
158
```bash
159
codex  # Creates new session with UUID
160
```
161

162
### Resumption
163

164
Sessions can be resumed multiple times:
165
- Configuration can be overridden per resumption
166
- New images and prompts can be added
167
- Original context is preserved
168

169
### Cleanup
170

171
Sessions persist until manually cleaned up:
172
```bash
173
# Manual cleanup (example)
174
rm -rf ~/.codex/sessions/old-session-uuid
175
```
176

177
## Configuration Override Behavior
178

179
When resuming sessions, configuration precedence is:
180

181
1. **Resume-specific flags**: Highest precedence
182
2. **Root-level flags**: Medium precedence
183
3. **Original session config**: Lowest precedence
184

185
```bash
186
# Example: This command overrides the original session's model and sandbox
187
codex resume --last -m gpt-4 -s workspace-write
188
```
189

190
## Integration Patterns
191

192
### Workflow Continuation
193

194
```bash
195
#!/bin/bash
196
# Continue work from yesterday
197
codex resume --last -p "Continue where we left off yesterday"
198
```
199

200
### Context Switching
201

202
```bash
203
# Resume specific project session
204
codex resume $(cat .codex-session-id) -C $(pwd)
205
```
206

207
### Automated Resume
208

209
```bash
210
# Resume with predefined settings
211
alias codex-dev='codex resume --last -m gpt-4 --full-auto -s workspace-write'
212
```
213

214
## Best Practices
215

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

222
## Troubleshooting
223

224
### Session Not Found
225

226
```bash
227
# If specific session UUID doesn't exist
228
codex resume nonexistent-uuid
229
# Error: No session found with ID: nonexistent-uuid
230
```
231

232
### No Sessions Available
233

234
```bash
235
# If no sessions exist yet
236
codex resume
237
# Shows: No previous sessions found. Starting new session.
238
```
239

240
### Configuration Conflicts
241

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