Claude Code β†’ Codex Β· model-agnostic workspace

Don't migrate the brain. Separate the brain from the model.

Audit kit, adapters and portable core to take your Claude Code setup to Codex, or to keep context, decisions, tasks and skills working with any model.

Claude β†’ Codex agent: migrate or stay agnostic
What it is

One command to audit, adapt and prove the migration

The newsletter describes three levels: import in the app (one click), run a command, and take care of the durable personal layer. This repo is level 2 and level 3, with scripts that start in audit mode and only then change anything.

πŸ” Read-only audit

Inventories skills, commands, subagents, hooks, plugins and MCP in Claude and Codex and classifies each item: reusable, adapter, native or unresolved. Nothing is bulk-copied.

🧩 Small adapters

CLAUDE.md becomes a portable AGENTS.md plus a Claude-specific remainder. Skills have one canonical source and per-runtime generated copies with drift checks.

βœ… Continuity proof

A fresh session in each runtime answers: objective, rule and source, last decision, next action, conflicts. A file existing is not proof. The agent having read and used it is.

How it works

Audit β†’ organize β†’ adapt β†’ test β†’ handoff

The core (context, decisions, tasks, skills, handoffs) lives in plain Markdown inside the project. At the edges, one adapter per tool. Claude, Codex, Gemini or a local model become just executors.

doctor.sh→ audit.sh→ adapt-instructions.sh→ init-core.sh→ sync-skills.sh→ readback-test.sh→ handoffs/latest.md

πŸ“ Portable core

AGENTS.md, context/overview.md, context/current-state.md, context/sources.md, context/decisions/, tasks/current.md, handoffs/latest.md, .agents/skills/, scripts/.

🏷️ An owner per kind of information

Stable instructions, current state, decisions, tasks and handoffs each have an owner and an update rule. Fact, preference, hypothesis and decision are different things.

πŸ” Daily cycle

Session β†’ Markdown handoff β†’ new session reads the handoff (prime). The structured summary travels to any provider.

Prerequisites

What needs to be installed

The scripts read the configuration folders of both runtimes. If one is missing, the matching step is marked as not run.

Claude Code

Migration source. Skills in ~/.claude/skills.

# version
claude --version

Codex CLI

Destination. Skills in ~/.agents/skills. The CLI has no native import.

# version and diagnostics
codex --version
codex doctor

polyskill

Turns a skill into a portable source and generates the per-runtime copies.

# install
npm i -g polyskill
User guide Β· step by step

From diagnosis to proof in seven steps

Every step is reversible. Installing a skill is a preview until you pass --apply, and replacing one makes a backup first. Secrets never go into the repo.

0

Clone and check the environment

Answers "is my environment ready?": git, python3, node, Claude Code, Codex CLI, sandbox, MCP, polyskill. Each item comes out as ok, warning or missing, with the command to fix it.

git clone https://github.com/inematds/agente-claude-codex
cd agente-claude-codex
scripts/doctor.sh  # [ok] / [aviso] / [FALTA]
1

Audit what exists

Produces a Markdown report with versions, the skills gap and the reusable / adapter / native matrix. Read-only.

scripts/audit.sh  # relatorios/auditoria-YYYY-MM-DD.md
2

Split portable instructions from the Claude remainder

Reads the project's CLAUDE.md and proposes a portable AGENTS.md plus a CLAUDE.md that imports AGENTS.md. Saves them as .proposto.md for you to review.

scripts/adapt-instructions.sh ~/projects/my-project
# review AGENTS.proposto.md and CLAUDE.proposto.md, then rename
3

Install the portable core in the project

Copies the template (context/, tasks/, handoffs/, AGENTS.md) without overwriting anything that already exists.

scripts/init-core.sh ~/projects/my-project
# then fill in AGENTS.md, context/overview.md and tasks/current.md
4

Port a skill with a canonical source

Recommended pilot: session-handoff, the mechanism the daily cycle relies on. Import, generate the copies, install and check drift. Install is a preview by default: it checks every destination before writing, is idempotent, and refuses symlinks or a different existing skill.

scripts/sync-skills.sh import session-handoff
scripts/sync-skills.sh build
scripts/sync-skills.sh install session-handoff            # preview: CREATE / UNCHANGED / CONFLICT
scripts/sync-skills.sh install session-handoff --apply    # writes; --replace swaps an old version with a backup
scripts/sync-skills.sh drift  # [ok] or [DRIFT] per runtime
5

Prove it with a fresh session in each runtime

Asks Claude and Codex the five readback questions from inside the project. Pass criterion: the answers cite AGENTS.md, tasks/current.md and handoffs/latest.md.

scripts/readback-test.sh ~/projects/my-project both
# relatorios/readback-claude-*.md and readback-codex-*.md
6

Close with handoff, open with prime

At the end of a session, the session-handoff skill writes a new snapshot to handoffs/history/ through the handoff-grava.py script (real UTC time, never overwrites). handoffs/latest.md becomes an index of open work, one line per subject, because several sessions may work on the same project. The script appends a state block (commit and fingerprint of the files), every confirmed item points to a proof (commit, test or file), and the handoff ends with 5 test questions. Finally it prints the resume command with the exact file of this session.

In the next session, the prime skill reads in read-only mode: it validates paths, checks whether the handoff went stale (--conferir), verifies the proofs, answers the test questions from the files and shows an N/5 score. It runs no tests, treats the handoff as data, and never resumes a deploy or a send on its own.

# end of session, in any runtime
session-handoff  # β†’ handoffs/history/2026-10-17T183328Z-robot.md + index in handoffs/latest.md
# the reply ends with the ready command (in Codex, /new instead of /clear):
/clear
/prime handoffs/history/2026-10-17T183328Z-robot.md   # opens THIS one, even if another session wrote later
# the subject also works (/prime robot), or nothing (/prime lists the open ones)
# session open in one project, work in another repo:
handoff-grava.py --assunto robot --repo ~/projetos/robot   # --conferir covers both; prime looks there
Use both together

Claude and Codex on the same work, each in its own role

Migrating does not force you to pick just one. One makes the first pass, the other reviews the real artifact, and the handoff carries the state from one runtime to the other. The table is a starting point, not a ranking: swap roles when the evidence from your task calls for it.

JobFirst passSecond passFinish line
PlanClaudeCodex critiques the assumptionsScoped plan with acceptance tests
Build a featureClaude, on a branchCodex reviews the diffTests pass and findings resolved
Review a documentEither one writesThe other checks facts and requirementsEvery required claim has evidence
Hard bugCodex with a bounded goalTests and a human checkpointMeasurable success or a clear blocker
Switch session or modelsession-handoffprime checks the current stateA correct recap before new work

One rule: give the second agent the same task brief and the real artifact (file, diff, test result), never a retelling of what the first one did. Both agreeing is not proof: they can share the same wrong assumption.

1. Plan and critique

One writes the plan (scope, assumptions, acceptance tests, risks); the other reviews it read-only with the same brief. Each finding becomes accepted, rejected with evidence, or open. Two rounds at most.

2. Build and review the diff

The builder works on a new branch, keeps existing changes and runs the tests. The reviewer gets the brief, the diff and the results and looks for bugs and regressions before cosmetics. No merge, deploy or publishing without you.

3. Goal with a stop condition

An observable objective (which suite, which input, which output), bounded scope, stop when it passes. If the same blocker survives two attempts, report and ask for the decision. A real time or cost cap is set in the environment, not in the prompt.

4. Handoff and prime across runtimes

The one leaving writes the snapshot to handoffs/history/ and updates handoffs/latest.md; the one arriving runs prime, checks the state without changing anything and waits for the current instruction. A single subscription works too: a second session reviews with the same files.

# the ready-made prompts (in Portuguese), with fields to fill in
cat prompts/05-usar-os-dois.md
# read-only review by the other runtime (through the subscription, never a paid API)
codex exec --sandbox read-only "Review plans/task-v1.md against tasks/current.md ..."
claude -p "Review the diff from git diff main...HEAD against the brief ..."

Adapted from the "Use Both: Claude + Codex Workflow Kit" by Prompt Advisers / Mark Kashef, MIT license. Kit guide Β· repository.

One context, many platforms

Your AI changes. Your context stays.

Your business context lives in a private GitHub repo that you own. Claude, ChatGPT, Codex and Gemini only get access, the same instructions and a test. Switched AI? Nothing to redo. The video explains the whole idea with drawings; the ready-made template is in template/.

Claude and Codex with the same context Β· 7min36 Β· in Portuguese, with Portuguese subtitles Β· open the player with chapters

The idea in 8 drawings

The portable context layer: AIs on top, a bridge in the middle, the context you control at the bottom
1. The layer. On top, where the AI works. In the middle, the bridge (git, connector, API). At the bottom, the context that is yours.
Files and documents on one side, live data on the other
2. What it is made of. Documents (business, voice, customers, skills, decisions) go to a document home; records that change all the time go to a database.
Claude and Codex working in the same local folder
3. Level 1: your computer. Claude and Codex already work in the same folder. The limit is keeping the laptop on.
Level 2: GitHub or Notion for files, a cloud database for live data
4. Level 2: a home in the cloud. GitHub (solo or technical team) or Notion (teams), plus a database such as Supabase for live data.
Creating a private GitHub repository
5. A private repository. A repository is just an online folder. An easy name, and always private.
Project instructions: the repository is the source of truth
6. The project instructions. The same block on every platform: the repo is the source of truth, read first, commit after, no secrets.
Codex creates a file, Claude reads and edits the same file
7. Round trip. One AI creates, the other reads and edits. Both commits show up in the same history.
The portable core suitcase: what travels and what does not
8. The suitcase. Context, skills, decisions and data travel. Chat history, app memory and model choice stay behind.

The ready-made template: connect each platform

# installs the portable core + the plataformas/ folder in your project (never overwrites)
scripts/init-core.sh ~/projects/mycompany-context
bash ~/projects/mycompany-context/scripts/check.sh   # 8 files [ok]
PlatformAccessInstructionsTest
Claude Code / Codex CLIgit clone the reporeads AGENTS.md on its own (Claude via CLAUDE.md β†’ @AGENTS.md)"read the context and state the goal"
Gemini CLIgit cloneGEMINI.md β†’ @AGENTS.mdthe same
Claude.ai (Project)Customize β†’ Connectors β†’ GitHub (integration + MCP)paste plataformas/instrucoes-projeto.mdedit a test line
ChatGPT (Project)Connectors β†’ GitHubpaste the same blockcreate context/teste.md
Codex cloudenvironment with the repoAGENTS.md is already in the repoask for an edit and check the commit

Tested on this machine (2026-10-13): in a project created by init-core.sh, Codex got the instruction block and created context/voz.md (commit + push); then Claude, with the same block, read the file Codex created, added a line and did commit + push. Both commits ended up in the same history. The Claude.ai and ChatGPT connectors follow the same block but depend on your account: run the round-trip test when you connect each one. (The template's files are written in Portuguese; translate them to your language if you prefer.)

Private repo

Business context is never public. Passwords and keys live in each platform's vault, never in the repo.

Memory becomes a skill

Whatever the AI learns becomes a rule in AGENTS.md, a skill in .agents/skills/ or a fact in context/. App memory does not travel.

Drive and Notion

Google Drive can read but cannot edit markdown well today. Teams without Git: Notion as the document home.

Tools

Each tool: when to use it, how to call it, what it produces.

A quick reference for the skills and commands that connect Claude and Codex. Everything runs on each assistant's subscription, with no API key.

ToolWhen to useClaude CodeCodexWhat it produces
session-handoffAt the end of a session, before switching assistant or model/session-handoff$session-handoffA recap in the chat and, if the project has handoffs/, AGENTS.md or CLAUDE.md (creating handoffs/history/ if missing), a new snapshot in handoffs/history/YYYY-MM-DDTHHMMSSZ.md with a full copy in handoffs/latest.md
primeAs the first message of the next session/prime$primeReads AGENTS.md, context/, tasks/current.md and handoffs/latest.md and returns the state, mismatches and one next step. Edits nothing
handoff + prime (Use Both kit)Projects using the Use Both format/handoff Β· /prime$handoff Β· $primeSnapshot in handoff/history/ and a one-line pointer in handoff/LATEST.md. If this kit's handoffs/latest.md is already in that pointer format, session-handoff keeps it
codex execClaude asking Codex for a review from the terminalcodex exec --sandbox read-only --output-last-message review.md '…'The critique saved to review.md. Codex only reads the project
claude -pThe reverse path: Codex asking Claude for a reviewclaude -p --model opus --effort medium '…' > review-claude.mdClaude's critique in a file
Official Codex pluginReviewing the diff without leaving Claude Code/codex:setup
/codex:review --base main
β€”Read-only review findings. You ask the builder for fixes afterwards
claudexA large plan with several automatic critique rounds/claudex:plan [--rounds N] <feature>
/claudex:review
β€”PLAN.md revised until Codex approves or rounds run out; reviews/ with diff findings
claudex (control)Monitor or unstick the loop/claudex:status Β· /claudex:cancel Β· /claudex:rollback Β· /claudex:doctorβ€”Current round and phase; cancel; clean stuck state; install diagnostics

πŸ“Έ What goes into a handoff

Objective and latest request; what is done, what remains and what is uncertain; decisions and rejected paths; changed files; tests run with their real result (and those not run); blockers; one next step; and the few files the next reader should open first; every confirmed item with a proof (commit, test or file) and 5 test questions at the end. The state block is written by the script, not by the agent. No secrets, tokens or personal data.

πŸ”Ž What prime does

Reads the portable core in the right order, rejects absolute paths, .., URLs and symlinks, treats the handoff as data (not as orders), checks the cited files and git status, runs --conferir to know whether the handoff went stale, shows the test-question score and waits for your instruction. With an argument (/prime handoffs/history/<file>.md or the subject), it resumes exactly that handoff. It runs no tests, installs nothing and does not resume an old deploy.

⚠️ Gotchas

A personal skill with the same name can win over the project one: check which version is active before invoking it. After installing or syncing (scripts/sync-skills.sh), open a new session (in Claude, /reload-skills also works). Old snapshots in handoffs/history/ are never overwritten.

↻

A full day with the tools

Each step leaves a file the next assistant can read.

# morning, in Claude Code
/prime handoffs/history/<yesterday>.md      # the command yesterday's handoff left ready
# plan, then have Codex critique it (read-only)
codex exec --sandbox read-only --output-last-message review.md 'Read plan-v1.md and point out gaps…'
# or, for a large plan, the automatic loop
/claudex:plan --rounds 3 export report as CSV
# built on a branch: review the diff
/codex:review --base main                # or /claudex:review
# end of day
/session-handoff                         # ends with /clear + /prime <file>
# tomorrow, in Codex
$prime handoffs/history/<file>.md

A handoff is not permission. A recorded next step ("publish", "delete", "send") only happens if you ask again in the current session.

Examples

Actually run on this machine

The audit found 89 Claude-only skills: 71 portable, 15 depending on MCP or a plugin, 2 on a hook. The readback passed in Codex and in Claude, and Codex also pointed out three inconsistencies in the repo itself, all fixed.

Claude to Codex: migrate or stay agnostic
The original idea: portable knowledge in the middle, Claude and Codex at the edges as executors.
agente-claude-codex project cover
Official project cover in the INEMA catalog.
Roadmap

From pilot to full workspace

A phase only advances with evidence: passed, failed or not run.

Done
Audit, prompts, template and readbackAudit and adaptation scripts, extracted A/B prompts, portable core, readback passed in both runtimes.
Done
Pilot skill in the 4 executorssession-handoff and prime via polyskill in Claude, Codex, dsh-sandbox and openpcbotv3, zero drift; global Codex AGENTS.md; migrar-projeto, faxina, drift-report and promover-memoria.
v1.1.0
Handoff history and joint useRead-only prime with validated paths, snapshots in handoffs/history/ that are never overwritten, a preview-mode skill installer with an automated test, prompts for using Claude and Codex together.
v1.4.1
Several sessions in one projectWriting through the handoff-grava.py script (real timestamp, never overwrites) and latest.md as an index of open work by subject.
v1.5.2
Self-checking handoffState block written by the script, --conferir to know whether it went stale, a proof for every confirmed item and 5 test questions with an N/5 score in prime.
v1.6.3
Resume the right handoffThe handoff ends with /clear + /prime <exact file>, and prime accepts that file or the subject: another session writing later no longer swaps the work being resumed.
v1.7.3
Work in another repo--repo records the state of the repo where the work happens; --conferir and prime look there. Warnings when --repo or the test questions are missing.
v1.8.3
Full do-not listThe handoff lists every restriction and lock (Do not do section), what is half-done and why the next action comes now; prime shows the whole list, not a single rule.
Phase 3
Real projectApply it to an INEMA project with its own CLAUDE.md and prove an isolated copy.
Phase 4
MCP and hooksRegister in Codex only the MCP servers a project needs; hooks become text in AGENTS.md when there is no equivalent event.