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
9
10## Start the migration
11
121. Open **Settings** in the Codex app.
132. On the **General** page, find **Import other agent setup**.
143. Select **Import** or **Import again**.
154. Review what Codex found, choose what to bring over, then select **Import**.
165. After the import finishes, select **View imported files** if you want to inspect the result.
17
18## How migration works
19
20Codex checks both your user-level setup and the current project. User-level
21setup comes from files on your machine; project-level setup comes from files in
22the repository you have open.
23
24When you import, Codex:
25
261. Detects the setup it can find.
272. Imports the selected items it can migrate directly.
283. Checks again after the import finishes.
294. Offers to continue the migration in a new thread if anything still needs
30 follow-up work.
31
32## What Codex can import
33
34| Detected setup | Codex destination |
35| ------------------------------------- | -------------------------------------- |
36| Instruction files | [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md) |
37| `settings.json` | [`config.toml`](https://developers.openai.com/codex/config-basic) |
38| Skills | [Codex skills](https://developers.openai.com/codex/skills) |
39| Recent sessions from the last 30 days | Codex threads and projects |
40| MCP server configuration | [Codex MCP configuration](https://developers.openai.com/codex/mcp) |
41| Hooks | [Codex hooks](https://developers.openai.com/codex/hooks) |
42| Slash commands | [Codex skills](https://developers.openai.com/codex/skills) |
43| Subagents | [Codex agents](https://developers.openai.com/codex/subagents) |
44
45## Finish remaining setup in a new thread
46
47Some detected setup does not have a clean one-to-one mapping into Codex. For
48those items, Codex can open a new thread with the
49[`migrate-to-codex`](https://github.com/openai/skills/tree/main/skills/.curated/migrate-to-codex)
50skill to help finish the migration.
51
52When that happens, Codex shows the remaining setup and offers **Continue in
53Codex**.
54
55
56
57If you continue, Codex opens a new thread with the remaining work already filled
58in. The thread keeps user-level setup separate from project-level setup so you
59can see where each remaining item belongs.
60
61
62
63## What to review after import
64
65Review any migrated setup before you rely on it, especially:
66
67- Tool restrictions or permissions in imported skills and agents.
68- MCP server settings that use custom authentication, headers, environment
69 variables, or transports.
70- Hooks whose behavior may differ in Codex.
71- Plugins, marketplaces, or other remaining setup that needs manual follow-up.
72- Prompt templates or command-style prompts that depend on arguments, shell
73 interpolation, or file-path placeholders.
74
75## After you switch
76
77Once the import finishes, open one of your migrated projects and continue from
78there. If you are new to Codex, see the [quickstart](https://developers.openai.com/codex/quickstart) for the
79rest of the setup flow.
