[DOCS] ~/.claude/ directory is undocumented — community deep dive available for incorporation

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://ramonactruta.substack.com/p/inside-claude-structure-is-not-security

Section/Topic

~/.claude/ directory — session storage, file formats, and security implications

Current Documentation

There is no documentation for the ~/.claude/ directory.

What's Wrong or Missing?

The ~/.claude/ directory is completely undocumented. Every Claude Code user
has this directory on their machine. It contains:

• Complete conversation history in plaintext JSONL (projects/ folder)
• Every prompt ever typed (history.jsonl)
• Sub-agent task descriptions (.meta.json files)
• Shell environment snapshots (shell-snapshots/)
• Usage statistics and token counts (stats-cache.json)
• A Statsig stable ID — persistent anonymous identifier across sessions
• A plugin blocklist refreshed remotely during active sessions
• Abandoned agent task lists (todos/)

Users have no way to know what is stored, that storage is unencrypted
plaintext, or that any secrets passing through tool results are written
to disk. This is both a documentation gap and a security/privacy gap.

Suggested Improvement

Add a ~/.claude/ reference page to the official docs covering:

• Full directory structure with explanation of each folder/file
• File formats (JSONL schema, meta.json, etc.)
• What is stored and for how long
• Security implications (plaintext storage, credential exposure risk)
• How to read and interpret session files

A detailed community-written guide already exists and is available as
a starting point:
Inside ~/.claude/: Structure is Not Security

Impact

High - Prevents users from using a feature

Additional Context

The linked community article was written by reading actual files from a real installation and verified against the actual directory structure. Multiple community members have noted it should be incorporated into official documentation.