✨ What's New

Newest first.

• 🧷 A conversation you carried on in Claude is left alone — --force treated "Claude replayed the history into the file" and "you answered in it" as the same kind of change and overwrote both, which cost a message. It now tells them apart and refuses the second, naming what would have been deleted and counting only lines somebody typed. Continuing an import also makes Claude fork it and repoint the record at a session of its own; those records are recognised as no longer ours, left alone rather than duplicated, and searched for messages sent there. (#9, #10)
• 🛑 A dry run stays dry — npm run import -- --dry-run used to import for real. npm owns --dry-run and --force, parses them as its own config and passes an empty argv on, so the flag never arrived and the write path ran. It now detects the swallowed flag and refuses; npm run import:dry has it baked in. (#6)
• 🧠 Memory citations out of the reply — when Codex answers from its memory files it appends an <oai-mem-citation> block, which Codex Desktop parses back out and never shows. Imports used to end an answer with raw markup; the citation is now a readable metadata line after the reply. (#3)
• 🏷️ Titles the way Codex titles them — Codex names the threads you start from the app and lists that name, not your opening message. Imports read those names from ~/.codex/session_index.jsonl, so a conversation is called the same thing on both sides. (#2)
• 🍎 macOS support — the Claude Desktop session-record store resolves per platform now instead of assuming the Windows layout, and project grouping follows current Codex Desktop builds, which dropped the thread→project map in favour of local-projects root paths. (#1)

Contents

On this page — Quick start · How it works · Features · Choosing conversations · Requirements · Safety · Limitations

Reference — CLI · Conversion · Formats

Quick start

git clone https://github.com/Agentryx-ai/codex-to-claude
cd codex-to-claude
node --experimental-strip-types --experimental-sqlite src/cli.ts list

$ codex-to-claude list
20 conversation(s), 20 after refinements.  [vscode:19  cli:1]

By project:
    3  Agentryx
    2  ReTalk
    2  Itineva
    1  ModuBoza
    1  (no project)
    ...

$ codex-to-claude import --dry-run          # writes nothing
$ codex-to-claude import --title-prefix "[Codex] "

Restart Claude Desktop. The conversations are in the sidebar under the same projects, and you can open and continue them.

Flags belong on node src/cli.ts, not on npm run — see CLI.

How it works

Claude Desktop keeps a conversation in two places, and needs both to show it:

Writing only a transcript leaves it invisible, so this writes both.

~/.codex/sessions/**/rollout-*.jsonl
        │
        ├─ select    what Codex Desktop lists
        ├─ convert   rollout items to transcript lines
        ├─ validate  replay invariants
        │
        ├──► ~/.claude/projects/<enc-cwd>/<id>.jsonl
        └──► claude-code-sessions/.../local_<uuid>.json

Features

• 📋 The same list you already see — selection replicates the Codex Desktop sidebar, including its project grouping, so you pick from what you recognise
• 🔁 Whole conversations, not just text — messages, tool calls, tool results, images and sub-agent reports
• 🏷️ Titles that read like titles — Codex's own conversation names, and its injected boilerplate marked as metadata so it never becomes one
• 🧭 Registered, so Claude actually lists it — the session record is written alongside the transcript
• 🔐 Sandbox and approval mapped — Codex's two settings collapse into Claude's one permissionMode
• 📉 Long sessions still open — imports start from the context Codex compacted to; 39 MB of history became 6.5 MB across 20 conversations
• ✅ Validated before writing — every conversion is replay-checked, and one that would fail on resume is repaired or refused
• 🛟 Your edits win — a conversation you continued in Claude is skipped, not overwritten

Choosing conversations

Codex Desktop groups by project. Conversations without one appear only under Recents, and plenty of people never look at them, so membership is a filter:

list prints the per-project breakdown first. Further limits: --since-days, --max, --from, --to, --id. Full flag reference in CLI.

Requirements

Windows or macOS, and Node.js 22.6 or newer. No dependencies.

Every path resolves per platform: the Claude Desktop session-record store from %APPDATA%, ~/Library/Application Support or $XDG_CONFIG_HOME, and ~/.codex and ~/.claude from the home directory. Linux follows the same rules but has not been run there; --sessions-root and --claude-home override any of it.

Safety

This writes into another application's local data, so it stays cautious.

• It creates files and deletes none. The only records it rewrites are ones it wrote itself, and only with --force.
• --dry-run prints every target path and writes nothing.
• If you continued an imported conversation in Claude, the transcript changed since the import and it is skipped, with a note.
• --force overrides that for a transcript Claude only rewrote — opening a conversation makes it replay the history back into the file — and says what it overwrote. It stops at a transcript holding messages you sent after the import, naming the first one, and does not offer to override: the flag exists to get past replay duplicates, not to discard conversation.
• To undo an import, delete the transcripts and the local_*.json records it created. Both are listed in its output.
• Prefer running with Claude Desktop closed.

Limitations

• Built on undocumented internals of two proprietary desktop apps. They can change at any time.
• Tested on Windows 11 and macOS 26. Linux resolves the same way but has not been run there.
• Codex encrypts its compaction summaries, so an import shows where compaction happened but not what it said.
• Sub-agent threads arrive as messages, not as separate threads.
• Large rollouts are read whole. No streaming yet.

Documentation

Related

• openai/codex-plugin-cc, calling Codex from Claude Code
• inmzhang/transession, CLI session translation by session id
• Codex CLI /import, Claude into Codex

Development

npm test

Disclaimer

Unofficial, and not affiliated with OpenAI or Anthropic. "Codex" and "Claude" are trademarks of their respective owners. Back up anything you care about.

License

Apache 2.0, see LICENSE and NOTICE.

You can use, modify and ship this, including commercially. Keep the copyright notice and the NOTICE file, and say what you changed. The license does not grant rights to the project's name or marks.