Streaming parser for Claude Code session JSONL files

Pulls structured token-usage and chat-event data out of the .jsonl files Claude Code writes to ~/.claude/projects/<encoded-path>/<session-id>.jsonl. Streaming, read-only, no network, no subprocess, no writes.

Install

[dependencies]
claude-session-parser = "0.2"

Usage

use std::path::Path;
use claude_session_parser::{parse_jsonl_entries, parse_chat_events, reduce_session};

let path = Path::new("/path/to/session.jsonl");

// Usage / billing view: one UsageEntry per assistant turn
let parsed = parse_jsonl_entries(path)?;
let summary = reduce_session(&parsed.entries, "claude-opus-4-7", "session-id");
if let Some(s) = summary {
    println!(
        "turns={} cost=${:.4} cache_hit={:.1}%",
        s.message_count, s.estimated_cost_usd, s.cache_hit_pct
    );
}

// Chat view: flat, timestamp-ordered event stream
let events = parse_chat_events(path)?;
for evt in events {
    println!("{:?}", evt);
}
# Ok::<(), std::io::Error>(())

API

Trust surface

"If a tool uses this crate to read my ~/.claude/ JSONL files, what does it touch on my machine?"

The full surface is the functions above plus the data types they return. Every file read is bounded (MAX_JSONL_BYTES = 200 MB), streaming (BufReader::lines(), O(1) memory per line), and read-only. No network. No subprocess. No filesystem writes. ~2600 lines of source.

JSONL format notes (load-bearing for correctness)

• Split content blocks. Claude Code 2.1+ writes one JSONL row per content block of an assistant message (thinking, then text, then each tool_use), all sharing the same message.id. The usage parser dedupes billing fields by id (they repeat identically) but unions content fields across rows; the chat parser keys dedup on (message_id + serialized_content). Dedup by id alone silently drops every block after the first.
• <synthetic> model rows are skipped — internal routing entries, not real LLM turns.
• Tiered cache / fast mode / web search. Cache writes split into 5-minute (1.25× input) and 1-hour (2× input) tiers via usage.cache_creation.ephemeral_{5m,1h}_input_tokens; fast mode (usage.speed == "fast") multiplies the token line (Opus 4.6/4.7 = 6×, 4.8/5/5.5 = 2×); usage.server_tool_use.web_search_requests bills $0.01 flat each. cost_for_entry accounts for all three — pricing only input/output/cache_read undercounts 1h-cache-heavy turns by ~38%.
• Hook executions are parsed from both the legacy attachment format and the v2.1.119+ system.subtype = "*_hook_summary" format.

Scope

• No file watching, no incremental parsing, no cache layer. Layer that on top with e.g. file-parse-cache.
• No I/O beyond reading the JSONL file you point it at.
• No async runtime, no GUI coupling, no build-system coupling.

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}