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

markdown = render_session_markdown(session, use_utc=True)
print(markdown[:200])

Parse multiple sessions and export artifacts:

from pathlib import Path

from session_parser import ParseInput, export_many, parse_many

results = parse_many(
    [
        ParseInput(provider="claude-code", path=Path("/path/to/claude/session.jsonl")),
        ParseInput(provider="codex-cli", path=Path("/path/to/codex/session.jsonl")),
        ParseInput(provider="gemini-cli", path=Path("/path/to/gemini/session.json")),
    ]
)

exported = export_many(results, Path("/tmp/session-parser-output"), use_utc=True)
for item in exported:
    print(item.output_dir)

Parse a project directory:

from pathlib import Path

from session_parser import parse_project

sessions = parse_project(
    "claude-code",
    Path("/path/to/project"),
)

for session in sessions:
    print(session.sessionId, session.slug)

Public API

Top-level imports exposed from session_parser:

• parse_session_file(...)
• parse_project(...)
• parse_many(...)
• render_session_markdown(...)
• export_session(...)
• export_many(...)
• derive_status(...)
• extract_last_shell_command(...)
• status_to_dict(...)

Output Layout

Default export artifacts:

• session-data.json
• session.md

Example output tree:

/tmp/session-parser-output/
  claude-code/
    claude-basic-1/
      session-data.json
      session.md
  codex-cli/
    codex-basic-1/
      session-data.json
      session.md

Development

Recommended local setup:

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
git config core.hooksPath .githooks

Default checks:

./scripts/check.sh

If you change parser behavior, verify:

• SessionData contract remains stable
• JSON / Markdown goldens still match intent
• reference compare should be updated or rerun when parity work is involved

Reference compare helper:

PYTHONPATH=src python3 scripts/export_reference_compare.py \
  --reference-repo /path/to/reference-go-repo \
  --output-root /tmp/session-parser-compare/run-001 \
  --codex-dir ~/.codex/sessions/2026/03/04 \
  --claude-project-dir ~/.claude/projects/-my-project

Repository Layout

src/session_parser/
  api.py
  core/
  emitters/
  monitoring/
  providers/
  schema/
tests/
  fixtures/
  goldens/
  integration/
  providers/
docs/
scripts/

Documentation

• 使用说明
• 项目现状与一期边界
• SessionData contract
• TDD 工作方式
• 项目约束
• 监控/状态快照
• 二期 backlog
• 贡献说明

Agent Context

If an AI coding agent is working in this repository, start with AGENTS.md.