Codex CLI 0.145.0 Upgrade and Migration Guide

OpenAI released Codex CLI 0.145.0 on July 21, 2026. The headline feature is the /import command: it can bring supported settings, MCP servers, plugins, recent sessions, commands, and other project setup from Cursor or Claude Code into Codex. This guide turns that release list into a reversible migration plan, including the parts the headline does not settle: name collisions, authentication, session limits, feature maturity, smoke tests, and rollback.

The source set is first-party and was reviewed on July 22, 2026: OpenAI's Codex changelog, the 0.145.0 GitHub release, implementation pull requests, current Codex documentation, and source pinned to the rust-v0.145.0 tag. No performance result in this article is an AgentPedia benchmark.

What changed in Codex CLI 0.145.0

The official changelog groups the release into six feature areas and six clusters of fixes. For an upgrade decision, the useful split is between changes received by installing the release and capabilities that still require an explicit opt-in or an experimental tolerance.

The importer is the biggest workflow change, but several fixes matter even if you never run it. PR #32781 applies startup_timeout_sec while an MCP client and transport are created, not only after startup. PR #33184 caches eligible stdio tool catalogs for up to 30 minutes in a bounded process-wide cache while resolving tool calls against the live connection. A server can opt out through the capability introduced in PR #33297.

The release also strengthens approval handling. PR #33464 expands forced-rm detection across wrappers, pipelines, substitutions, traps, and option variants. That is a safety heuristic improvement, not permission to weaken sandbox or approval settings.

Separate shipped features from experiments

OpenAI's feature-maturity reference defines under development as not ready for use, experimental as unstable and subject to removal, and stable as supported for broad use. The release notes and tagged feature registry do not assign the same maturity to every headline.

The table resolves an easy-to-miss contradiction. The changelog says /import includes project-scoped memories, while PR #33444 calls memory migration feature-gated and the pinned registry sets external_agent_memory_import to under development and disabled. The safe interpretation is that the implementation exists in 0.145.0, but it is not ready for an ordinary migration.

Multi-agent V2 is the opposite case. Its source classification is stable, yet it is still opt-in:

[features]
multi_agent_v2 = true

Stable does not mean automatically enabled. Introduce it after the upgrade and import are proven, so a failed acceptance test has one likely cause instead of three.

Prepare a reversible upgrade

Start with an inventory and an isolated repository checkout. Do not test an importer against an unrelated dirty worktree.

codex --version
command -v codex
codex mcp list
git status --short

If the repository is clean, create a dedicated worktree from the commit you intend to test:

git worktree add ../codex-0145-import-test -b codex-0145-import-test
cd ../codex-0145-import-test

Next, preserve the Codex configuration you may need to restore. The directory below is private to your user because of umask 077. Treat the copy as a secret because config.toml can contain MCP headers, environment values, or other credentials.

CODEX_0145_BACKUP_DIR="$HOME/.local/state/codex-backups/0.145.0-$(date +%Y%m%d-%H%M%S)"
umask 077
mkdir -p "$CODEX_0145_BACKUP_DIR"

codex --version > "$CODEX_0145_BACKUP_DIR/version-before.txt"
codex mcp list > "$CODEX_0145_BACKUP_DIR/mcp-before.txt"

if [ -f "$HOME/.codex/config.toml" ]; then
  cp -p "$HOME/.codex/config.toml" "$CODEX_0145_BACKUP_DIR/config.toml"
fi

printf '%s\n' "$CODEX_0145_BACKUP_DIR"

Keep the printed backup path in the change record. Do not paste the configuration into an issue, chat, or pull request. This backup covers configuration rollback; it is not a full snapshot of imported sessions or installed plugins.

Before running /import, also record the current plugin IDs and marketplace sources, plus the names of user- and project-scoped skills. After each staged import, append the items Codex reports as added, skipped, or preserved. Use supported inventory commands where your installed version provides them; otherwise keep a private, redacted checklist. Without that inventory, plugin and skill rollback is guesswork.

Install the exact 0.145.0 release

OpenAI's changelog gives an exact npm pin:

npm install --global @openai/[email protected]
codex --version

Confirm the version output contains 0.145.0 before running the importer. If command -v codex points to a different package-manager installation, resolve that path conflict first; otherwise the install command and the binary under test may not be the same artifact.

For a first look that avoids replacing the global installation, npm can run the pinned package directly. This still downloads and executes the package and can populate npm's cache:

npx --yes @openai/[email protected] --version

The official CLI guide also documents the standalone installer, Homebrew, and release archives. Those channels are useful for normal updates, but an evaluation should record the exact artifact. The GitHub release provides platform archives and checksums.

What the importer actually moves

The release headline is accurate but compressed. PR #33426 adds the Cursor adapter, and the pinned migration model enumerates configuration, skills, instructions, plugins, MCP servers, subagents, hooks, commands, memory, and sessions as separate item types.

The merge behavior is deliberately conservative. The tagged merge implementation inserts missing configuration fields recursively and adds an MCP server only when its name is absent. It does not overwrite an existing same-name server with imported transport, environment, or authentication data.

That prevents a blind overwrite, but creates a review obligation. A name collision can leave the existing Codex server active while the operator assumes the external definition replaced it. Compare configuration, transport, command, arguments, working directory, environment, headers, and auth for every collision.

Session import is bounded too. The tagged detector considers at most 50 sessions changed within 30 days per detection pass. Claude Code sessions whose working directory no longer exists are skipped; Cursor can use migration fallback metadata. “Recent sessions” does not mean a complete historical archive.

Commands need their own review. PR #33411 converts supported plugin commands into skills, prefers a native skill on a name collision, and skips unsupported templates, missing descriptions, collisions, or generated skills above its size limit without blocking the entire plugin installation. OpenAI's broader import guidance also tells users to inspect command arguments, shell interpolation, path placeholders, tool restrictions, hooks, and MCP authentication after import.

Run the import in controlled stages

The terminal importer must run locally. The tagged flow explicitly rejects remote sessions and a TUI connected through the local app-server daemon.

From the isolated test worktree:

codex

Then enter:

/import

If both Cursor and Claude Code contain importable data, choose one source. Run /import again later for the other source. The picker begins with detected items selected, so review the list and deselect anything outside the current stage.

1. Settings and instructions. Import the smallest configuration surface first. Exit Codex, inspect the generated files, and resolve duplicate or inaccurate guidance.
2. MCP servers. Import server definitions separately. Compare names and transports, then reauthenticate before invoking a tool.
3. Skills, commands, hooks, subagents, and plugins. Inspect each artifact for executable commands, permission assumptions, placeholders, and missing dependencies.
4. Recent sessions. Import only after project paths and configuration are stable. Resume one known session before accepting the batch.
5. Memory. Leave it unselected in a production migration. Its 0.145.0 implementation is under development.

After each repository-scoped stage:

git status --short
git diff -- AGENTS.md .codex .agents
git ls-files --others --exclude-standard -- AGENTS.md .codex .agents

git diff does not show untracked importer outputs. Open and review every path printed with ?? by git status or by the git ls-files --others command before accepting the stage.

For user-level configuration, compare the private backup locally:

if [ -f "$CODEX_0145_BACKUP_DIR/config.toml" ]; then
  diff -u "$CODEX_0145_BACKUP_DIR/config.toml" "$HOME/.codex/config.toml" || true
fi

Do not paste that diff into a public review until secrets and environment values have been removed. A safer change record lists server names and reviewed outcomes without copying credential-bearing fields.

Run the upgrade smoke tests

Run the acceptance gate with experimental and under-development features disabled. Add multi-agent V2 only after the base gate passes.

For MCP, remember that 0.145.0 can present a cached catalog while a replacement stdio process initializes. PR #33184 says calls are still resolved against the live connection and HTTP servers are not included in this cache. Test an actual harmless call; seeing a tool name is not enough.

After the base gate passes, enable multi-agent V2 in the test configuration and repeat permission, navigation, concurrency, and shutdown checks:

[features]
multi_agent_v2 = true

Use a bounded task with two sub-agents, confirm their selected models and reasoning levels, inspect concurrent edits, and verify that stopping the parent does not leave unexpected work running. The feature is stable in 0.145.0, but concurrency still changes operational risk.

Roll back by artifact, not only by version

There is no published one-command undo for /import. Downgrading the package changes the executable; it does not reverse files, plugin installations, or imported sessions. Roll back each surface deliberately.

For an npm installation, read the exact prior version from the saved baseline instead of assuming it was 0.144.0. Re-enter the absolute backup path from the change record when opening a new shell:

CODEX_0145_BACKUP_DIR="/absolute/path/recorded-during-preparation"
: "${CODEX_0145_BACKUP_DIR:?Set the recorded backup directory}"
test -f "$CODEX_0145_BACKUP_DIR/version-before.txt"

PREVIOUS_CODEX_VERSION=$(sed -nE 's/.* ([0-9]+\.[0-9]+\.[0-9]+)$/\1/p' "$CODEX_0145_BACKUP_DIR/version-before.txt")
: "${PREVIOUS_CODEX_VERSION:?Could not read the previous Codex version}"

npm install --global "@openai/codex@${PREVIOUS_CODEX_VERSION}"
codex --version

Restore user configuration only after saving the failed-test state for diagnosis:

: "${CODEX_0145_BACKUP_DIR:?Set the recorded backup directory}"
test -f "$CODEX_0145_BACKUP_DIR/config.toml"
test -f "$HOME/.codex/config.toml"

cp -p "$HOME/.codex/config.toml" "$CODEX_0145_BACKUP_DIR/config-after-failed-test.toml"
cp -p "$CODEX_0145_BACKUP_DIR/config.toml" "$HOME/.codex/config.toml"
codex mcp list

If no config.toml existed before the test, do not use the second copy command; review the new file and remove or archive only imported entries. Do not use a broad Git reset in a repository containing unrelated work.

OpenAI's general import documentation says the external setup is not changed or deleted. The tagged importer also merges missing Codex values rather than overwriting same-name settings. Those safeguards protect the source, not every Codex-side target. The backup, worktree, and result inventory are what make rollback auditable.

Limits and unresolved gaps

The release does not make migration lossless.

• Authentication is not configuration parity. Imported MCP definitions can still require OAuth, headers, environment variables, or a new login. Plugins and marketplaces can also need manual setup.
• Same-name entries are intentionally preserved. Existing Codex configuration wins. A collision can retain an outdated transport or permission model.
• Session import is partial. The pinned detector uses a 30-day window and a 50-session cap, and Claude sessions require an existing project directory.
• Converted commands are not the old command runtime. They become skills, and unsupported templates or collisions can be skipped.
• Source terminology can be rewritten, but semantics still need review. A migrated hook, subagent, sandbox rule, or instruction can behave differently under Codex.
• The maturity labels are mixed. Multi-agent V2 is stable but opt-in; paginated history and Bedrock are experimental; external memory import and realtime V3 remain under development in the tag.
• No public migration completeness benchmark is attached to the release. The implementation has tests, but OpenAI does not publish a percentage of real Cursor or Claude Code setups that migrate without follow-up.

The acceptance standard is behavioral: the imported Codex environment should load, preserve intended permissions, connect to the correct MCP servers, resume the sessions you care about, and pass a representative task in an isolated checkout.

For adjacent setup work, use the AgentPedia AGENTS.md review guide to keep repository instructions scoped, the secure MCP tunnel guide for private servers, and the Cursor, Kiro, and Codex remote-work comparison when choosing where an agent should run.

Upgrade or wait

Upgrade with a pinned pilot if you need Cursor import, richer Claude Code migration, MCP startup improvements, better long-session rendering, or multi-agent V2. Use the staged flow and keep the source tools installed until the Codex environment passes.

Upgrade without importing if the reliability and terminal fixes matter but your current setup is already curated. Installing 0.145.0 does not require running /import.

Wait if you need project-memory migration to be supported, depend on realtime V3, cannot reauthenticate MCP servers, or lack a safe test worktree and configuration backup. The release contains those implementations, but its own maturity signals do not support treating every headline as production-ready.

Official sources

Release and source

• OpenAI Codex changelog entry for 0.145.0
• Codex CLI 0.145.0 GitHub release
• Full 0.144.0 to 0.145.0 source comparison
• Source tree pinned to rust-v0.145.0

Import implementation

• Cursor import support, PR #33426
• Plugin command-to-skill migration, PR #33411
• Enabled-plugin marketplace import, PR #31672
• Feature-gated external memory migration, PR #33444
• Pinned migration item model, merge behavior, and session limits

Current Codex documentation

• Codex CLI installation and quickstart
• OpenAI feature-maturity definitions
• Import from another agent
• Codex MCP configuration and authentication