Claude Code Internals

Claude Code Internals

Facts about how Claude Code organizes and stores data.

Storage Layout

~/​.claude/
├── settings.json              # User config (see cc-configuring-permissions)
├── skills/                    # User-level skills
├── session-env/               # Session environment cache
└── projects/                  # All session data, per-project
    └── <encoded-path>/        # One dir per project cwd
        ├── sessions-index.json    # Session metadata index
        ├── <uuid>.jsonl           # Session transcripts
        └── agent-<hash>.jsonl     # Subagent transcripts

Project Path Encoding

Project directories are cwd paths with slashes replaced by dashes:

Decode: echo "-Users-me-foo" | sed 's/^-/\//; s/​-/\//g'

Sessions Index (sessions-index.json)

Each project has one index tracking all sessions in that project.

{
  "version": 1,
  "entries": [
    {
      "sessionId": "027b253b-7743-4cd7-8c7b-96740e0a3cf8",
      "fullPath": "/​Users/​.../<uuid>.jsonl",
      "firstPrompt": "user's first message...",
      "summary": "Auto-generated summary",
      "customTitle": "user-set via /​rename",
      "messageCount": 28,
      "created": "2026-01-17T00:22:31.447Z",
      "modified": "2026-01-17T00:44:18.038Z",
      "gitBranch": "main",
      "projectPath": "/​Users/​me/​projects/​foo",
      "isSidechain": false,
      "fileMtime": 1769006749607
    }
  ]
}

Session Entry Fields

/​rename Command

Sets customTitle field in sessions-index.json.

Finding Named Sessions

# All named sessions across all projects
for dir in ~/​.claude/​projects/​*/; do
  jq -r '.entries[] | select(.customTitle != null) | "\(.customTitle) | \(.projectPath)"' \
    "$dir/​sessions-index.json" 2>/​dev/​null
done

# Named sessions in current project
jq -r '.entries[] | select(.customTitle != null) | "\(.customTitle): \(.sessionId)"' \
  ~/​.claude/​projects/​-Users-me-projects-foo/​sessions-index.json

Session Transcripts (.jsonl)

Each line is a JSON object. See cc-thread-search for search patterns.

{"type": "user", "timestamp": "<ISO>", "message": {...}, "sessionId": "<uuid>"}
{"type": "assistant", "timestamp": "<ISO>", "message": {...}, "sessionId": "<uuid>"}
{"type": "summary", ...}

Related Skills