---

name: cc-internals description: How Claude Code works internally. Use for ANY question about CC behavior, architecture, or "how does CC do X". Covers session storage, /rename scope, project organization, file locations, and internal data structures.

Claude Code Internals

Facts about how Claude Code organizes and stores data.

Storage Layout

Copy~/.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.

Copy{
  "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

Copy# 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.

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

Related Skills