Tutorial

Recovering Codex History After Switching Providers with CCSwitch on Mac

How to recover locally stored Codex conversations that become hidden after switching a relay endpoint or model provider with CCSwitch

中文

Recovering Codex History After Switching Providers with CCSwitch on Mac

This note explains how to troubleshoot and recover Codex conversations that suddenly disappear after using CCSwitch to change a relay endpoint or model provider on macOS.

The short version is: the history files are usually still stored on the Mac, but the newly selected Provider environment may not directly expose threads created under the previous Provider.

This guide uses the third-party command-line tool codex-threadripper to rescan and synchronize local threads. It is not an official OpenAI tool. Verify its source and make a complete backup of ~/.codex before installing or running it.

Symptoms

After changing the Codex relay endpoint, model_provider, or base_url with CCSwitch, you may observe that:

  • Codex starts and answers normally.
  • New conversations are saved correctly.
  • Conversations created before the switch are no longer visible.
  • The ~/.codex directory still exists and its disk usage has not dropped significantly.

This does not necessarily mean that the history was deleted. Local thread data may contain Provider, model-source, or environment metadata. After configuration changes, the new environment may expose a different set of threads.

Recovery Approach

The complete workflow is:

Back up ~/.codex
    -> Switch to the target relay with CCSwitch
    -> Confirm that Codex works normally
    -> Scan and synchronize threads with codex-threadripper
    -> Reopen Codex
    -> Verify history and tool status

Do not modify or delete the local Codex database without a backup. If the original history files still exist, recovery is usually possible. Once the source data is overwritten, recovery becomes much harder.

Install codex-threadripper

codex-threadripper is a third-party command-line tool for scanning and processing local Codex history threads. Depending on your package manager, install it through Homebrew or npm.

Install with Homebrew

brew tap wangnov/tap
brew install codex-threadripper

Install globally with npm

npm i -g codex-threadripper

Check that the command is available:

codex-threadripper --help

If Homebrew or npm cannot find the package, the tool may no longer be available from that source, or its repository and package names may have changed. Do not download an unverified binary. Confirm the project repository and release page first.

Back Up Local Codex Data

Quit all running Codex instances, then create a timestamped backup:

cp -R ~/.codex ~/.codex_backup_$(date +%Y%m%d_%H%M%S)

Confirm that the backup exists:

ls -ld ~/.codex_backup_*

The backup may contain account state, configuration, and private conversation history. Do not upload it to a public cloud drive or repository, or share it with an untrusted party.

Switch to the Target Provider with CCSwitch

Use CCSwitch to select the relay endpoint or model provider you want to use. Reopen Codex and confirm that:

  • Codex starts normally.
  • Authentication with the current Provider succeeds.
  • A test message receives a response.

Make sure the new environment works before synchronizing history. Otherwise, Provider configuration failures and history-index problems become difficult to distinguish.

Synchronize Threads

Run the following command in Terminal:

codex-threadripper sync

If the tool does not automatically detect the Codex data directory, specify it explicitly:

codex-threadripper --codex-home "$HOME/.codex" sync

On macOS, $HOME/.codex resolves to:

/Users/your-username/.codex

Do not run multiple Codex instances during synchronization, and do not delete databases or thread files from ~/.codex while the command is running.

Reload Codex

After synchronization finishes, fully quit and reopen Codex. Use the history, session-resume, thread-list, or search entry provided by your installed version.

History commands and UI entry points can change between Codex versions. If a parameter or interactive command is unavailable, inspect the commands supported by your current installation:

codex --help

Treat the actual options shown by the installed client as the source of truth.

Inspect Synchronization Status

Use the third-party tool to inspect current thread status:

codex-threadripper status

If supported by that version, the output groups threads by sources such as custom and openai, helping confirm whether old records were scanned and merged.

How to Confirm Recovery

Check the following:

  • Threads created before the Provider switch appear in Codex again.
  • User messages and Codex responses remain in the correct order when an old thread is opened.
  • New conversations can still be created and saved under the new Provider.
  • codex-threadripper status detects the expected threads.
  • Recovered threads remain visible after restarting Codex.

Troubleshooting

codex-threadripper Command Not Found

Check the executable path and help output:

which codex-threadripper
codex-threadripper --help

For an npm installation, also confirm that the global npm executable directory is included in PATH.

Old Conversations Are Still Missing

Check these items in order:

  • Confirm that synchronization used the actual Codex directory, normally ~/.codex.
  • Confirm that you switched to the target Provider before running synchronization.
  • Fully quit and restart Codex instead of only closing a window.
  • Use status to check whether the tool detected old threads.
  • Check whether the old data is stored under another CODEX_HOME or backup directory.
  • Review command output for database-lock, permission, or incompatible-format errors.

Database Is Locked During Synchronization

Quit Codex and any other processes that may access ~/.codex, then retry. Do not force-copy or modify an index while the database is being written.

History Reappears After Switching Back

This usually indicates that the original data was never lost. The visible thread set or index differs between Provider environments. Back up the data before deciding whether synchronization is necessary, rather than deleting the old configuration.

Rollback

If synchronization causes problems, quit Codex first. Preserve the current directory for diagnosis, then restore the backup as ~/.codex.

Confirm the actual backup directory name before restoring. The commands below are only an example:

mv ~/.codex ~/.codex_after_sync
cp -R ~/.codex_backup_20260611_120000 ~/.codex

Replace the example timestamp with the backup directory you actually created.

Security Notes

  • ~/.codex may contain login state, Provider configuration, API Key references, and conversation content.
  • Never commit the complete directory to Git.
  • Do not send database files to strangers for troubleshooting.
  • Inspect the source, installation scripts, and release files of third-party thread tools.
  • Keep an untouched backup before every synchronization attempt.

Summary

When Codex history disappears after switching relay endpoints with CCSwitch, it does not necessarily mean the local data was deleted. More often, the new Provider configuration does not read the old threads. The safest order is: back up first, switch and validate the Provider, then synchronize threads and verify the result.

codex-threadripper can be used as a third-party recovery method, but its package source and command behavior may change. Always verify the installed version with --help before allowing it to write to ~/.codex.