Understand configuration directories in Claude Code

Link copied

Attach video time

Claude Code uses hidden .claude directories to manage its configuration, conversation history, and custom tools. These directories let you customize Claude Code's behavior and share project-specific settings with your team.

There are two of them: one in your home directory for global settings, and an optional one in each project directory for project-specific configuration.

The global directory (~/.claude)

Your home directory contains a .claude folder that stores everything that applies across all your projects.

A handful of these are files you write yourself:

• CLAUDE.md -- Global instructions that apply to all your projects.

• settings.json -- Your preferences: permissions, hooks, environment variables, and model defaults.

• skills/ -- Packaged instructions and scripts that Claude pulls in when they become relevant.

• commands/ -- Global slash command definitions you can use in any project.

• agents/ -- Subagents that handle delegated tasks in their own context window.

• rules/ -- Instructions split into topic files, which can be scoped to specific file paths.

Everything else in there is state that Claude Code manages for itself -- conversation transcripts, file snapshots, shell state, caches, and logs. You'll see a lot of directories, and you don't need to know what most of them are. Two are worth recognizing when you stumble across them:

• projects/ -- Your full conversation history, one folder per working directory. This is what --resume reads from.

• plugins/ -- Collections of related commands, agents, MCP servers, and hooks that you've installed.

Note: You'll also find a .claude.json file sitting next to the directory. That's not configuration you edit -- it holds your login session and the record of which project directories you've trusted. It identifies your account, so don't paste it into a bug report or a screen share.

Project-specific directories

Claude Code creates a .claude directory inside your project when it needs to store something project-specific, or when certain commands are run. If it doesn't exist yet, you can create it manually to set up your project's tools and configuration from the start.

It follows the same structure as your global directory, but everything in it applies only to this project. Custom build commands, project-specific agents, or team-shared permissions belong here.

Note: When the same setting is defined in both places, the project version wins. CLAUDE.md is the exception -- those files stack rather than override, so you get your global instructions and your project instructions together.

This is particularly useful for team projects. By committing the .claude directory to version control, everyone on your team gets the same tools and settings.

One file to leave out, though: settings.local.json. That's where Claude Code writes permissions you approve during a session, and it's meant to stay on your machine. Add it to your .gitignore:

.claude/settings.local.json

Where to put tools and configurations

You can start with everything global and gradually move settings into project directories as patterns emerge, or do the opposite (as I do) -- experiment locally, then promote the tools that prove useful up to your global configuration.