migrate.md +110 −0 added
1# Migrate to Codex
2
3Use the import flow to bring your instructions, configuration, skills, MCP
4servers, hooks, subagents, and recent sessions from another agent into Codex.
5Codex migrates the parts it can handle directly and can open a follow-up thread
6to help migrate anything that remains.
7
8<div class="not-prose my-6 max-w-4xl">
9 <CodexScreenshot
10 alt="Import from another agent in General settings"
11 lightSrc="/images/codex/migrate/import-flow-light.png"
12 darkSrc="/images/codex/migrate/import-flow-dark.png"
13 maxHeight="520px"
14 class="p-3 sm:p-4"
15 imageClass="rounded-xl"
16 />
17</div>
18
19## Start the migration
20
21<WorkflowSteps>
22
231. Open **Settings** in the Codex app.
242. On the **General** page, find **Import other agent setup**.
253. Select **Import** or **Import again**.
264. Review what Codex found, choose what to bring over, then select **Import**.
275. After the import finishes, select **View imported files** if you want to inspect the result.
28
29</WorkflowSteps>
30
31## How migration works
32
33Codex checks both your user-level setup and the current project. User-level
34setup comes from files on your machine; project-level setup comes from files in
35the repository you have open.
36
37When you import, Codex:
38
391. Detects the setup it can find.
402. Imports the selected items it can migrate directly.
413. Checks again after the import finishes.
424. Offers to continue the migration in a new thread if anything still needs
43 follow-up work.
44
45## What Codex can import
46
47| Detected setup | Codex destination |
48| ------------------------------------- | -------------------------------------- |
49| Instruction files | [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md) |
50| `settings.json` | [`config.toml`](https://developers.openai.com/codex/config-basic) |
51| Skills | [Codex skills](https://developers.openai.com/codex/skills) |
52| Recent sessions from the last 30 days | Codex threads and projects |
53| MCP server configuration | [Codex MCP configuration](https://developers.openai.com/codex/mcp) |
54| Hooks | [Codex hooks](https://developers.openai.com/codex/hooks) |
55| Slash commands | [Codex skills](https://developers.openai.com/codex/skills) |
56| Subagents | [Codex agents](https://developers.openai.com/codex/subagents) |
57
58## Finish remaining setup in a new thread
59
60Some detected setup does not have a clean one-to-one mapping into Codex. For
61those items, Codex can open a new thread with the
62[`migrate-to-codex`](https://github.com/openai/skills/tree/main/skills/.curated/migrate-to-codex)
63skill to help finish the migration.
64
65When that happens, Codex shows the remaining setup and offers **Continue in
66Codex**.
67
68<div class="not-prose my-6 max-w-4xl">
69 <CodexScreenshot
70 alt="Additional setup found after import"
71 lightSrc="/images/codex/migrate/additional-setup-light.png"
72 darkSrc="/images/codex/migrate/additional-setup-dark.png"
73 maxHeight="520px"
74 class="p-6 sm:p-8"
75 imageClass="!w-auto rounded-xl"
76 />
77</div>
78
79If you continue, Codex opens a new thread with the remaining work already filled
80in. The thread keeps user-level setup separate from project-level setup so you
81can see where each remaining item belongs.
82
83<div class="not-prose my-6 max-w-4xl">
84 <CodexScreenshot
85 alt="Follow-up migration task in Codex"
86 lightSrc="/images/codex/migrate/continue-with-codex-light.png"
87 darkSrc="/images/codex/migrate/continue-with-codex-dark.png"
88 maxHeight="320px"
89 class="p-6 sm:p-8"
90 imageClass="rounded-xl"
91 />
92</div>
93
94## What to review after import
95
96Review any migrated setup before you rely on it, especially:
97
98- Tool restrictions or permissions in imported skills and agents.
99- MCP server settings that use custom authentication, headers, environment
100 variables, or transports.
101- Hooks whose behavior may differ in Codex.
102- Plugins, marketplaces, or other remaining setup that needs manual follow-up.
103- Prompt templates or command-style prompts that depend on arguments, shell
104 interpolation, or file-path placeholders.
105
106## After you switch
107
108Once the import finishes, open one of your migrated projects and continue from
109there. If you are new to Codex, see the [quickstart](https://developers.openai.com/codex/quickstart) for the
110rest of the setup flow.