Migrating Codex History and Projects Between Windows User Profiles

[Muhengi]

Hi,

I wanted to share, in the form of a practical guide, my own experience of moving the ChatGPT/Codex application environment completely from one Windows user profile to another on the same computer, with the help of AI during the process.

I went through the migration, troubleshooting, data recovery, Project migration, archived conversation handling, and history visibility problems myself. I hope this guide will be useful to others who are facing a similar situation and want to avoid unnecessary trial and error.

Purpose

This guide describes how to migrate a local Codex Desktop environment from one Windows user profile to another on the same PC while preserving:

• existing Codex conversation history
• archived conversations
• Codex Projects
• Project-to-thread associations
• workspace/project roots
• local session indexes and application state

Example profiles used throughout this guide:

Old Windows profile: User1
New Windows profile: User2

The procedure is intentionally written so that it can also be given to an AI assistant and used as a technical specification for generating the required PowerShell commands and migration scripts.

---

1. Validated environment

The migration/recovery work described here was performed using:

Codex CLI: 0.153.0
Older rollout/session metadata encountered: 0.146.0-alpha.3.1

The exact Codex Desktop application build was not recorded during the migration, so no specific Desktop version is claimed here.

Codex continues to evolve, so internal storage structures and migration behavior may change between releases.

Current Codex GitHub issues also document different Windows problems involving Project-to-thread associations, archived sessions, and history visibility. See the references at the end of this guide.

---

2. The key concept: Codex history is local

A Windows profile migration should not be treated as a normal account-login migration.

Codex keeps important local session data under the user's .codex directory.

For example:

C:\Users\User1\.codex

and after migration:

C:\Users\User2\.codex

An important distinction is:

Conversation data
    sessions/
    archived_sessions/
    session_index.jsonl

Application and Project state
    state_5.sqlite
    thread_history_1.sqlite
    .codex-global-state.json

The rollout JSONL files are especially important because they contain the underlying session history.

This means:

Not visible in the UI

does not automatically mean:

The conversation data is gone

Windows migration problems have been reported where local rollout/session data and thread records remained available while Project associations or UI visibility were lost. See openai/codex #36663.

---

3. Preserve the old profile

The first rule of the migration is:

Do not delete or modify the old profile during the migration.

The model should be:

User1
  |
  | original source
  |
  +----------------------+
                         |
                         v
                    User2
                 migrated copy

Keep the original:

C:\Users\User1\.codex

available until the new profile has been fully verified.

---

4. Prepare a fresh authenticated User2 profile

Under User2:

1. Start Codex once.
2. Sign in normally.
3. Allow Codex to create the new .codex directory.
4. Close Codex completely before copying historical data.

The new profile's authentication state should remain the authoritative authentication state.

Do not blindly replace:

auth.json

with the old user's authentication file.

The goal is:

Old profile:
    history + session/project data

New profile:
    authentication

---

5. Back up the new User2 Codex directory

Before changing anything under:

C:\Users\User2\.codex

create a complete backup.

For example:

C:\Users\User2\.codex.backup-YYYYMMDD-HHMMSS

Keep this backup until the migration has been completely verified.

---

6. Copy the actual session history

The first migration layer is the actual conversation/session data.

Copy:

C:\Users\User1\.codex\sessions

to:

C:\Users\User2\.codex\sessions

Also copy:

C:\Users\User1\.codex\archived_sessions

to:

C:\Users\User2\.codex\archived_sessions

Preserve the directory structure and file names.

Do not rename individual rollout files.

Do not rewrite the historical rollout JSONL just to update Windows usernames or paths.

Treat the rollout as historical source data.

---

7. Copy the session index

Copy:

C:\Users\User1\.codex\session_index.jsonl

to:

C:\Users\User2\.codex\session_index.jsonl

The session index contains discovery/index information such as session IDs, names and timestamps.

A useful mental model is:

Rollout JSONL
    = underlying conversation/session data

session_index.jsonl
    = discovery/index information

The index and the SQLite state can become inconsistent after migration, so a conversation may still physically exist even when the UI does not display it correctly.

---

8. Projects are a separate migration layer

Copying:

sessions/
archived_sessions/
session_index.jsonl

does not guarantee that Codex Projects will be reconstructed correctly.

Projects and threads are represented separately in application state.

The relevant concepts include:

projects
project_roots
threads
thread.project_id
project ordering
thread-project assignments
workspace roots
migration state

The important relationship is:

Project
   |
   +---- Project root
   |
   +---- Thread A
   +---- Thread B
   +---- Thread C

A migration can therefore preserve every conversation while still leaving Projects empty or leaving conversations unassigned.

This exact class of problem has been reported in openai/codex #36663, where local thread/session data survived but Project-to-thread associations were lost. A similar case is described in #42867, where Project and Thread records remained but thread Project assignments disappeared.

---

9. Project migration should use IDs, not names

Do not assume that this is sufficient:

Project name = "Project A"

The migration should preserve the actual Project relationships.

Conceptually:

Old Project ID
       |
       v
New Project ID
       |
       +---- Thread 1
       +---- Thread 2
       +---- Thread 3

Where necessary, maintain mappings such as:

old legacy project ID
        ->
new/app-server project ID

and:

thread ID
        ->
new project ID

Do not infer Project membership from thread titles.

Do not infer Project membership from the current working directory alone if a reliable historical Project-to-thread assignment exists.

---

10. Remap workspace roots to the new Windows profile

A Windows username change normally changes paths such as:

C:\Users\User1\Documents\ProjectA

into:

C:\Users\User2\Documents\ProjectA

The migration process should therefore distinguish:

Historical conversation content

from:

Current workspace root

For example:

Old Project root:
C:\Users\User1\OneDrive\Documents\Project

New Project root:
C:\Users\User2\OneDrive\Documents\Project

Do not modify historical rollout data merely to change the path.

Update the Project/workspace configuration instead.

---

11. Handle global Project state separately

Codex global state can also contain Project and thread relationship information.

Conceptually, the migration may need to preserve:

local-projects
project-order
selected-project
thread-project-assignments
workspace roots
legacy Project -> app-server Project mapping
migration state

Do not copy this information blindly if it contains paths belonging to User1.

The correct approach is:

preserve Project identity
        +
remap Project root
        +
preserve thread assignment
        +
replace old Windows paths

The importance of this distinction is also demonstrated by #36663 and #42867, where Project migration state and thread assignments became inconsistent.

---

12. Archived conversations are not deleted conversations

Do not assume:

Not visible in sidebar
=
Deleted

Archived sessions can remain under:

C:\Users\User2\.codex\archived_sessions

Current Codex Desktop versions also provide an Archived Chats area and an Unarchive action.

When possible, use:

Settings
    ->
Archived chats
    ->
Unarchive

instead of manually editing the database.

However, archive behavior has also had Windows-specific regressions. For example, #39150 documents an archive failure involving Windows rollout paths using the \\?\ prefix.

---

13. Projectless conversations can still be valid

A thread can have:

project_id = null

without being corrupted or deleted.

This means:

Thread exists
but
Thread is not associated with a Project

Do not automatically assign such a thread to a Project based only on its title or directory.

If a reliable historical Project assignment exists, use that information.

---

14. Use one read-only diagnostic when something is missing

A migration guide should not require users to run dozens of forensic scripts.

If a conversation is missing or appears empty, ask an AI assistant to generate one read-only diagnostic PowerShell script.

That diagnostic should collect, for each affected thread:

1. Thread ID
2. Thread title/name
3. Project ID
4. Archived status
5. Thread source
6. History mode
7. Current working directory
8. Rollout path
9. Rollout file size
10. Whether the rollout exists
11. session_index entry
12. Projection byte offset
13. Projection ordinal
14. Projected turn count
15. Projected item count
16. subagent_history_start_ordinal, if applicable
17. Project mapping
18. Legacy-to-new Project mapping, if applicable

The diagnostic should be:

READ-ONLY
NO DATABASE WRITES
NO ROLLOUT MODIFICATION
NO AUTHENTICATION CHANGES
NO POWERSHELL EXIT

The AI should classify the situation before generating any recovery script.

---

15. AI-assisted migration specification

If this guide is given to an AI assistant, the AI should interpret the task using the following rules.

Profile variables

Use generic variables:

OLD_USER = User1
NEW_USER = User2

OLD_CODEX_HOME = C:\Users\User1\.codex
NEW_CODEX_HOME = C:\Users\User2\.codex

Never hard-code a real user's name unless the user explicitly provides it.

Mandatory safety rules

The AI must:

1. Keep OLD_CODEX_HOME untouched.
2. Close Codex before copying or modifying local files.
3. Back up NEW_CODEX_HOME before migration.
4. Keep the new user's authentication state.
5. Never copy old auth.json as part of a normal history migration.
6. Preserve original rollout files.
7. Prefer application-level Archive/Unarchive over manual archive-state edits.
8. Use read-only diagnostics before database repair.
9. Back up SQLite databases before modifying them.
10. Never use exit to close PowerShell.
11. Provide any required PowerShell/Node script in the same response that explains the action.
12. Never expose secrets while displaying diagnostic output.

Recommended migration order

1. Prepare a fresh NEW_USER Codex profile
2. Back up NEW_USER .codex
3. Close Codex
4. Copy sessions/
5. Copy archived_sessions/
6. Copy session_index.jsonl
7. Preserve NEW_USER authentication
8. Migrate Project definitions
9. Migrate Project roots
10. Migrate thread.project_id relationships
11. Migrate legacy Project ID -> new Project ID mappings
12. Remap old workspace paths to new workspace paths
13. Start Codex
14. Check Projects
15. Check active history
16. Check Archived Chats
17. Investigate only exceptional threads

Recovery order

If a conversation is missing:

1. Check Archived Chats
2. Check whether the rollout exists
3. Check the state_5.sqlite thread row
4. Check the Project association
5. Check the session index
6. Check the thread history projection
7. Check the subagent history boundary if applicable
8. Only then consider targeted recovery

The AI should not jump directly from:

"Conversation is not visible"

to:

"Edit SQLite database"

---

16. Expected result

A successful migration should result in something like:

User2
   |
   +-- Codex
       |
       +-- Project A
       |     +-- historical thread 1
       |     +-- historical thread 2
       |
       +-- Project B
       |     +-- historical thread 3
       |
       +-- Projectless historical threads
       |
       +-- Archived Chats

The goal is not merely that the files exist.

The target state is:

Original history
        +
Original Project structure
        +
Correct thread associations
        +
New Windows paths
        +
New authentication
        =
Usable Codex installation

---

17. Migration checklist

[ ] Old profile preserved
[ ] New profile authenticated normally
[ ] New .codex backed up
[ ] Codex closed before migration
[ ] sessions/ copied
[ ] archived_sessions/ copied
[ ] session_index.jsonl copied
[ ] Old authentication files NOT copied
[ ] Projects migrated
[ ] Project roots remapped
[ ] Thread-to-Project associations migrated
[ ] Legacy/new Project ID mappings preserved
[ ] Archived Chats checked
[ ] Important historical threads opened
[ ] Important threads show their content
[ ] New conversations can be created
[ ] Original backups retained

---

18. Related Codex Issues and References

The technical distinctions in this guide are not based on a single migration experience. Similar behaviors have been independently reported in the public Codex repository.

Project and migration problems

openai/codex #36663 — Windows migration drops existing Codex project-to-thread associations

Describes a Windows migration where local session/thread data remained available but Project-to-thread associations were lost. ([github.com](#36663))

openai/codex #42867 — Projects disappear while threads move to Recents

Describes Projects and Threads remaining in SQLite while thread Project assignments disappear. ([github.com](#42867))

Session/index visibility

openai/codex #22452 — Local thread history/index drift

Documents cases where local Codex state and the visible thread list become inconsistent. ([github.com](#22452))

Archive behavior

openai/codex #39150 — Windows archive failure involving \\?\ rollout paths

Documents a Windows archive failure caused by rollout path handling. ([github.com](#39150))

History projection

openai/codex #38762 — Migrated persisted subagent threads with empty projected history

Documents a case where a migrated subagent rollout remains non-empty while projected history appears empty because of the subagent_history_start_ordinal boundary. ([github.com](#38762))

openai/codex #41566 — Duplicate rollout ordinal freezes paginated history projection

Documents history projection becoming stuck because of a duplicate ordinal in the rollout. ([github.com](#41566))

openai/codex #42027 — Interrupted turn causes duplicate ordinal and breaks history projection

Documents a related projection failure after an interrupted turn. ([github.com](#42027))

The issue list above is not exhaustive and may change as Codex evolves.

---

AI disclosure

This guide was prepared with the assistance of an AI system and was subsequently reviewed and structured for practical use.

It was created from technical experience gained during a Codex migration/recovery process. Relevant Codex GitHub issues that is found by AI have also been added as references to the guide.

This is not an official migration procedure; it is a personal experience and knowledge-sharing guide.

The information described here may change between Codex versions. Always create an independent backup before modifying an existing Codex profile.