🗺️ The three levels of migration
One click, one command, personal. The newsletter that gave rise to this course splits the migration from Claude to Codex into three levels. The first two are mechanical and quick; the third is the one that really matters and the one no tool does for you. Here you'll understand each level, what is actually model-specific, why most of the work is a cleanup, and when it's worth building your own harness.
🖱️ Level 1: import in the Codex app
The shallowest level is the easiest: you open the Codex desktop app, click Import, and it pulls your skills, commands, plugins, projects and chat sessions from Claude Code. That's the "one click" promise. It works, and for anyone who just wants to try Codex with what they already have, it does the job.
But there's a catch that the audit of this machine revealed: the Codex CLI (the terminal version, 0.154 at the time of the diagnosis) has no import command. The "one click" exists only in the desktop app. If your workflow lives in the terminal, level 1 simply isn't available to you. That's why this course exists: for levels 2 and 3.
New here? "Native import" is when the destination tool itself offers an official button or command to bring in another tool's configuration. "CLI" is the command-line version (you type codex in the terminal); "desktop app" is the window with a graphical interface. They're the same product, but they don't always have the same features.
✓ What level 1 solves
- ✓Brings in skills, commands and plugins all at once, without you touching a file.
- ✓Copies projects and chat sessions, so your history doesn't disappear.
- ✓Ideal for trying out Codex in 5 minutes.
✗ What it doesn't solve
- ✗It doesn't exist in the CLI: anyone working in the terminal is left out.
- ✗It copies the noise along with everything else: dead skills, old sessions, unapproved memory.
- ✗It doesn't separate anything: you still have two brains, now duplicated.
- ✗Nothing guarantees Codex will actually use what it imported.
Key concepts
The destination tool's official button. Only in the Codex desktop app.
Same product, different features. CLI 0.154 has no import.
Importing duplicates the brain; it doesn't make it portable.
Run codex --help and look at the command list yourself.
⌨️ Level 2: one command
The second level is the idea of one command that carries all your Claude Code resources over to Codex. The original text imagines something like npx migrate to codex and suggests it could be adapted for a Gemini stack. It also recommends, before running anything, letting an agent audit the entire Claude configuration so that no detail gets lost.
That hypothetical command doesn't exist off the shelf. That's why the agente-claude-codex kit was born: it is level 2 of this machine, broken into five scripts that run in order and that you will actually use in Track 2.
Read it as a staircase: level 1 is mechanical and shallow, level 2 automates the switch, and only level 3, highlighted, carries what survives a change of model. The higher up, the more durable.
🧰 This machine's "one command": five scripts in order
scripts/doctor.sh and scripts/audit.sh: diagnose the environment and inventory skills, hooks and MCP, without changing anything.
scripts/adapt-instructions.sh: splits CLAUDE.md into a portable AGENTS.md plus a Claude-only residue.
scripts/init-core.sh: installs the portable core without overwriting what already exists.
scripts/sync-skills.sh: one canonical skill source, per-runtime generated copies, drift check.
scripts/readback-test.sh: opens a fresh session in each runtime and proves the agent read and used the context.
💡 Practical tip
Every level 2 script starts in audit mode: it reads and reports, it doesn't change. Only after you've read the report and approved does the next step modify files, and always with a backup alongside. If a "migration command" you find out there has no audit phase, be suspicious.
Key concepts
Automated, reproducible migration, not manual.
An agent inventories everything so nothing gets lost.
The kit that implements level 2 in five scripts.
Every step has a backup or generates a proposed file.
🧠 Level 3: the durable personal layer
This is the level that really matters for most people. This is where private knowledge, project context, the overview.md, the sources.md, the playbooks, the handoffs and the documentation come in. It is the durable layer, the one that isn't tied to any specific model. No import button and no script does this for you, because it is the way you work, not a configuration.
Think about what would happen if Claude and Codex disappeared tomorrow and you had to use a third agent. What would you want to have saved in plain files, readable by anyone? That is level 3.
Private knowledge
Facts about you, your clients, your projects. On this machine: the runbooks for Skool, the INEMA.PRO login, the Magnific models.
Project context
What each project is, where it lives, what works, what is pending. Today scattered across 165 CLAUDE.md files.
Playbooks and processes
How you publish, version, generate images, deliver. Rules that apply to any agent working with you.
Handoffs
The structured summary of each session: decisions, open items, next steps, file paths. Travels to any provider.
✓ Signs that it is at level 3
- ✓It is plain Markdown, inside the project, with no plugin dependency.
- ✓A person understands it when opening it, not just an agent.
- ✓It has a date, a source and an owner.
- ✓It survives if you switch tools tomorrow.
✗ Signs that it is still level 1 or 2
- ✗It lives in
~/.claude/projects/*/memoryand only Claude reads it. - ✗It sits in 2.3 GB of JSONL sessions that nobody will ever reread.
- ✗It depends on a hook or plugin the other runtime does not have.
- ✗It was imported, but never read or approved.
Key concepts
What survives a model switch.
Verified facts and where they came from. Details in 1.4.
A written process that any agent follows.
Session summary that the next session reads first.
🧹 The big cleanup
The main mindset shift, in the words of the original text: most of this is simply a big cleanup. It sounds highly scientific, but it is basically Marie Kondo for your folders, the same kind of tidying you would do on your computer even if AI did not exist.
Many people's Claude Code brain is full of dead files, old stuff, archived documents and irrelevant information. Migrating that raw only carries the noise across. Before migrating anything: clean up the "second brain", archive by default, and bring information back into context only when it is needed.
New here? "Marie Kondo for folders" is the rule of keeping only what is still useful and archiving the rest. "Second brain" is the set of notes and files where you keep what does not fit in your head. "Archive by default" means the rule is to move things out of the way; bringing them back is the exception, done on demand.
📊 The noise on this machine, measured in the 2026-09-14 diagnostic
- •6,859 JSONL sessions from Claude, 2.3 GB, plus 209 from Codex. History, not source.
- •227 memory folders with 869 files that only Claude reads and nobody approved.
- •A 1,391-line CLAUDE.md in one project (ruflo), 542 lines in another. A file that size becomes noise in both runtimes.
- •11 archived skills and 117 active ones, 89 of which exist only in Claude.
Take inventory
Run the audit before deciding. You cannot clean what you cannot see.
Archive by default
A skill that has not run in 90 days, an old session, unused memory: off to the archive. Nothing is deleted, it just gets out of the way.
Promote what is worth it
A verified fact goes to overview.md with date and source. A stable rule goes to AGENTS.md. The rest stays where it is.
Only then migrate
With a lean brain, what crosses over to Codex is small, clear and useful.
Key concepts
Cleaning is most of the work, not the migration.
Moving out of the way is the rule; bringing back, the exception.
Sessions, memory and giant CLAUDE.md files have a number.
Context enters the session when the task calls for it.
🎯 What is truly model-specific
Here is the good news that changes the size of the problem: the part truly tied to the provider is small. Basically, only agents.md and claude.md are strongly bound to a tool. Gemini also uses agents.md. GLM can be instructed to respect that file. claude.md is the only truly Claude-specific exception. Practically everything else is portable Markdown.
Compare the sizes: the small box is everything that depends on the provider, two instruction files. The large box, highlighted, is your real work, and it is just Markdown that any agent reads.
🧩 Who reads what
Reads
CLAUDE.md. With @AGENTS.md on the first line, it imports the portable one.Reads
AGENTS.md. Without it, it goes in "blind": 13 projects on this machine are like that.Also reads
AGENTS.md.Can be instructed to respect
AGENTS.md via the prompt or the harness.⚠️ The mistake to avoid
Keeping two sources of truth: a hand-written CLAUDE.md and a hand-written AGENTS.md, each with different rules. On this machine, 39 projects have both files and nobody knows which one is in charge. The right pattern is a single portable file (AGENTS.md) and the other one importing it (@AGENTS.md) plus the specific residue.
Key concepts
CLAUDE.md and AGENTS.md are what ties you to the provider.
Codex, Gemini and GLM read it; Claude imports it.
The core does not change; the edge translates for each tool.
Never two diverging instruction files.
🔧 When building your own harness is worth it
A common temptation is to build an "OmniAgent" or a super-harness that wraps every model. For Claude and Codex, the text is blunt: don't waste time on that. Their harnesses are already highly optimized, and the vendors themselves do the work of tracking and adapting the harness as new models appear.
Where is it worth building your own? For local models. In those cases the default harness is usually much weaker. That is what the author does with PyHarness, training and evolving it from excellent sessions done with strong models. On this machine, the analogous case is dsh-sandbox and openpcbotv3, which you will see in Track 3.
New here? A "harness" is the structure around the model: the loop that reads your message, decides to call tools, runs commands, reads files and returns the answer. Claude Code and Codex are harnesses. "PyHarness" is the custom harness, in Python, that the author of the text maintains for local models, using good sessions from models like Astra and Fable as a reference. A "super-harness" would be a single harness on top of every model.
✓ Building a harness is worth it when
- ✓The model is local and its default harness is weak.
- ✓You have excellent sessions from strong models to use as a reference.
- ✓Privacy, cost or offline requirements demand running everything at home.
✗ Not worth it when
- ✗The target is Claude or Codex: the vendor already optimizes and updates it.
- ✗The motivation is "unify everything": what unifies is the context, not the harness.
- ✗You haven't done the cleanup yet or don't have the durable layer in place.
🔭 Two warnings from the original text
- •All of this is iterative. Each change can improve a skill for one model and break the same skill for another. Keep track of what each model actually needs.
- •Closed models may no longer need skills. If they are trained on your conversations, many skills become unnecessary. Local models may still depend on them. Build agnostic, but keep track of each provider.
Key concepts
The tool loop wrapped around the model.
Not worth it for Claude and Codex: they already handle this.
Here it is worth it: the default is weak and you can train your own.
Improving for one can break another. Always measure.
Self-check (optional): you work in the terminal with the Codex CLI and want to migrate your Claude setup. Which path is available?
🎯 Module summary
Next module:
1.4 — Anatomy of a portable workspace: AGENTS.md, context/, tasks/, handoffs/