ReddRadar
Agent skill
cc-internals
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.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/cc-internals
SKILL.md
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.
json
{
"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
bash
# 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.
json
{"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 |
Didn't find tool you were looking for?