Start in Codex.
Finish in Claude Code.

STEP 01

Prepare both clients.

You need Git, Node.js 22 or later, npm, and both Codex and Claude Code. Install the two Context Docs skills separately in each client by following the installation guide; installing them in one client does not install them in the other.

The app is the existing Reading Queue example, also used in the full workflow walkthrough. Everything here runs on your machine. The API tests need no running server, cloud account or deployment.

STEP 02

Create a fresh practice checkout.

Clone into a new folder so earlier attempts cannot leak in, then branch from the starter tag. The starter supports adding, reading, filtering and deleting links; export is not implemented yet.

git clone https://github.com/jaredchu/context-docs-example-reading-queue.git reading-queue-codex-claude
cd reading-queue-codex-claude
git switch -c try-codex-claude switching-start
npm ci
npm test

Note the baseline test result as you observe it. If npm test fails before any change, resolve that first: a handoff over a broken baseline is hard to judge.

STEP 03

Confirm both clients reuse the setup.

The starter already has a context entry point at docs/project-context.md, a maintenance rule in AGENTS.md, and a CLAUDE.md that imports it with @AGENTS.md. Adoption should reuse that setup in each client, not add a second layout.

Run the two prompts one at a time: first open the folder in Codex, then close it and open the folder in Claude Code. Codex reads AGENTS.md; Claude Code reads CLAUDE.md, which imports it. A file on disk does not prove a client loaded it, so ask each one.

Prompt: Adopt in Codex

$adopt-context-docs Inspect and reuse this project's existing context documents and maintenance rule. Preserve the current layout, decisions and evidence. Keep optional logging off. Report which project instruction files you loaded in this session and any uncertainty. Do not change global settings, commit or deploy.

Prompt: Adopt in Claude Code

/adopt-context-docs Inspect and reuse this project's existing context documents and maintenance rule. Preserve the current layout, decisions and evidence. Keep optional logging off. Report which project instruction files you loaded in this session and any uncertainty. Do not change global settings, commit or deploy.

Expected result: Each client reports the existing entry point and rule, with loading stated separately from configuration.

Check: Run git status --short and review any adoption diff: no duplicate layout and no logging setup. Close both sessions before continuing.

STEP 04

Codex: build and test the API half.

Start a new Codex session in the practice folder. This prompt names the exact backend scope and tells Codex where to stop.

Prompt: Build the export API in Codex

Read this project's context and the existing export requirement. Implement only the backend half: a GET /api/export endpoint and its API tests.

Return {"schema_version":1,"items":[...]} where each item has only title, url and read, covering the entire active queue of the requesting browser regardless of any UI filter. Preserve queue isolation and expiry. Include no identifiers, cookie values or database metadata, and do not change any data. An empty queue returns {"schema_version":1,"items":[]}. If the requirement's wording about empty output is ambiguous, this task approves that versioned empty shape as an exercise clarification; do not rewrite the requirement or its authority.

Keep the reason: the export is a backup of the whole queue, not a copy of the current view. Make no schema or cloud changes. Stop before the browser Export JSON button.

Run npm test. Then record in the existing docs/project-context.md, and in docs/decisions.md only where appropriate, what is complete, which checks actually ran, and that browser integration is pending. Do not deploy, commit or change global settings.

About the empty shape. The switching-start requirement explicitly uses {"schema_version":1,"items":[]} for an empty queue. This teaching clarification preserves the versioned object shape; it is not a quotation of a historical owner request.

Expected result: GET /api/export and its API tests exist. The existing context records the API as complete with the checks that actually ran, and the browser button as pending.

Check: Inspect the code and Markdown diffs. No browser button, schema change or deployment.

STEP 05

Stop Codex and review the handoff.

Exit Codex before Claude Code starts. Keep one writer: two agents editing the same files at once can overwrite each other, and nothing here locks or syncs them.

git status --short
git diff

Review the code and the context changes together. A useful handoff says what is complete, what is pending and why, which checks ran, what they do not cover, and the next step. It might read something like this:

## Current work
JSON export API: GET /api/export implemented with API tests.
Checks run: npm test (<your actual result>).
Browser Export JSON button and download: pending, not started.

## Decision
Export the whole active queue, not the filtered view: it is a backup.
Empty queue returns {"schema_version":1,"items":[]} (exercise clarification).

## Limits
API tests do not cover the button, the download or the error message.

## Next step
Add the Export JSON button using /api/export. On failure, show an
error and download nothing. Verify in a browser.

Your files, wording and layout will differ. Judge the content, not the exact text.

Same checkout: Claude Code sees the saved, uncommitted files directly; you do not need to commit. Another checkout or machine: move the code and context changes together with a transfer you are authorized to make, such as a commit pushed to your own branch, and confirm they arrived. Ignored or private files do not travel with Git; use your own private transfer for them.

Chat history, Codex memories and other runtime state stay with Codex. Only the project files carry the work across.

STEP 06

Claude Code: continue from the files.

Open the same folder in a new Claude Code session. The prompt is deliberately generic: it does not mention the export, the endpoint or the button.

Prompt: Continue in Claude Code

Read this project's context entry point and the relevant sources it links. Identify what is complete, what is pending and why. Verify those claims against the current files, then continue with the next authorized task within the recorded scope. Run the available checks and report what actually ran and what passed. Preserve recorded decisions and blockers, and update the existing notes. Do not deploy, commit or change global settings.

Expected result: From the files, Claude Code reports that the export API is complete and the browser button is pending, keeps the whole-queue reason and the versioned empty shape, and names what the API tests do not cover. It then adds an Export JSON button that downloads from /api/export, shows success or a clear error, and downloads nothing when the request fails. It runs npm test and updates the existing notes.

Check: If it invents scope that is not in the files, or calls browser behavior verified because the API tests passed, record that as a miss.

STEP 07

Verify the result yourself.

npm test checks the API. It does not exercise the button or the download. Check those in a browser:

npm test
npm run db:local
npm run dev

Open the printed localhost URL. Add two links, mark one read, select Unread and export: the file should contain both links. Export an empty queue and check for the versioned empty shape. Then make the request fail, for example by stopping the dev server before you click: you should see an error and get no file.

Finally, read the context diff. Does it record the browser checks you actually ran, separately from the API tests, and leave an honest next step? Do not deploy.

STEP 08

Know what this shows.

A bounded native check observed this direction using file inspection/editing sessions, followed by separate coordinator API and browser checks. It did not run every walkthrough prompt unchanged. The case record retains the exact scope and command-boundary deviations.

This walkthrough shows one way to hand work between clients: the saved files carry scope, reasons, status and limits, and the receiving agent checks them before continuing. There is no sync, file locking or exclusive ownership; agree on one writer at a time.

It is an authored walkthrough, not a study. Any observed checks of it are described, with their scope and limits, in the switching examples record. It does not establish general reliability, dependable instruction loading, or time or token savings compared with other ways of working.

Try the reverse: Claude Code to Codex

Back to all examples