🧠 Why separate the brain from the model
Everyone asks "how do I migrate from Claude to Codex?". The right question is a different one: what part of your work survives a model switch? This module shows where you are locked in without noticing, what is truly durable, and the principle that guides the entire course: don't migrate the brain, separate the brain from the model.
🔒 The invisible lock-in
You never signed a contract, but you're locked in. Every rule you wrote in a CLAUDE.md, every fact Claude stored in its memory, every session saved to a JSONL file: only Claude reads all of that. If you open Codex tomorrow, it starts from scratch, as if you had never worked at all. That is lock-in, and it is invisible because it grew one file at a time.
New here? Lock-in is being stuck with a vendor because leaving is expensive. CLAUDE.md is the instructions file Claude Code reads when it opens a folder. JSONL is a text format with one JSON object per line; that is how Claude records the history of each session. No other program cares about these files.
📊 The size of the problem on a real machine (diagnosis from 2026-09-14)
- •165 projects with CLAUDE.md, and only 54 with AGENTS.md (the file Codex reads).
- •869 memory files in 227 folders, which only Claude opens.
- •6,859 JSONL sessions, 2.3 GB of history that no other tool can use.
- •Codex, installed on the same machine, with no global instructions and no MCP: every session starts blind.
✓ Signs that you're in good shape
- ✓Your rules live in a file that any tool can read.
- ✓A colleague could open your project and understand its state without you.
- ✓You know where the last decision made is recorded.
✗ Signs of lock-in
- ✗"Claude knows" is the answer to where some piece of information lives.
- ✗Switching tools means re-explaining everything.
- ✗The session history is the only record of what was decided.
Key concepts
Dependency that grows without a contract, one file at a time.
Instructions that only Claude Code reads.
Facts stored in the format of a single tool.
Raw history, huge, unreadable by any other tool.
🗂️ What's durable and what's disposable
Not everything deserves to be migrated. Most of what sits in the Claude folder is residue: old sessions, discarded attempts, dead files. What's worth keeping is small and looks like a document: what the project is, what was decided, what's in progress, how each thing gets done. Separating the two is the first job, and it's more housekeeping than engineering.
Look at the center: what's yours lives in Markdown inside the project. The blue boxes at the edges are just executors; any of them can be swapped without the center changing.
✓ Durable: worth migrating
- ✓Project context: what it is, who it's for, what works.
- ✓Accepted decisions, with date and reason.
- ✓Playbooks and skills: how each task gets done.
- ✓Handoffs: where things stopped and what comes next.
✗ Disposable: archive by default
- ✗Entire JSONL sessions (2.3 GB of raw conversation).
- ✗Automatic memory without approval (869 files nobody reviewed).
- ✗Plugin and hook configuration: it belongs to the tool, not to you.
- ✗Archived skills you haven't used in months.
💡 Practical tip
Rule from the source text: archive by default, bring things back only when you need them. Before migrating anything, clean up your "second brain". Migrating residue only carries noise over to the new tool.
Key concepts
Context, decisions, playbooks, handoffs: what survives the switch.
Raw history and tool configuration.
The default is to store things out of the way; context only comes in when it is used.
Plain text that any tool can read. It is the brain's format.
🔄 Models change, your structure stays
Look at the timeline of the last few months: a new model every few weeks, each with its own name, harness and quirks. If the way you work depends on a specific model, it ages at the same speed. If it depends on a file structure, it ages at the speed of Markdown, which is to say almost never.
New here? A model is the AI brain itself (Claude, GPT, DeepSeek). A harness is the program that gives the model hands and eyes: it reads files, runs commands, keeps the history. Claude Code and Codex CLI are harnesses. Module 1.2 goes deeper into these terms.
Yesterday: one harness, one model
You picked a tool and shaped everything around it: rules, memory, shortcuts. It worked, and the price stayed hidden.
Today: two or three harnesses on the same machine
Claude for one thing, Codex for another, a local model for the cheap task. Each one starts from scratch because the brain stayed in the first one.
Tomorrow: the model you don't know yet
It will show up. The only question is whether you will re-explain everything or point to a folder and say "read this".
🧭 The sentence that sums up the course
"What really needs to survive a model switch is not Claude, Codex or Gemini. It is your layer of context, knowledge, Markdown, processes, handoffs, memory and tools."
Models may change. Your working structure should keep working.
Key concepts
Model: weeks. Markdown: years.
Any harness that reads the portable layer and acts.
Folders and files with a defined role, not a conversation.
The test: does pointing to a folder replace re-explaining?
⭕ The Venn Diagram: shared vs specific
The source text gives an example with two clients, North Star and Harbor: find out what the two have in common, centralize that part, and keep separate folders only for what is exclusive to each. The same logic applies to tools. What Claude and Codex have in common is almost everything: rules, context, decisions, skills in Markdown. What is specific fits in two files.
The green area in the middle is where your work lives. The blue edges are small on purpose: only what the tool requires. If the edges grow, you are rewriting the shared part twice.
📐 The tool-specific part is smaller than it looks
According to the source text, only AGENTS.md and CLAUDE.md are strongly tied to the provider. Gemini also reads AGENTS.md; GLM can be instructed to respect it. CLAUDE.md is the exception. Practically everything else is portable Markdown.
On the audited machine: of the 72-line global CLAUDE.md, 71 lines were portable and 7 were Claude-specific (interactive menus, plugins, hooks). That is the ratio you should expect.
Key concepts
What every tool uses. Centralize it here.
What is exclusive to each tool. Keep it small.
The instructions file that Codex, Gemini and others read.
The bigger the middle, the less you write twice.
💸 The cost of doing nothing
Not separating the brain from the model looks free, because nothing breaks today. The cost shows up in small doses: the Codex that answers wrong because it never read your rules, the decision made twice because it got lost in a session, the hand-copied skill that drifted from the original, the colleague (or you in three months) who has no idea where to start.
✗ What you pay without noticing
- ✗Re-explaining the project to every new tool.
- ✗Skills that drift apart: on the audited machine, 4 different places consumed skills with no single source.
- ✗Contradictory decisions because the "right" version was whichever came latest in the conversation.
- ✗Impossible to delegate: only your Claude account "knows".
✓ What separation gives back
- ✓Any executor joins the project and reads the same truth.
- ✓One skill, N generated copies, with drift checking.
- ✓Every decision has a file, a date and an owner.
- ✓You can switch models in an afternoon, not in a month.
⚠️ An honest warning from the source text
"All of this is iterative. Every change can improve a skill for one model and break that same skill for another." Separating the brain does not eliminate maintenance; it just happens in one place instead of in every tool.
Key concepts
Paid in small doses, never on an invoice.
Copies that diverge from the original over time.
Can another person or another agent pick it up?
One place to edit, N places to generate.
🧩 The core principle
Seven words make up the layer that survives: context, knowledge, Markdown, processes, handoffs, memory and tools. Each one becomes a folder or a file in your project, and each track of this course shows how. Keep the list; it is the map of what you are going to build.
Context and knowledge
What the project is, what is true today, where each fact came from. Becomes context/overview.md, current-state.md and sources.md.
Markdown and processes
The format and the "how it's done": AGENTS.md, skills, scripts. Portable because they are text.
Handoffs and memory
Where things left off and what was learned: handoffs/latest.md and facts promoted with approval.
Tools
MCP and scripts, registered per tool but referencing the same keys and the same data.
🎯 One-sentence summary
Don't migrate your "brain" from Claude to Codex; separate the brain from the model.
Claude, Codex, Gemini or local models become mere executors on top of a portable context layer.
Key concepts
Context, knowledge, Markdown, processes, handoffs, memory, tools.
What runs on top of the layer. Swappable.
What stays. Yours, in Markdown, inside the project.
The verb for the entire course.
Self-check (optional): which sentence best sums up this module's thesis?
🎯 Module summary
Next module:
1.2 — The vocabulary: runtime, harness, skill, MCP, hook, handoff