Inside the .claude/ Folder: How Claude Code Organizes Your AI Workspace

Claude Code writes a .claude/ folder into your project root the first time you run it, and most developers never open it. That silence costs you twice. You surrender any say over what Claude remembers between sessions, and you risk pushing conversation logs that quote your own API keys into a repository other people can read.

I walked this folder path by path inside a live Next.js project deployed on AWS, then set the result beside GitHub Copilot and Cursor to separate what genuinely belongs to Claude Code from what every stateful assistant now does. Below sits that map, the 30-day cleanup command I run against it, and the security rules I refuse to bend.

Subscribe to the newsletter for deep dives on AI developer tooling.

The short answer

The .claude/ folder is Claude Code's workspace directory. It holds conversation threads, context snapshots, cached embeddings, and project-specific settings, which lets Claude keep awareness of your project across sessions instead of starting cold every morning. Five paths carry the whole system, conversations/, context/, cache/, settings.json, and state.db. Add the folder to .gitignore before your next commit, because the conversation logs inside it quote whatever you pasted into a prompt.

Think of it as Claude's memory palace. Understanding how the five paths divide the work helps you steer what Claude recalls, and it stops the two failure modes that bite most teams, an accidental commit and a context window quietly filling up.

What Claude Code Stores in .claude/

The folder structure reveals how Claude maintains project awareness:

.claude/
├── conversations/          # Thread history and message logs
├── context/             # Project snapshots and file indexes
├── cache/                # Embeddings and computed context
├── settings.json         # Project-specific preferences
└── state.db             # Session persistence and bookmarks

conversations/

Each conversation thread gets a JSON file with:

• Message history (prompts and responses)
• File references and code snippets
• Tool invocations and their results
• Timestamps and session metadata

This enables Claude to reference previous discussions. Ask "What did we decide about the auth flow yesterday?" and Claude can search its conversation history for the answer.

context/

Claude maintains a semantic index of your codebase:

• File structure and module relationships
• Function signatures and type definitions
• Recent changes and active work areas
• Project-specific terminology and patterns

This index updates incrementally. When you modify files, Claude updates its understanding without re-scanning the entire project.

cache/

Computed embeddings and intermediate results:

• Vector embeddings for semantic search
• Parsed ASTs for code understanding
• Dependency graphs and import maps
• Generated documentation snippets

Caching these expensive computations makes Claude responsive even in large codebases.

Why This Matters

The .claude/ folder enables capabilities that stateless AI tools cannot provide:

Persistent Context. Claude remembers your project across sessions. Return after a weekend and Claude still knows you were refactoring the payment module.

Semantic Search. Claude can find relevant code by meaning, not just filename. Ask "Where do we handle refunds?" and Claude searches its context index.

Incremental Understanding. Claude updates its model of your codebase as you work. Add a new API endpoint and Claude knows about it immediately.

Conversation Recovery. If your terminal crashes, Claude restores conversation threads from the .claude/ folder.

Best Practices

Add to .gitignore

Never commit this folder. It contains:

• Personal conversation history
• Potentially sensitive code snippets
• User-specific state and preferences

Exclude from Backups

Add .claude/ to your backup exclusions. The data is ephemeral and can be regenerated. Backing it up wastes space and may preserve old conversation data you intended to delete.

Clean Up Periodically

Old conversations accumulate. Clean them when:

• The folder grows beyond 100MB
• You finish major project phases
• You want to reset Claude's understanding

Understand the Limits

The .claude/ folder has limitations:

• Context has size limits (approximately 200K tokens)
• Very large projects may exceed indexing capacity
• Complex dependency graphs may not be fully captured

When Claude seems to forget things, the context window may be full.

How Claude Uses Context

Understanding the context system helps you work with Claude more effectively:

Automatic Context

Claude automatically includes:

• Open files in your editor
• Recently modified files
• Files referenced in conversation
• Project configuration files

Manual Context

You can provide additional context:

• Use @file to reference specific files
• Use @folder to include entire directories
• Paste code snippets directly
• Share documentation URLs

Context Priority

Claude prioritizes context by relevance:

1. Explicitly mentioned files
2. Recently accessed files
3. Files related to current work
4. Project-wide patterns and conventions

Comparing to Other AI Tools

Claude's persistent context is its differentiating feature. While Copilot treats each prompt independently, Claude builds cumulative understanding through the .claude/ folder.

Security Considerations

The .claude/ folder raises security questions:

Data Exposure. Conversation files may contain:

• API keys mentioned in prompts
• Database credentials in code snippets
• Internal architecture discussions
• Business logic details

Mitigation Strategies:

• Never commit .claude/ to version control
• Exclude from dotfiles repositories
• Clean before sharing project archives
• Use environment variables for secrets

Corporate Environments. Some organizations may want to:

• Disable persistent storage entirely
• Store .claude/ on encrypted volumes
• Implement automatic cleanup policies
• Audit conversation contents