jsonl-parser

Claude Code JSONL Parser Specification

File Location

Session logs are at ~/.claude/projects/{encoded-path}/*.jsonl where path encoding replaces / with - (e.g., /Users/jane/project becomes -Users-jane-project).

Additionally, ~/.claude/projects/{encoded-path}/sessions-index.json contains session metadata (summaries, message counts, timestamps).

Record Format

Each line is a JSON object with these common fields:

interface BaseRecord {
  type: "user" | "assistant" | "system" | "result";
  sessionId: string;
  timestamp: string;       // ISO-8601
  uuid: string;
  parentUuid: string | null;
  version?: string;
  cwd?: string;
  gitBranch?: string;
}

Assistant Records

Contain Claude's responses with text and tool_use blocks:

interface AssistantRecord extends BaseRecord {
  type: "assistant";
  message: {
    role: "assistant";
    content: ContentBlock[];
    usage?: {
      input_tokens: number;
      output_tokens: number;
      cache_creation_input_tokens?: number;
      cache_read_input_tokens?: number;
    };
  };
}

type ContentBlock =
  | { type: "text"; text: string }
  | { type: "tool_use"; id: string; name: string; input: Record<string, any> }
  | { type: "thinking"; thinking: string };

User Records

Contain user messages or tool results (when isMeta: true):

interface UserRecord extends BaseRecord {
  type: "user";
  message: {
    role: "user";
    content: string | ToolResultBlock[];
  };
  isMeta?: boolean; // true = internal tool result, false = real user message
  isCompactSummary?: boolean;
}

interface ToolResultBlock {
  type: "tool_result";
  tool_use_id: string; // links back to tool_use block's id
  content: string | ContentPart[];
  is_error?: boolean;
}

System Records

Session lifecycle events:

interface SystemRecord extends BaseRecord {
  type: "system";
  subtype?: "init" | "compact_boundary";
  compactMetadata?: {
    trigger: "auto" | "manual";
    preTokens: number;
  };
}