Recovering Codex History After Switching Providers with CCSwitch on Mac

Thu, 11 Jun 2026 00:00:00 +0800

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.

Recommended Recovery Workflow on Mac

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.

Connecting Mobile GPT to Mac Codex

Tue, 26 May 2026 10:30:00 +0800

Connecting Mobile GPT to Mac Codex

This note records my own setup process. The goal was to make the GPT app on my phone connect reliably to Codex running on my Mac.

Steps

Enable multi-factor authentication on the phone

Enable multi-factor authentication (MFA) on the mobile side. Otherwise, the phone-side security verification may fail.
In my case, I completed the verification using Apple’s built-in password/authentication capability.

Configure Codex proxy environment variables

Edit ~/.codex/.env and add the following content:

HTTP_PROXY=http://127.0.0.1:6789
HTTPS_PROXY=http://127.0.0.1:6789
ALL_PROXY=http://127.0.0.1:6789
WS_PROXY=http://127.0.0.1:6789
WSS_PROXY=http://127.0.0.1:6789
http_proxy=http://127.0.0.1:6789
https_proxy=http://127.0.0.1:6789
all_proxy=http://127.0.0.1:6789
ws_proxy=http://127.0.0.1:6789
wss_proxy=http://127.0.0.1:6789
NO_PROXY=localhost,127.0.0.1,::1
no_proxy=localhost,127.0.0.1,::1

After saving the configuration, restart Codex.

If you use a local proxy tool, Codex may work normally without changing these environment variables, but the mobile app may still show the device as offline.

Connect the phone and Codex

After restarting Codex, try the connection flow again from the mobile app.
Once the connection succeeds, it should be ready for normal use.

Success Criteria

I mainly used two signals to decide whether the setup was successful:

Mobile GPT and Mac Codex are signed in with the same account and remain stable.
Codex network requests work normally, without proxy or connection errors.

Troubleshooting

If the connection fails, I would check the following items in order:

Confirm that the phone and Mac are using the same account.
Confirm that MFA has been completed and is active.
Check whether ~/.codex/.env was saved successfully and whether the port is correct.
Confirm that the local proxy at 127.0.0.1:6789 is running and that the port matches.
Restart Codex and try again.

Codex on XEDCZQ Blog

Recovering Codex History After Switching Providers with CCSwitch on Mac

Recovering Codex History After Switching Providers with CCSwitch on Mac

Symptoms

Recovery Approach

Install codex-threadripper

Install with Homebrew

Install globally with npm

Recommended Recovery Workflow on Mac

Back Up Local Codex Data

Switch to the Target Provider with CCSwitch

Synchronize Threads

Reload Codex

Inspect Synchronization Status

How to Confirm Recovery

Troubleshooting

codex-threadripper Command Not Found

Old Conversations Are Still Missing

Database Is Locked During Synchronization

History Reappears After Switching Back

Rollback

Security Notes

Summary

Connecting Mobile GPT to Mac Codex

Connecting Mobile GPT to Mac Codex

Steps

Sign in with the same account

Enable multi-factor authentication on the phone

Configure Codex proxy environment variables

Connect the phone and Codex

Success Criteria

Troubleshooting