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:

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

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

Codex

Pi

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():

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:

This is exactly the API that existed before Converter was introduced. Use
it if you want a direct import with no dispatch layer in between; use
Converter if you want one interface…