# Codex CLI 0.145.0 Upgrade and Migration Guide

> Upgrade to Codex CLI 0.145.0, import Cursor or Claude Code setup safely, test MCP and sessions, and separate stable features from experiments.

- **Published**: 2026-07-22
- **Category**: AI Infrastructure
- **URL**: https://agentpedia.codes/blog/codex-cli-0-145-upgrade-migration-guide

---

> **Important callout**

**Bottom line:** Codex CLI 0.145.0 is worth a controlled upgrade if you need its expanded Cursor and Claude Code importer, MCP reliability fixes, or stable-but-opt-in multi-agent V2. Pin version 0.145.0, import one category at a time, and keep project memory and realtime V3 out of a production rollout because the tagged source still marks those paths under development.

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](https://learn.chatgpt.com/docs/changelog), the [0.145.0 GitHub release](https://github.com/openai/codex/releases/tag/rust-v0.145.0), 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](https://learn.chatgpt.com/docs/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.

| Area | What 0.145.0 adds or changes | Adoption consequence |
| --- | --- | --- |
| External-agent import | /import detects Cursor and Claude Code setup, then offers supported configuration, MCP, plugins, sessions, commands, and project data | Treat this as a migration assistant, not a semantic compatibility guarantee |
| Thread history | Paginated resume, search, persisted names, sub-agent history, and memory integration | OpenAI labels the new paginated history experimental |
| MCP | Startup deadlines cover client creation; OAuth discovery no longer blocks startup; refreshes are serialized; eligible stdio tool catalogs can be reused | Re-test every imported server and authentication flow |
| Multi-agent V2 | Configurable sub-agent models, reasoning, concurrency, restored roles, and improved navigation | The implementation is classified stable but remains disabled by default |
| Audio and realtime | Local audio inputs and tool outputs plus streaming realtime V3 plumbing | Audio support and realtime maturity are not the same; realtime remains under development in the tagged registry |
| Bedrock | Login, custom endpoint and authentication support, with GPT-5.6 Sol as the default Bedrock model | The release explicitly labels Bedrock support experimental |
| Terminal and safety | Faster long-session rendering, bounded command output, Windows sandbox fixes, stronger forced-rm detection, and consistent full-access confirmation | Run representative long-session, Windows, and approval checks before broad rollout |

The importer is the biggest workflow change, but several fixes matter even if you never run it. [PR #32781](https://github.com/openai/codex/pull/32781) applies startup_timeout_sec while an MCP client and transport are created, not only after startup. [PR #33184](https://github.com/openai/codex/pull/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](https://github.com/openai/codex/pull/33297).

The release also strengthens approval handling. [PR #33464](https://github.com/openai/codex/pull/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](https://learn.chatgpt.com/docs/feature-maturity) 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.

| Capability | 0.145.0 status | Default | Practical guidance |
| --- | --- | --- | --- |
| Core /import flow for Cursor and Claude Code | Shipped without an experimental label | Available in a local TUI | Pilot with selected items and inspect every Codex-side change |
| Project-scoped external memory import | **Under development** in the [tagged feature registry](https://github.com/openai/codex/blob/rust-v0.145.0/codex-rs/features/src/lib.rs) | Off | Skip in a normal rollout |
| Paginated thread history | **Experimental** in the release notes | Release-dependent experiment | Do not make it the only copy of important session state |
| Amazon Bedrock support | **Experimental** in the release notes | Requires setup | Evaluate with non-production credentials and endpoints |
| Multi-agent V2 | **Stable**, according to [PR #34383](https://github.com/openai/codex/pull/34383) | Off | Enable only after single-agent and permission tests pass |
| Audio inputs and audio tool outputs | Shipped in the release notes | Depends on client and model support | Test the exact format, model, and surface used |
| Streaming realtime V3 | **Under development** in the tagged registry | Off | Keep outside the production acceptance gate |
| Inline visualization links | Shipped in the release notes | Available where emitted | Confirm the target before opening a terminal link |

The table resolves an easy-to-miss contradiction. The changelog says /import includes project-scoped memories, while [PR #33444](https://github.com/openai/codex/pull/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:

~~~toml
[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.

~~~bash
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:

~~~bash
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.

~~~bash
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.

| Category | Baseline evidence | Pass condition |
| --- | --- | --- |
| Version | Existing codex --version output | Installed binary reports 0.145.0 |
| Repository files | Clean test worktree | Only reviewed AGENTS.md, .codex, and .agents changes |
| MCP | Saved codex mcp list output | Same intended servers, successful auth, one harmless tool call each |
| Plugins and marketplaces | Private pre-import list of IDs and sources | Only reviewed additions; no pre-existing item removed |
| User/project skills | Private pre-import directory-name inventory | Every new skill is attributable to a staged import |
| Sessions | Known recent Cursor or Claude Code chat | Imported title, working directory, and context are usable |
| Commands and skills | One low-risk command or skill | Converted item loads and behaves correctly on a disposable fixture |
| Source setup | Existing Cursor or Claude Code files | Source files and source application still work |

## Install the exact 0.145.0 release

OpenAI's changelog gives an exact npm pin:

~~~bash
npm install --global @openai/codex@0.145.0
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:

~~~bash
npx --yes @openai/codex@0.145.0 --version
~~~

The [official CLI guide](https://learn.chatgpt.com/docs/codex/cli) 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](https://github.com/openai/codex/releases/tag/rust-v0.145.0) provides platform archives and checksums.

## What the importer actually moves

The release headline is accurate but compressed. [PR #33426](https://github.com/openai/codex/pull/33426) adds the Cursor adapter, and the [pinned migration model](https://github.com/openai/codex/blob/rust-v0.145.0/codex-rs/external-agent-migration/src/model.rs) enumerates configuration, skills, instructions, plugins, MCP servers, subagents, hooks, commands, memory, and sessions as separate item types.

| Imported material | Claude Code | Cursor | Codex-side behavior in the pinned source |
| --- | --- | --- | --- |
| Settings and sandbox policy | Supported settings from .claude | Supported CLI and sandbox settings from .cursor | Missing TOML values are added to user or project config.toml; existing values win |
| MCP servers | Supported | Supported from Cursor MCP configuration | Only server names absent from Codex are merged; a same-name Codex server is preserved |
| Instructions | User and project CLAUDE.md | Project .cursorrules | Writes AGENTS.md only when the destination is missing or empty |
| Skills | Supported where detected | Supported where detected | Copies missing skill directories into user or project .agents/skills |
| Plugins and marketplaces | Enabled plugins from known marketplaces | Supported where detected | Uses the normal plugin installer; missing packages or authorization can require follow-up |
| Commands | Supported | Supported | Converts command-style Markdown into skills rather than preserving a separate command runtime |
| Subagents and hooks | Supported | Supported | Converts or copies supported definitions; inspect permissions and event semantics afterward |
| Recent sessions | Supported | Supported | Considers files modified in the last 30 days, caps a detection pass at 50, and skips already-recorded imports |
| Project memory | Claude project memory only | Not supported by the pinned adapter | Feature-gated, under development, and off by default |

The merge behavior is deliberately conservative. The [tagged merge implementation](https://github.com/openai/codex/blob/rust-v0.145.0/codex-rs/external-agent-migration/src/config_values.rs) 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](https://github.com/openai/codex/blob/rust-v0.145.0/codex-rs/external-agent-migration/src/detect/sessions/common.rs) 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](https://github.com/openai/codex/pull/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](https://learn.chatgpt.com/docs/import) 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](https://github.com/openai/codex/blob/rust-v0.145.0/codex-rs/tui/src/external_agent_config_migration_flow.rs) explicitly rejects remote sessions and a TUI connected through the local app-server daemon.

From the isolated test worktree:

~~~bash
codex
~~~

Then enter:

~~~text
/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:

~~~bash
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:

~~~bash
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.

| Test | Action | Pass condition | Investigate when |
| --- | --- | --- | --- |
| Binary and config | Run codex --version, launch Codex, then open /status | Version is 0.145.0 and configuration loads without warnings or parse errors | Version path differs, startup fails, or imported TOML is invalid |
| Repository scope | Review git diff for AGENTS.md, .codex, and .agents | Instructions and generated skills are in the intended scope | Root guidance contains project-only rules or files appear outside the test worktree |
| MCP inventory | Run codex mcp list and compare the saved baseline | Intended servers are present once with the expected transport | Same-name server retained an old definition or a server disappeared |
| MCP authentication | Run codex mcp login for OAuth servers, then invoke one harmless read-only tool | Login completes and the tool returns expected data | Startup times out, OAuth repeats, or the live tool differs from its cached catalog |
| Imported skill | Invoke one converted command or skill against a disposable fixture | Arguments, paths, permissions, and output match the original intent | Placeholders remain literal, shell behavior changed, or broader access is requested |
| Imported session | Open /resume and select a known recent session | Title, working directory, attachments, and useful context are present | Session is absent, attached to the wrong directory, or loses essential context |
| Long TUI session | Stream a representative long response and run a bounded command | Rendering remains responsive and command output stays usable | Redraws stall, output truncation hides evidence, or resume state breaks |
| Approval safety | Review permissions and use a harmless command that should meet the configured boundary | The expected prompt and rejection reason remain visible | Full access becomes active unexpectedly or imported settings weaken the boundary |

For MCP, remember that 0.145.0 can present a cached catalog while a replacement stdio process initializes. [PR #33184](https://github.com/openai/codex/pull/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:

~~~toml
[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.

| Surface | Rollback action | Evidence afterward |
| --- | --- | --- |
| CLI binary | Reinstall the recorded previous version through the same package manager | codex --version matches version-before.txt |
| User config.toml | Preserve the failed-test file, then restore the private pre-upgrade copy | codex mcp list matches the intended baseline |
| Repository instructions and config | Discard the dedicated test worktree or reverse only reviewed import changes | Original working tree remains unchanged |
| Skills and commands | Remove only items listed as imported, preferably by discarding the test worktree for project scope | No pre-existing skill directory was removed |
| Plugins | Uninstall only plugin IDs installed by this import and remove new marketplaces only when unused | Plugin inventory matches the saved baseline |
| Sessions | Keep or delete imported Codex copies through the supported session UI | Cursor and Claude Code source sessions remain intact |
| Memory | Skip during the production migration | No under-development memory workspace needs cleanup |

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:

~~~bash
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:

~~~bash
: "${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](https://learn.chatgpt.com/docs/import) 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](/blog/codex-code-review-agents-md-rules) to keep repository instructions scoped, the [secure MCP tunnel guide](/blog/openai-secure-mcp-tunnels-guide) for private servers, and the [Cursor, Kiro, and Codex remote-work comparison](/blog/code-from-your-phone-cursor-kiro-codex) 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.

## FAQ

### Should I upgrade to Codex CLI 0.145.0 immediately?

Upgrade if you need the expanded Cursor or Claude Code importer, MCP startup fixes, long-session rendering improvements, or stable opt-in multi-agent V2. Pin the version and test it first if your workflow depends on imported configuration or authenticated MCP servers.

### Does Codex 0.145.0 delete my Cursor or Claude Code setup?

No. OpenAI's import documentation says the source setup is left unchanged, and the tagged importer adds missing Codex values rather than deleting the external-agent files. The import still writes Codex-side files, so back those up and inspect the result.

### Can Codex CLI 0.145.0 import both Cursor and Claude Code?

Yes. The release changelog and tagged source support both adapters. When both have importable data, the local terminal flow asks which source to import. Run the flow again to process the other source.

### Is project memory import stable in Codex CLI 0.145.0?

No. Although the release headline mentions project-scoped memories, the tagged 0.145.0 feature registry marks external agent memory import as under development and disabled by default. OpenAI's maturity guidance says under-development features are not ready for use.

### Does downgrading Codex undo an import?

No. Reinstalling the earlier binary rolls back the executable, not imported configuration, plugins, skills, or sessions. Use a test worktree, preserve a restricted backup of Codex configuration, import in stages, and reverse each changed artifact separately.


---

[Join the Agentpedia newsletter](https://agentpedia.codes/blog)
[Browse related Agentpedia articles](https://agentpedia.codes/blog)

## Official sources

### Release and source

- [OpenAI Codex changelog entry for 0.145.0](https://learn.chatgpt.com/docs/changelog)
- [Codex CLI 0.145.0 GitHub release](https://github.com/openai/codex/releases/tag/rust-v0.145.0)
- [Full 0.144.0 to 0.145.0 source comparison](https://github.com/openai/codex/compare/rust-v0.144.0...rust-v0.145.0)
- [Source tree pinned to rust-v0.145.0](https://github.com/openai/codex/tree/rust-v0.145.0)

### Import implementation

- [Cursor import support, PR #33426](https://github.com/openai/codex/pull/33426)
- [Plugin command-to-skill migration, PR #33411](https://github.com/openai/codex/pull/33411)
- [Enabled-plugin marketplace import, PR #31672](https://github.com/openai/codex/pull/31672)
- [Feature-gated external memory migration, PR #33444](https://github.com/openai/codex/pull/33444)
- [Pinned migration item model](https://github.com/openai/codex/blob/rust-v0.145.0/codex-rs/external-agent-migration/src/model.rs), [merge behavior](https://github.com/openai/codex/blob/rust-v0.145.0/codex-rs/external-agent-migration/src/config_values.rs), and [session limits](https://github.com/openai/codex/blob/rust-v0.145.0/codex-rs/external-agent-migration/src/detect/sessions/common.rs)

### Current Codex documentation

- [Codex CLI installation and quickstart](https://learn.chatgpt.com/docs/codex/cli)
- [OpenAI feature-maturity definitions](https://learn.chatgpt.com/docs/feature-maturity)
- [Import from another agent](https://learn.chatgpt.com/docs/import)
- [Codex MCP configuration and authentication](https://learn.chatgpt.com/docs/extend/mcp)


---

- [All articles](https://agentpedia.codes/blog)