Agent Session Parser

Agent Session Parser

Python library for parsing Claude Code, Codex CLI, and Gemini CLI session files into a shared `SessionData` schema.

这个仓库是一个独立的 Python 解析库，目标是把不同 provider 的原始会话文件稳定解析、批量导出，并提供可复用的库接口。它不是现有 Go CLI 的 Python 包装层，也不承担 watcher 或 provider 运行时能力。

Recommended GitHub repository name: `agent-session-parser`

Features

• Parse Claude Code, Codex CLI, and Gemini CLI session files.
• Normalize outputs into a shared SessionData contract.
• Export session-data.json and session.md.
• Support batch parsing and batch export.
• Provide derived status helpers for monitoring or snapshot use cases.
• Keep parser behavior protected by fixture, golden, integration, and contract tests.

Support Matrix

Provider	Input format	Typical input	Single session file	Project parse	Notes
claude-code	JSONL	session.jsonl, Claude project session directories	Yes	Yes	Includes internal session rebuild logic
codex-cli	JSONL	session.jsonl	Yes	No	Current focus is single-file session parsing
gemini-cli	JSON	session.json, Gemini chat/session directories	Yes	Yes	Supports multi-file project parsing

Scope

Current in scope:

• Stable parsing for Claude / Codex / Gemini
• Shared SessionData schema
• JSON / Markdown emitters
• Batch export and reference-compare tooling
• Monitoring-oriented derived status helpers

Current out of scope:

• watcher
• ExecAgentAndWatch
• provider install detection
• cloud sync / analytics / debug raw dumps
• new provider expansion

Install

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Quick Start

Parse one session file:

from pathlib import Path

from session_parser import parse_session_file, render_session_markdown

session = parse_session_file(
    "codex-cli",
    Path("/path/to/session.jsonl"),
)

print(session.sessionId)
print(session.provider.id)
print(len(session.exchanges))