The .claude Directory: Every Claude Code Config File Explained

These files describe how Claude should work in this repository, so they belong in git. A minimal setup that most projects benefit from:

1your-project/2├── CLAUDE.md                 # commands, conventions, gotchas3├── .mcp.json                 # shared MCP servers, if any4└── .claude/5    ├── settings.json         # permissions and hooks6    ├── rules/7    │   └── api.md            # loaded for files under src/api/8    └── skills/9        └── release-notes/10            └── SKILL.md      # invoked as /release-notes

A path-gated rule loads only when Claude works on matching files, which keeps CLAUDE.md short:

1---2paths:3  - "src/api/**/*.ts"4---5- Every handler validates input with the shared zod schema.6- Return errors as { error: { code, message } }.

.claude/commands/*.md still works and uses the same mechanism as skills, but for new workflows Anthropic recommends skills, which can bundle supporting files.

Two files hold your personal preferences for one project and should not be committed:

• .claude/settings.local.json: your overrides, such as an extra allow rule or a gateway credential. Claude Code adds it to .gitignore when it saves a setting there; if you create it by hand, add it yourself.
• CLAUDE.local.md at the project root: private instructions loaded alongside CLAUDE.md. Create it manually and gitignore it.

In your home directory, ~/.claude/ applies to every project:

• ~/.claude/settings.json: your default settings; project and local files override any key you also set there.
• ~/.claude/CLAUDE.md: personal preferences across all projects.
• ~/.claude/skills/, agents/, rules/, output-styles/: your personal versions of the project-level folders.
• ~/.claude/keybindings.json and themes/*.json: shortcuts and colour themes.
• ~/.claude/projects/<project>/memory/: auto memory, notes Claude writes for itself across sessions.

And one file outside the folder: ~/.claude.json holds app state, OAuth details, UI toggles, and MCP servers you added at user or local scope. You rarely edit it by hand.

The most useful table in the reference maps intent to file:

• Give Claude project context and conventions → CLAUDE.md (project or global).
• Allow or block specific tool calls → permissions or hooks in settings.json.
• Run a script before or after tool calls → hooks in settings.json.
• Set environment variables for the session → env in settings.json.
• Keep personal overrides out of git → settings.local.json.
• Add a prompt or capability invoked with /name → skills/<name>/SKILL.md.
• Define a specialised subagent with its own tools → agents/*.md.
• Orchestrate many subagents from a script → workflows/*.js.
• Connect external tools over MCP → .mcp.json (project scope).
• Change how Claude formats responses → output-styles/*.md.

The underlying distinction is between guidance and enforcement. CLAUDE.md and rules are instructions Claude applies with judgment and can miss, especially in a long session. Permissions and hooks in settings are applied by Claude Code itself, every time. If something must never happen, or must always happen, it belongs in settings, not in CLAUDE.md.

Skills, commands, subagents, output styles, and rules all read configuration from YAML frontmatter at the top of the file. A subagent that reviews code with read-only tools:

1---2name: security-reviewer3description: Reviews code for security vulnerabilities4tools: Read, Grep, Glob, Bash5model: opus6---7You are a senior security engineer. Review code for injection, auth flaws,8secrets in code, and insecure data handling. Give file and line references.

And a skill with side effects that you want to trigger only by hand:

1---2name: deploy-staging3description: Deploy the current branch to staging4disable-model-invocation: true5---6Run the staging deploy script and report the URL.

The description field matters most: it is how Claude decides when to use a skill or delegate to a subagent, so write it as a precise statement of when the file applies.

Beyond the configuration you write, ~/.claude holds data Claude Code writes during sessions, and it is plaintext. Anything that passes through a tool is written to a transcript: file contents, command output, pasted text. If Claude reads a .env file or a command prints a token, that value is now in ~/.claude/projects/<project>/<session>.jsonl.

Swept automatically after cleanupPeriodDays (default 30, minimum 1): session transcripts, subagent transcripts, large tool outputs, file-history/ snapshots used for checkpoint restore, plans/, debug/ logs, paste-cache/, and others, plus orphaned worktrees.

Kept until you delete them: history.jsonl (every prompt you typed, for up-arrow recall), stats-cache.json, auto memory files, and state such as .credentials.json.

To reduce exposure: lower cleanupPeriodDays, deny reads of credential files with permission rules, and set CLAUDE_CODE_SKIP_PROMPT_HISTORY to skip writing transcripts and prompt history (or pass --no-session-persistence with -p). To delete one project's state, run claude purge; it shows the full plan and asks before removing transcripts, auto memory, per-session task and debug files, matching history lines, and the project's entry in ~/.claude.json.

In a project you use Claude Code with:

1. List what exists: ls -la CLAUDE.md CLAUDE.local.md .mcp.json .worktreeinclude .claude/ 2>/dev/null and ls ~/.claude/. 2. Run git check-ignore -v .claude/settings.local.json CLAUDE.local.md and fix .gitignore if either is not ignored. 3. Start claude, run /context and /permissions, and note which CLAUDE.md and rules files loaded. 4. Move one domain-specific section of CLAUDE.md into .claude/rules/<topic>.md with a paths: filter, and confirm with /context that it loads only when you open a matching file. 5. Add "deny": ["Read(./.env)", "Read(./.env.*)"] to .claude/settings.json. 6. Search last month's transcripts for secrets: grep -l "API_KEY\|SECRET" ~/.claude/projects/*/*.jsonl | head. If anything shows up, rotate the credential and consider claude purge.

Pass criterion: personal files are gitignored, CLAUDE.md is shorter with a path-gated rule doing part of its job, secret reads are denied, and you know whether any credential has already been written to a transcript.