Content
# Claude Code → Codex App Ecosystem Sync
One prompt for Codex App to migrate and verify the Claude Code ecosystem: skills, MCP, instructions, hooks, subagents, memory, recent sessions, and project-local settings.
Claude Code remains the source of truth for global user settings. For project-local skills, the source of truth is now the project itself: `<project>/.agents/skills/<name>/SKILL.md`, and `.claude`, `.codex`, and `.cursor` receive compatible symlink-mirrors.
## Quick Start
Open Codex App in any project and send one prompt:
```text
Read the repository https://github.com/2030ai/2030ai-claudecode-allecosystem-sync
and use it as an instruction for ecosystem-sync.
Goal: Ensure full functionality of my Claude Code ecosystem in Codex App.
Verify and, if necessary, synchronize global and project-local skills, MCP servers,
AGENTS/CLAUDE instructions, hooks, subagents, recent sessions, Codex trusted projects,
and related memory/context elements.
First, perform an audit/dry-run and show a short list of actions.
Write to configs only after my confirmation.
Do not delete or overwrite existing files, do not touch ~/.codex/auth.json,
do not show tokens, and mask all secrets as <TOKEN>.
Work flexibly and cross-platform: determine the OS, home directory,
current project, and usual project folder. On Windows, use PowerShell/Python/native APIs,
on macOS/Linux, use shell or Python. Ask only if it's risky to continue.
```
For read-only verification, replace the phrase "if necessary, synchronize" with "only verify, do not change".
The same text is available separately in [`PROMPT.md`](PROMPT.md) for easy copy-paste without README.
## What Codex Should Do
- Find Claude Code configs and skills in `~/.claude/`.
- Connect global skills in `~/.codex/skills/`, without touching native Codex skills.
- Connect project-local skills from `<project>/.agents/skills/` to mirrors `<project>/.claude/skills/`, `<project>/.codex/skills/`, and `<project>/.cursor/skills/`.
- Synchronize MCP from Claude Code to Codex TOML, including HTTP MCP via `url` + `http_headers`.
- Verify `AGENTS.md` / `CLAUDE.md`, project trust in Codex, and local project configs.
- Verify Claude hooks and suggest only safe reviewed-migration to Codex hooks.
- Verify Claude slash commands, but transfer them only to skills, without creating slash-command shims.
- Verify Claude subagents and suggest Codex custom agents if roles are really needed.
- Verify global/project `MEMORY.md` and memory: transfer rules to `AGENTS.md`/docs, and use Codex Memories only as a local recall-layer.
- Verify recent sessions: prefer the official Codex import flow or summarize selected sessions, do not copy transcript files in bulk.
- First, show an audit/dry-run, then perform changes only with confirmation.
## Windows and Linux
The instruction is not tied to macOS. Paths via `~` refer to the user's home directory:
- macOS/Linux: `~/.claude`, `~/.codex`, `~/.cursor`.
- Windows: `%USERPROFILE%\.claude`, `%USERPROFILE%\.codex`, `%USERPROFILE%\.cursor`.
Codex should use platform-native operations. Commands in `SKILL.md` are examples, not a requirement to run Bash on Windows. For symlinks on Windows, Developer Mode or running with permissions that allow creating symbolic links may be required; if a symlink cannot be created, the agent should stop and explain what to include, rather than copying files silently.
## Main Guarantees
- Only addition: no deletion, no silent overwrite.
- Native Codex/Cursor skills are not overwritten.
- `~/.codex/auth.json` is never touched.
- Tokens are not output to logs and not shown to the user.
- If a config does not parse, the agent stops and shows an error.
## If Installation as a Skill is Needed
The main scenario is the prompt above. Installation as a skill is optional.
If you still want a locally installed skill:
```text
Clone https://github.com/2030ai/2030ai-claudecode-allecosystem-sync.git
as a skill ecosystem-sync in ~/.claude/skills/ecosystem-sync.
If the directory already exists, perform a git pull.
```
After installation, ask the agent to use `ecosystem-sync` in the required mode:
```text
Use ecosystem-sync in audit mode.
Use ecosystem-sync in sync mode.
```
## Files
- [`SKILL.md`](SKILL.md) — main instruction for the AI agent.
- [`PROMPT.md`](PROMPT.md) — short prompt for launching from Codex App.
- [`references/platform-matrix.md`](references/platform-matrix.md) — what and where is synchronized.
- [`references/adr-2026-project-local-skills-source.md`](references/adr-2026-project-local-skills-source.md) — decision on `.agents/skills` as the source of truth for project-local skills.
- [`references/mcp-format-guide.md`](references/mcp-format-guide.md) — MCP JSON ↔ TOML conversion rules.
- [`references/native-skills-registry.md`](references/native-skills-registry.md) — native skills that should not be touched.
- [`references/troubleshooting.md`](references/troubleshooting.md) — diagnostics of common problems.
- [`scripts/check-project-skill-layout.py`](scripts/check-project-skill-layout.py) — read-only verification of canonical `.agents/skills` and mirror symlinks in `.claude`, `.codex`, `.cursor`.
README in Russian is for people. `SKILL.md` and `references/` in English are for AI agents.
## License
MIT
