claude-codex-sessions
Bring your Codex CLI sessions into Claude Code.
claude-codex-sessions is a Claude Code plugin (and a command-line tool) that imports your Codex CLI sessions for the current repository into Claude Code. Run /codex-sessions:import, then use /resume (or claude --resume) to browse the imported [codex] … conversations and press Enter to continue one.
Features
No model call, no tokens. The import runs in a Claude Code hook and prints its report directly. Tokens are only spent once you resume a session and start typing, just like any other conversation.
No duplicates, ever. A session whose content hasn’t changed since its last import is skipped. A session that changed gets a new copy with the next suffix: Title, Title (1), Title (2)…. Existing files are never overwritten.
Only this repository. Scoping works like /resume: the current git worktree by default, or --worktrees for all worktrees of the repo.
Reads Codex’s own rollout JSONL files directly, read-only. No database, no CLI call, no network access.
Prerequisites
Python 3.10+
Installation
As a Claude Code plugin
claude plugin marketplace add barseghyanartur/claude-sessions-importer
claude plugin install codex-sessions@barseghyanarturOr inside a Claude Code session:
/plugin marketplace add barseghyanartur/claude-sessions-importer
/plugin install codex-sessions@barseghyanarturUpdate later with claude plugin update codex-sessions@barseghyanartur, or turn on auto-update for the marketplace under Marketplaces in /plugin.
The plugin runs the code bundled in the plugin itself, so it does not need the PyPI package. It needs a Python >= 3.10 on PATH (python3, python3.1x) or uv. Note that /usr/bin/python3 on macOS is 3.9. brew install python or uv python install 3.12 fixes that, or set CCS_PYTHON=/path/to/python.
As a command-line tool
uv tool install claude-codex-sessions # or: pipx install claude-codex-sessions
uvx claude-codex-sessions list # one-off run without installingUsage in Claude Code
/codex-sessions:import # sessions of the current worktree
/codex-sessions:import --worktrees # every worktree of the repository
/codex-sessions:import --dry-run # show what would happen
/codex-sessions:import --with-tool-output # include (truncated) tool output
/resume # pick a "[codex] …" sessionExample report:
Codex → Claude Code import · git worktree /Users/me/repos/brrn
into ~/.claude/projects/-Users-me-repos-brrn
imported [codex] I want to create a local version of English <-> Armenian dictionary
1 imported
Open them with /resume — titles start with "[codex]".What an imported conversation contains
One transcript per Codex session, in Claude Code’s own session folder for this project (~/.claude/projects/<project>/<uuid>.jsonl).
User messages and assistant replies as text. Each tool call becomes one line (→ exec_command: `pytest -x`), and its output is left out unless you pass --with-tool-output. Reasoning content is left out, same as Claude Code’s own thinking blocks.
A first line saying which Codex session it came from. Claude reads this when you resume, so it knows the context.
A title, taken from Codex’s own session index when it has one, otherwise the first line of your first message.
Known gap: Codex injects some context into the conversation as plain, untagged text (an AGENTS.md instructions header, IDE “Active file” context, “Files mentioned by the user” lists). Only content Codex wraps in a recognised <tag>…</tag> block is filtered out as synthetic; the rest is imported verbatim, same as a real message. Sessions and tool calls that Codex tracks only in its own internal SQLite state (archived status, for one) aren’t visible here — only what’s in the rollout files.
How duplicates are prevented
The Claude session id is uuid5(Codex session id + hash of the converted content). Importing unchanged content maps to a file that already exists, so it is skipped. The first line of each imported file records the Codex session id, content hash and suffix, so changed content gets the next free suffix (the highest existing one + 1). New files are written under a temporary name and hard-linked into place, which can’t overwrite an existing file. Continuing an imported conversation in Claude doesn’t count as a change: only the Codex side is compared.
Claude Code’s transcript format is internal and may change between Claude Code versions. The importer writes only a minimal, stable subset of it.
Command line
The same package works in the terminal:
claude-codex-sessions import --dry-run # same as /codex-sessions:import
claude-codex-sessions import --worktrees
claude-codex-sessions list # sessions in scope, newest first
claude-codex-sessions list --all --format json
claude-codex-sessions doctor # environment + sessions reportScoping
Mode |
Flag |
Sessions whose directory is… |
/resume equivalent |
|---|---|---|---|
worktree |
(default) |
inside the current git worktree (its top-level directory or below). Outside git: the current directory or below |
default view |
repo |
--worktrees |
inside any worktree of the repository |
Ctrl+W |
all |
--all (list only) |
anywhere |
Ctrl+A |
Configuration
Variable |
Purpose |
|---|---|
CODEX_HOME |
Codex’s own config/data directory. Default: ~/.codex. Sessions are read from $CODEX_HOME/sessions/**/rollout-*.jsonl |
CCS_PYTHON |
Interpreter for the plugin launcher (scripts/codex-sessions) |
Every command also accepts --codex-home PATH.
How it works
Codex keeps one JSONL “rollout” file per session under $CODEX_HOME/sessions/<year>/<month>/<day>/rollout-<timestamp>-<id>.jsonl, plus a best-effort session_index.jsonl with titles for some of them. There is no database to open and no CLI export to fall back on — the rollout files are read directly, read-only. See docs/design.md for the full format notes.
Development
make install # uv sync (creates .venv with dev tools)
make test # pytest (tests live in src/claude_codex_sessions/tests)
make check # ruff + mypy --strict + pytest + manifest validation
make run ARGS="list --all"
make dev # claude --plugin-dir . (live plugin; /reload-plugins after edits)
make install-local / make uninstall-localTroubleshooting
If /codex-sessions:import makes Claude answer instead of printing a report, the hook didn’t run. Check the Python requirement above and run claude-codex-sessions doctor, or sh ~/.claude/plugins/…/scripts/codex-sessions doctor. It shows the Python in use, the Codex home in use, the rollout file count and the scope roots for the current directory.
License
MIT
Support
For security issues contact me at the e-mail given in the Author section.
For overall issues, go to GitHub.
1 maintainer
Metadata
1 maintainer
Release files for claude-codex-sessions 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| claude_codex_sessions-0.1.0.tar.gz | 31.6 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| claude_codex_sessions-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 73.0 kB
Release files / claude_codex_sessions-0.1.0.tar.gz
| Download URL | claude_codex_sessions-0.1.0.tar.gz |
|---|---|
| Size | 31.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
78aa784ef071766d1d59fd049543117e692f48e0b59473f40b367233ea236050
|
|
BLAKE2b-256 checksum How to use checksums |
4b4e290106e625214d7e6cc6d04ef82df4a2f385ec619779b09b4f383a7ada60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.11
|
Release files / claude_codex_sessions-0.1.0-py3-none-any.whl
| Download URL | claude_codex_sessions-0.1.0-py3-none-any.whl |
|---|---|
| Size | 41.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
44b86e92c5de6cac2c3ebb0432a6391d1cf792853202f044835cafc664093b95
|
|
BLAKE2b-256 checksum How to use checksums |
911a80a5dbf38a18b91a393110aeea784ee34934ac612fb60c6ad9fe0e55f758
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.11
|
Security for claude-codex-sessions 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
