# Claude Code Data Sources - Technical Reference
> **Last verified:** 2025-12-08
> **Claude Code version tested:** Latest (check for breaking changes)
## Overview
Claude Viewer reads conversation data from Claude Code's local storage. This document tracks the **unofficial but verified** file structure used by Claude Code CLI.
**WARNING:** Anthropic does NOT officially document the internal file structure. This is considered an implementation detail and may change without notice.
---
## Data Sources
### 1. History Index
```
~/.claude/history.jsonl
```
- **Purpose:** Quick index of all prompts sent to Claude
- **Format:** JSONL (one JSON object per line)
- **Content:** One line per user prompt (NOT per session)
- **Fields:** `display`, `timestamp`, `leaf`, `cwd`, `sessionId`
### 2. Full Conversation Transcripts
```
~/.claude/projects/{encoded-path}/*.jsonl
```
- **Purpose:** Complete conversation history with responses
- **Format:** JSONL (one JSON object per message)
- **Naming:**
- `{uuid}.jsonl` = Main session
- `agent-{uuid}.jsonl` = Subagent session
- **Path encoding:** `/Users/max/project` → `-Users-max-project`
---
## Message Schema (from projects/*.jsonl)
```javascript
{
"type": "user" | "assistant" | "tool_use" | "tool_result" | "summary",
"uuid": "unique-message-id",
"parentUuid": "parent-message-id",
"timestamp": "2025-12-08T10:30:00.000Z",
"sessionId": "session-uuid",
"cwd": "/absolute/path/to/project",
"gitBranch": "main",
"version": "1.0.x",
"isSidechain": false, // true for subagent messages
"isMeta": false, // true for system messages
"message": {
"role": "user" | "assistant",
"content": "..." | [...], // string or array of blocks
"model": "claude-sonnet-4-5-20250929",
"stop_reason": "end_turn" | "tool_use",
"usage": {
"input_tokens": 1234,
"output_tokens": 567,
"cache_creation_input_tokens": 890,
"cache_read_input_tokens": 0
}
}
}
```
---
## Known Behaviors
### Session Cleanup
- **Default:** Sessions older than 30 days are deleted
- **Setting:** `cleanupPeriodDays` in `~/.claude/settings.json`
- **Recommendation:** Set high value to preserve history
### Subagent Sessions
- Files named `agent-*.jsonl`
- Linked via `parentSessionId` and `agentId` fields
- `isSidechain: true` in messages
### Token Counting
- `input_tokens` = prompt tokens
- `output_tokens` = response tokens
- `cache_creation_input_tokens` = cached context
- `cache_read_input_tokens` = reused cache
---
## Verification Sources
### Official (Anthropic)
| Source | URL | Notes |
|--------|-----|-------|
| Claude Code Docs | https://code.claude.com/docs/en/overview | No internal file structure documented |
| Data Usage Policy | https://code.claude.com/docs/en/data-usage | Retention policies only |
| GitHub Repo | https://github.com/anthropics/claude-code | No schema documentation |
### Community (Monitor for updates)
| Source | Author | URL |
|--------|--------|-----|
| **Technical Guide** | @idsc2025 | https://idsc2025.substack.com/p/the-complete-technical-guide-to-claude |
| History Guide | Kent Gigger | https://kentgigger.com/posts/claude-code-conversation-history |
| ClaudeLog FAQ | ClaudeLog | https://claudelog.com/faqs/does-claude-code-store-my-data/ |
---
## Compatibility Checklist
When updating Claude Code, verify:
- [ ] `history.jsonl` format unchanged
- [ ] `projects/` folder structure unchanged
- [ ] Message schema fields present
- [ ] `cwd` field still available
- [ ] Token usage fields unchanged
- [ ] Subagent naming convention (`agent-*.jsonl`)
---
## Change Log
### 2025-12-08
- Initial documentation
- Verified with Claude Code latest version
- Confirmed: `history.jsonl` + `projects/*.jsonl` structure
- Confirmed: JSONL format with documented fields
---
## Notes for Claude Viewer Development
1. **Always have fallbacks** - Don't assume fields exist
2. **Monitor Substack author** - @idsc2025 seems to reverse-engineer Claude Code updates
3. **Version check** - Consider reading `version` field from messages to detect changes
4. **Graceful degradation** - App should work even if some fields missing
