Claude Converter

A zero-dependency Python module for inspecting and converting coding-agent session files (.jsonl) — Claude Code, Codex, and Pi — into the messages format expected by Hugging Face Transformers.

Each of these tools stores its session history as a JSONL file on disk, one JSON record per line: user prompts, assistant responses, tool calls, tool results, and extended thinking/reasoning blocks. This module parses each tool's format and flattens it into the same simple [{"role": ..., "content": ...}] list that tokenizer.apply_chat_template() consumes directly — so downstream code doesn't need to know or care which tool produced the session.

Why this exists

The conversion pipeline has two stages that are often conflated:

Session JSONL (Claude Code / Codex / Pi)  →  [claude_converter]  →  messages[]  →  apply_chat_template()  →  tokens
                                                 (this module)                        (transformers handles this)

apply_chat_template() handles stage 2 (turning a messages list into model-specific token sequences), but it knows nothing about any of these tools' JSONL formats. This module handles stage 1, for all three.

Installation

uv pip install claude-converter

Quick start

The unified Converter class is the recommended entry point. Pick the tool with the converter argument ("claude-code" is the default) and every method behaves the same regardless of which tool produced the file.

Claude Code

from claude_converter import Converter
from huggingface_hub import hf_hub_download

converter = Converter()

hf_hub_download(repo_id="armand0e/claude-fable-5-claude-code",
        filename="06ec42c3-2184-40c5-b0ee-98c3235b4c4c.jsonl",
        repo_type="dataset",
        local_dir=".")

converter.inspect_session("06ec42c3-2184-40c5-b0ee-98c3235b4c4c.jsonl")

Codex

from claude_converter import Converter
from huggingface_hub import hf_hub_download

converter = Converter(converter="codex")

hf_hub_download(repo_id="AletheiaResearch/GPT-5.5-Codex",
        filename="rollout-2026-06-22T08-33-58-019eee77-052d-7530-af09-17a140e08123.jsonl",
        repo_type="dataset",
        local_dir=".")

converter.inspect_session("rollout-2026-06-22T08-33-58-019eee77-052d-7530-af09-17a140e08123.jsonl")

Pi

from claude_converter import Converter
from huggingface_hub import hf_hub_download

converter = Converter(converter="pi")

hf_hub_download(repo_id="armand0e/claude-opus-4.8-pi-traces",
        filename="2026-06-07T00-07-46-038Z_019e9f68-3075-7136-b429-c6b2c871ed67.jsonl",
        repo_type="dataset",
        local_dir=".")

converter.inspect_session("2026-06-07T00-07-46-038Z_019e9f68-3075-7136-b429-c6b2c871ed67.jsonl")

huggingface_hub is only needed to pull the example files above — it is not a dependency of claude_converter itself.

To go straight to a messages list ready for apply_chat_template():

from claude_converter import Converter

converter = Converter(converter="codex")  # or "claude-code" / "pi"
messages  = converter.session_to_messages("session.jsonl")

Legacy API (still supported)

If you only ever work with Claude Code sessions and don't need the multi-tool dispatch, the original module-level functions are still available and unchanged — nothing here was touched or deprecated: