Separating Codex Sessions, Resume, and Working Directories

When resuming Codex, treating “the terminal is back” as “the conversation and working location are correct” is risky.

A Codex session stores conversation history.

A shell session manages processes, environment variables, and the terminal.

A Git worktree manages file changes and a branch.

The names are similar, but the stored state and recovery operation are different.

Separate the three states first

State	What it mainly stores	How to resume or verify it
Codex session	Conversation, model, and work context	`codex resume` or `/resume`
Shell session	CWD, environment variables, and running processes	tmux or the shell’s mechanism
Git worktree	File diff and branch	The target directory and Git

Restoring a terminal with tmux or ctx does not automatically continue a Codex conversation.

Conversely, resuming a conversation does not guarantee that the correct worktree’s files are selected.

Record important specifications and remaining work in repository documentation or commits, not only in a conversation.

Verify resume behavior in the official CLI

The official Codex CLI command reference documents these forms:

codex resume
codex resume --last
codex resume --all
codex resume SESSION_ID

With no argument, Codex opens a picker for saved sessions.

--last selects the latest session associated with the current working directory.

--all includes sessions from other working directories.

An ID or name resumes a particular session directly.

Inside the TUI, /resume opens the selection flow.

Before running the command, decide whether you want the last terminal state or the last Codex conversation.

Check the CWD when it differs

When the session’s saved CWD differs from the CWD where resume runs, the choice of location matters.

The current CLI customization documentation supports setting tui.resume_cwd to "current" or "session".

When using an explicit --cd, treat the specified directory as the primary location to verify.

Immediately after resuming, check:

Does pwd -P show the expected worktree?
Does git branch --show-current show the expected branch?
Does git status --short contain only expected changes?
Does Codex /status show the expected location and model?

Opening a similarly named worktree can edit the wrong files even when the conversation is correct.

Choose between resume and fork

resume continues the original conversation.

fork copies a previous session so that you can try a different direction.

Use resume for the same implementation.

Use fork to compare a design or repair strategy.

Start a new session for an independent task so that old constraints do not leak into it.

When the conversation and file changes both need a branch, assign a separate worktree as well.

Treat `active writer` wording safely

The public Codex documentation available in August 2026 did not provide an official cause or recovery procedure for wording such as “active writer.”

The following is an inference from exclusive-write controls, not an official Codex specification.

If multiple Codex processes update one session at the same time, one may be rejected to protect the history.

Diagnose it in this order:

Check for another CLI, IDE, or desktop window with the same session open
Wait for one side to finish
Close the unnecessary side through its normal exit operation
Resume again from the original worktree
If contention continues, fork and use a separate session
Send /feedback with the version, session ID, time, and reproduction steps

Do not delete session storage or apparent lock files based on a guess.

That can lose history or create inconsistency with another session.

Record state before and after interruptions

Before an interruption, record changes, remaining work, and verification results in repository documentation or a commit.

Give sessions short names and use one task, one worktree, and one session as the default.

After resuming, verify conversation, location, and state.

Restoring a terminal does not restore a conversation.

Restoring a conversation does not replace checking the correct worktree.