ai-session-bridge _{(aka claude2codex / codex2claude)}

v0.3 — imports both Claude Code JSONL sessions and Claude Chat data exports, registers sessions in modern Codex, and renders imported messages in the Codex app UI.

Bridge your AI coding sessions between OpenAI Codex CLI and Anthropic Claude Code CLI.

Start a task in one tool, continue in the other. Both store sessions as JSONL — this tool converts between their formats bidirectionally. Searching for a claude codex bridge, claude2codex converter, or a way to transfer a Claude Code session to Codex (or back)? This is it.

English | Русский

English

The problem

You're deep into a coding session with Codex CLI when you realize Claude Code would handle the next part better. Or vice versa. But your conversation history, tool call results, and context are locked in one tool's proprietary JSONL format.

The solution

ai-session-bridge reads session files from either tool, maps messages and tool calls 1:1, and writes a valid session file for the other tool. Then you resume where you left off.

How it works

Codex CLI (.codex/sessions/)          Claude Code (.claude/projects/)
┌──────────────────────┐              ┌──────────────────────┐
│ response_item (user) │  ──bridge──> │ type: "user"         │
│ response_item (asst) │  ──bridge──> │ type: "assistant"    │
│ function_call        │  ──bridge──> │ tool_use             │
│ function_call_output │  ──bridge──> │ tool_result          │
│ session_meta         │  ──bridge──> │ (embedded metadata)  │
│ event_msg            │  <──bridge── │ type: "progress"     │
└──────────────────────┘              └──────────────────────┘

Quick start

git clone https://github.com/bakhtiersizhaev/ai-session-bridge.git
cd ai-session-bridge
npm install

Usage

# See all your sessions from both tools
npx tsx src/cli.ts list

# Preview what's in a session before bridging
npx tsx src/cli.ts preview 019ced67

# Bridge Codex session -> Claude Code (last 5 user turns)
npx tsx src/cli.ts codex2claude 019ced67-e597-72d2-9e6d-657e520103b0 --tail 5

# Bridge Claude Code session -> Codex
npx tsx src/cli.ts claude2codex 70f732ba-5279-4674-a7a8-c99cc4771e33

# Import every conversation from a Claude Chat data export
npx tsx src/cli.ts import-claude-chat ~/Downloads/claude-export

# Inspect an archive without writing anything
npx tsx src/cli.ts import-claude-chat ~/Downloads/claude-export --dry-run --json

# Auto-detect format and bridge
npx tsx src/cli.ts auto /path/to/session.jsonl

# Dry run — see stats without writing
npx tsx src/cli.ts auto 019ced67 --dry-run

# JSON output for AI agents
npx tsx src/cli.ts list --json

Features

• Bidirectional: Codex CLI <-> Claude Code, both directions
• Auto-detect: Reads the JSONL and figures out which format it is
• Session discovery: Finds sessions in ~/.codex/sessions/ and ~/.claude/projects/ automatically
• Partial ID: Type 8+ characters of a session UUID instead of the full thing
• Message preview: See the first messages before converting
• Tool name mapping: exec_command <-> Bash, read_file <-> Read, etc.
• Tail trimming: --tail N keeps only the last N user turns — essential for large sessions that overflow context
• History registration: Automatically registers converted sessions in Claude Code's history.jsonl
• Modern Codex registration: Registers sessions in both session_index.jsonl and state_5.sqlite (Node.js 22.5+), so they appear in the app sidebar and remain writable after resume
• Claude Chat archives: Imports every conversation from the official Claude conversations.json data export as a separate Codex session
• Visible app history: Emits user_message and agent_message UI events, so imported text is rendered in Codex instead of being model-only context
• Responses API-safe tools: Normalizes imported tool names to ^[a-zA-Z0-9_-]+$ and prevents invalid input[].name errors
• Correct project placement: Converted sessions go into the right ~/.claude/projects/ subdirectory
• Converted session tracking: Bridged sessions are marked [bridged] in list output
• AI agent friendly: --json flag on every command for machine-readable output

Tool name mapping

Verified end-to-end

Both directions were tested with a "secret codeword" round-trip on real CLIs (Codex CLI 0.126, Claude Code 2.1):

1. Tell tool A a codeword → bridge the session → resume in tool B → ask for the codeword → tool B answers correctly.
2. Send a second message after resume → new turns append to the bridged session file (Codex side requires the session-index registration this tool performs automatically).

Session storage paths

Importing a Claude Chat data export

Point import-claude-chat at either the extracted export directory or its
conversations.json file. Each Claude conversation becomes a separate Codex
session with a [Claude Chat] title. Text, available attachment extracts, tool
calls, and tool results are preserved; hidden thinking blocks are skipped.

Some Claude exports contain conversation metadata but empty message bodies.
The dry-run report shows withText and withoutText counts, and textless
conversations receive an explicit placeholder instead of pretending that their
content was recovered.

What's preserved / what's lost

Requirements

• Node.js 18+
• tsx (installed as devDependency)

Русский

Проблема

Вы в разгаре сессии в Codex CLI и понимаете, что Claude Code лучше справится со следующей частью задачи. Или наоборот. Но вся история диалога, результаты вызовов инструментов и контекст заперты в проприетарном JSONL-формате одного инструмента.

Решение

ai-session-bridge читает файл сессии любого из инструментов, маппит сообщения и tool calls 1:1, и записывает валидный файл сессии для другого. Дальше вы продолжаете с того места, где остановились.

Быстрый старт

git clone https://github.com/bakhtiersizhaev/ai-session-bridge.git
cd ai-session-bridge
npm install

Использование

# Все сессии из обоих инструментов
npx tsx src/cli.ts list

# Превью сессии перед конвертацией
npx tsx src/cli.ts preview 019ced67

# Codex -> Claude Code (последние 5 тернов)
npx tsx src/cli.ts codex2claude 019ced67-e597-72d2-9e6d-657e520103b0 --tail 5

# Claude Code -> Codex
npx tsx src/cli.ts claude2codex 70f732ba-5279-4674-a7a8-c99cc4771e33

# Импорт всех разговоров из экспорта Claude Chat
npx tsx src/cli.ts import-claude-chat ~/Downloads/claude-export

# Предварительная проверка без записи
npx tsx src/cli.ts import-claude-chat ~/Downloads/claude-export --dry-run --json

# Авто-определение формата
npx tsx src/cli.ts auto /path/to/session.jsonl

# Пробный прогон (без записи файла)
npx tsx src/cli.ts auto 019ced67 --dry-run

Что сохраняется при конвертации

• Текстовые сообщения user/assistant — 1:1
• Tool calls и результаты — 1:1 с переименованием инструментов
• Progress events — маппятся
• Метаданные (session_meta, turn_context, file-history) — частично, помечаются как lossy
• История отображается в интерфейсе Codex благодаря событиям user_message / agent_message
• Сессии регистрируются в современном state_5.sqlite и появляются в боковой панели
• Имена инструментов очищаются до формата Responses API, поэтому импорт не вызывает ошибку input[].name

Экспорт Claude Chat

Команда import-claude-chat принимает папку распакованного архива или файл
conversations.json и создаёт отдельную сессию Codex для каждого разговора.
Если Claude оставил в экспорте только метаданные без текста, это явно отражается
в отчёте withText / withoutText; отсутствующий текст не подменяется выдуманным.

License

MIT