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:

| cwd | Encoded directory name | |-----|------------------------| | /Users/me/projects/foo | -Users-me-projects-foo | | /Users/me/foo/.worktrees/bar | -Users-me-foo--worktrees-bar |

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

| Field | Description | |-------|-------------| | sessionId | UUID, matches .jsonl filename | | summary | Auto-generated by CC | | customTitle | User-set via /rename (null if unset) | | firstPrompt | First user message (truncated) | | gitBranch | Branch at session creation | | projectPath | Absolute cwd path | | messageCount | Total messages in session | | isSidechain | Whether session is a sidechain | | created / modified | ISO timestamps | | fileMtime | File modification time (epoch ms) |

/rename Command

Sets customTitle field in sessions-index.json.

| Aspect | Behavior | |--------|----------| | Scope | Per-project (cwd-specific) | | Collision | Same name can exist in different projects | | Storage | Only in index, not in .jsonl transcript | | Persistence | Survives session end, stored in index |

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

| Topic | Skill | |-------|-------| | Searching transcripts | cc-thread-search | | Permission config | cc-configuring-permissions | | Hook config | cc-writing-hooks | | MCP config | cc-configuring-mcp |