migrate.md Codex Docs, 2026-03-27 18:23 UTC → 2026-05-02 06:45 UTC

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![Import from another agent in General settings](/images/codex/migrate/import-flow-light.png)

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![Additional setup found after import](/images/codex/migrate/additional-setup-light.png)

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![Follow-up migration task in Codex](/images/codex/migrate/continue-with-codex-light.png)

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.