Skip to content

Claude Code Internals

Welcome to the comprehensive guide on Claude Code's internal structure and session data format.

What You'll Learn

This documentation covers:

  • Session Structure: How Claude Code organizes session data on disk
  • JSONL Format: The line-delimited JSON format used for message logs
  • Message Types: Understanding user, assistant, system, and tool messages
  • Subagents: How subagent sessions are structured
  • Data Analysis: How to parse and analyze session data using Zod types
  • Temp Files: Finding and understanding temporary log output files

Quick Start

Finding Session Data

Claude Code stores session data in:

~/.claude/projects/<project-name>/

Each session has a unique UUID:

~/.claude/projects/-home-admin--openclaw-workspace-pergola-fullstack/
├── b9f04a0c-72d2-47f4-ab33-66fef0e738b6.jsonl    # Main session log
├── b9f04a0c-72d2-47f4-ab33-66fef0e738b6/          # Session directory
│   └── subagents/                                  # Subagent logs
├── memory/                                         # Session memory

Reading JSONL Files

JSONL (JSON Lines) format - one JSON object per line:

# View first 10 messages
head -10 session.jsonl

# Parse with jq
cat session.jsonl | jq '.type' | sort | uniq -c

# Count messages
wc -l session.jsonl

Using Zod Types

TypeScript types for parsing session data:

import { parseClaudeMessage, AssistantMessageSchema } from '@claude-dashboard/claude-zod';

// Parse a single line
const message = parseClaudeMessage(jsonlLine);

// Validate with schema
const assistant = AssistantMessageSchema.parse(jsonData);

Key Concepts

1. Session UUIDs

Each session has a unique identifier (e.g., b9f04a0c-72d2-47f4-ab33-66fef0e738b6) that: - Names the JSONL file - Names the session directory - Links subagents to parent session

2. Message Types

Type Description
user User input, commands, tool results
assistant Claude's responses with tool calls
system System events (turn duration, errors)
permission-mode Session permission state
attachment Skills, context attachments

3. Tool Messages

Tools appear in two forms: - tool_use: Assistant requesting tool execution - tool_result: Tool execution result returned to conversation

4. Subagents

Subagents have their own: - JSONL log files (agent-<uuid>.jsonl) - Meta files (agent-<uuid>.meta.json) - Parent session reference

Finding Temporary Files

Claude Code writes temporary logs and outputs to /tmp. To find them:

# Find Claude-related temp files
find /tmp -name "*claude*" -o -name "*anthropic*" 2>/dev/null

# Find by process
lsof | grep claude

# Check recent temp files
ls -lt /tmp | head -20

See Finding Temp Files for detailed guidance.

Package Structure

The @claude-dashboard/claude-zod package provides:

packages/claude-zod/
├── src/
│   ├── index.ts                    # Main exports
│   ├── user-message.zod.ts         # User message types
│   ├── assistant-message.zod.ts    # Assistant message types
│   ├── system-message.zod.ts       # System message types
│   └── subagent-meta.zod.ts        # Subagent metadata
├── samples/                        # Sample JSON for type generation
└── package.json

Next Steps

Resources