🧠 Fundamentals

"Lock-in" means being stuck with one vendor. On this machine it takes concrete form: 165 projects with rules in CLAUDE.md, 869 memory files and 2.3 GB of sessions that only Claude Code knows how to read.

You only notice the lock-in the day you open Codex and it starts from scratch. Seeing this beforehand is what motivates the separation.

Lock-in, native memory, JSONL session, "Codex comes in blind".

Durable is what survives a model switch: project context, playbooks, decisions, handoffs, documentation. Disposable is native state: cache, raw history, harness configuration.

Migrating everything carries noise along. Migrating only the durable part fits in Markdown and works in any runtime.

Durable layer, native state, portable Markdown, "archive by default".

Claude, Codex, Gemini or a local model become mere executors. What needs to survive is your work structure, not whichever provider is current.

Each new model version can improve one skill and break another. A stable structure absorbs those changes without a rebuild.

Executor, portable layer, provider independence.

Think of two clients, North Star and Harbor. What the two have in common goes in the center, shared; only what is exclusive stays in its own folder. The same applies to runtimes: what Claude and Codex share goes in the center.

The bigger the middle area, the more reusable the system and the less duplicated maintenance.

Intersection, centralize what is shared, specific folders only for what is exclusive.

Without the separation, a second runtime stays underused: in the real diagnosis, 2,424 sessions in Claude versus 64 in Codex over 14 days, with Codex lacking a global AGENTS.md, lacking MCP and having a quarter of the skills.

The cost is not just money: it is rework, lost context and dependence on a single vendor at moments when you are blocked.

Underuse, rework, single-vendor risk.

What must survive a model switch is the layer of context + knowledge + Markdown + processes + handoffs + memory + tools. In one sentence: don't migrate your brain from Claude to Codex; separate the brain from the model.

It's the yardstick for every decision in the course: if something doesn't fit into one of these seven layers, it's probably native state and stays in the residue.

The seven layers, runtime residue, the one-sentence summary.

The model is the AI brain (Claude Fable, GPT-6 Astra, a local Qwen). The runtime is the program you run in the terminal (Claude Code, Codex CLI). The harness is the "bodywork" around the model: tools, execution loop, permissions, memory.

Almost everything that "locks you in" lives in the harness, not the model. Separating the three names shows you where to act.

Model, runtime, harness, agentic loop.

An instructions file is the text the runtime reads before working. Claude reads CLAUDE.md; Codex, Gemini and OpenCode read AGENTS.md. It's the only point truly tied to the provider.

With a portable AGENTS.md and a CLAUDE.md that starts with "@AGENTS.md", both runtimes read the same source.

CLAUDE.md, AGENTS.md, @AGENTS.md import, explicit reading order.

A skill is a folder with a SKILL.md (instructions on how to do a task) and, sometimes, scripts. Claude looks in ~/.claude/skills; Codex in ~/.codex/skills and ~/.agents/skills; the project may have .agents/skills.

The format is almost the same. What changes is the discovery path and the tools the skill assumes exist.

SKILL.md, discovery paths, canonical skill, per-runtime adapter.

MCP (Model Context Protocol) is a standard for the runtime to access external tools and data, such as Magnific or Metricool. It grants access; it doesn't merge chat histories, doesn't resolve memory conflicts, doesn't separate clients.

Many people treat MCP as portable memory. It's plumbing. Registering an MCP in Codex is what unlocks the skills that depend on it.

MCP, tool server, referenced credentials (never copied).

A hook is a script the runtime fires on an event (session start, after editing). A plugin is an extension installed in the runtime. A subagent is a role with its own prompt. The events and formats are not the same between Claude and Codex.

These three are the "residue" that doesn't migrate. Knowing this keeps you from trying to port what has no equivalent.

SessionStart vs PostToolUse, plugin, subagent, native-only.

A handoff is a structured summary at the end of the session: decisions, open items, next steps, file paths, saved in Markdown. Prime is reading that summary at the start of the next session, in any runtime.

It's the mechanism that replaces dependence on native JSONL histories. Session → handoff → Markdown → prime → new session.

Handoff, prime, handoffs/latest.md, cross-runtime continuity.

The Codex desktop app has an Import button that brings in skills, commands, plugins, projects and sessions from Claude Code. Codex CLI 0.154 doesn't have that command: the "one click" only exists in the graphical interface.

It keeps you from hunting for a command that doesn't exist and shows that the native import is part of the solution, not the solution.

Native import, app vs CLI, items skipped during import.

The source text imagines an "npx migrate to codex". Here that command is the agente-claude-codex kit: doctor, audit, adapt-instructions, init-core, sync-skills and readback-test, always in audit mode before changing anything.

An agent audits the whole setup before migrating, so no detail gets lost. This is the level that Track 2 walks through step by step.

Kit, agent-driven audit, reversible scripts.

Private knowledge, project context, overview.md, sources.md, playbooks, handoffs and documentation. It's the layer that isn't tied to any model.

For most people it's the only level that changes the outcome. The other two are logistics.

Durable layer, playbooks, overview.md, sources.md.

Most of the migration is cleanup: dead files, old stuff, archived documents, irrelevant information. Archive by default and bring things back only when you need them. A 1,391-line CLAUDE.md is noise in both runtimes.

It's the same kind of tidying you'd do on your computer even without AI. Migrating clutter just moves the clutter somewhere else.

Archive by default, context on demand, clean second brain.

Basically only the instructions file is tied to the provider. Gemini also uses AGENTS.md; a local model can be told to respect it. CLAUDE.md is the Claude-specific exception. Practically everything else is portable Markdown.

It reduces the fear: the part that needs an adapter is small and well known.

Specific instructions, portable Markdown, minimal adapter.

For Claude and Codex, don't waste time building a "super-harness": the vendors already optimize and adapt theirs to every new model. For local models, the default harness is weak, and that's where evolving your own pays off, using excellent sessions as reference.

It focuses the effort: portable context for everyone, a custom harness only where it makes a difference.

OmniAgent, super-harness, harness for local models, dsh-sandbox.

README.md is onboarding for people: how to run, how to test, structure. AGENTS.md is short, aimed straight at the agent, and starts with the reading order of the other files.

Mixing the two makes the agent read a tutorial and the human read machine rules. Separating them keeps each one lean.

Audience of each file, reading order, concise instruction.

overview.md holds what the project is, verified facts with source and date, preferences and hypotheses. current-state.md says what works and what is pending today.

A new session answers "what's the goal?" by reading those two files, without digging through history.

Overview, current state, dated fact, starting briefing.

sources.md lists each source with its type (local file, dated export, live connection), date, scope and refresh rule. decisions/ has one file per accepted decision, with context and consequences.

When two versions of a piece of information clash, the source and the accepted decision settle it. Without that, the most recent file wins, and it isn't always right.

Source, dated snapshot, accepted decision, provenance.

The file for the current work: goal, who owns it, a verifiable definition of done, the concrete next action and blockers.

The agent comes to understand not just the history, but what is being done right now and when it can say "done".

Current task, owner, acceptance criteria, next action.

The most recent handoff, always at the same path: project and scope, goal, accepted state, changed files, checks run with results, open questions and the exact next action.

A fixed path ("latest") is what lets Codex pick up where Claude left off, and vice versa.

latest.md, accepted state, checks with evidence, next action.

Reusable skills live in .agents/skills/ (where Codex looks) and common commands in scripts/. But context/, tasks/ and handoffs/ are your own convention: no runtime loads them on its own. AGENTS.md has to tell the agent to read them.

A pretty structure the agent ignores is worth nothing. The explicit reading order is what makes it real.

Convention vs auto-load, .agents/skills, reproducible scripts.

A fact is what has been verified (the Codex version is 0.154). A preference is the owner's taste (commit author inematds). A hypothesis is what is assumed without checking. A decision is what was accepted after discussion.

A hypothesis written down as a fact becomes a wrong rule the agent follows with confidence. Separating the types cuts that error off at the source.

Fact, preference, hypothesis, decision.

Every durable note carries an ID, the scope (project, machine, client), the source, the observation date, the status (draft, accepted, revoked) and when to review or expire it.

It answers the classic question: "which of the several versions of this information is the correct one?".

Note metadata, observation date, expiration, owner per type.

Provenance is the traceable origin of a piece of information. In a conflict, the most trustworthy source and the accepted decision win, not the newest file. openpcbotv3 does this by marking the old version with superseded_by instead of deleting it.

Timestamp rewards whoever wrote last, including an agent that guessed. Provenance rewards whoever verified.

Provenance, conflict, superseded_by, never delete, only hide.

Native memory (869 Claude files, conversations) is raw material. Promoting means choosing a verified fact and writing it into overview.md with source and date, deliberately. Never bulk-copy.

Copying everything carries hypotheses and noise along. Promoting fact by fact keeps the overview short and trustworthy.

Deliberate promotion, raw material vs source, curated vault.

Any search index, cache or vector database must be rebuildable from the records you own. The source of truth is the Markdown; the index is derived.

If the index is the only copy, you have lock-in again, just inside a search tool.

Source vs derived, rebuild, curated snapshot before retrieval.

API keys, raw native state and personal or client material do not go into the portable repository. Keys stay in .env and are referenced; raw evidence is kept separate from what was promoted.

On this machine there are 269 secret files in ~/projetos. A portable workspace that drags them along is a leak waiting to happen.

Referenced secret, separate raw evidence, client scope.

Both mega-prompts have a MODE field. In audit, the agent inspects, classifies and returns a plan with a proposed tree, mappings and acceptance criteria, without touching any file. Only then do you run it again with MODE: implement and an agreed scope.

Migration is hard to reverse. Reading the plan first costs minutes; undoing a mass copy costs days.

MODE audit/implement, reviewable plan, reversible changes, declared scope.

"Act as my migration engineer": confirms scope and evidence, inventories the system (instructions, skills, commands, hooks, plugins, MCP, memory), checks the target before converting, produces the plan as a table, implements only in implement, separates portable logic from native integration, verifies continuity and delivers with a handoff.

It is the complete script for an honest migration, including what does not transfer without changes.

WORKSPACE_ROOT, SOURCE_ROOTS, TARGETS, REPRESENTATIVE_TASK, KEEP_UNCHANGED.

"Act as my workspace architect": inspects before designing, proposes the smallest portable core, implements README/AGENTS/context/tasks/handoffs, defines who owns each piece of information, adds small native adapters, controls context distribution, proves portability and delivers. It has add-ons for personal, client or mixed use.

It works both for adapting an existing project and for being born portable from the very first commit.

PILOT_PROJECT, KNOWLEDGE_SOURCES, CLIENT_SCOPE, personal/client add-on.

Every asset in the setup gets one of four labels: reusable as is, needs an adapter, exists only in the source runtime, or unresolved. On this machine: 72 reusable skills, 15 adapter skills, 2 native, 1 without a SKILL.md.

It turns "migrate everything" into a list with a destination, rollback and test per item.

Source → target matrix, classification, rollback, acceptance criterion per asset.

Every check has one of three states. "Not run" is a valid and mandatory answer when access or time was lacking; it comes with the steps to reproduce. The PDF itself admits that no real migration was tested by the authors.

A report that distinguishes the three states is what separates a migration that was done from a migration that was declared.

Passed / failed / not run, reproduction, honest report.

A generated tree, a successful import or a configuration with valid syntax does not prove equivalent behavior. The proof is a fresh session that answers: current goal, one rule with its source file, last decision, next action and conflicts.

It is the continuity test that Track 2 actually runs, in Claude and in Codex. Found it? Read it? Understood it? Used it?

Readback in a fresh session, the 5 questions, proof of use.