.claude Directory

Claude Code reads instructions, settings, skills, subagents, and memory from ~/.claude in your home directory and from your project directory. Global files in ~/.claude establish your personal baseline across all projects; project files override or extend them for a specific repo.

Most users only need CLAUDE.md and .claude/settings.json. Everything else is optional — add skills, rules, or subagents as you need them.

If you set CLAUDE_CONFIG_DIR, every ~/.claude path on this page lives under that directory instead.

Global files (`~/.claude`)

Files in your home directory. These form the base layer — they apply to every project and are never committed.

Directory~/
- .claude.json App state, UI toggles, OAuth session, personal MCP servers
- Directory.claude/
  - CLAUDE.md Personal preferences across all projects
  - settings.json Default settings for all projects
  - keybindings.json Custom keyboard shortcuts (hot-reloaded on edit)
  - Directoryprojects/ Auto memory — Claude writes and reads these
    Directoryproject-name/memory/
    MEMORY.md Index loaded at session start (first 200 lines / 25 KB)
    debugging.md Topic file — read on demand when related task comes up
  - Directoryrules/ User-level rules that apply everywhere
    …
  - Directoryskills/ Personal skills available in every project
    …
  - Directorycommands/ Personal single-file commands (all projects, legacy)
    …
  - Directoryoutput-styles/ Personal output styles (all projects)
    …
  - Directoryagents/ Personal subagents available in every project
    …
  - Directoryagent-memory/ User-scoped subagent persistent memory
    …

Project files

Files in your project root and .claude/ folder. These override or extend the global layer. Commit most of them so your whole team shares them.

Directoryyour-project/
- CLAUDE.md Project instructions loaded every session
- .mcp.json Team-shared MCP server configuration
- .worktreeinclude Gitignored files to copy into new worktrees
- Directory.claude/
  - settings.json Permissions, hooks, model, env vars
  - settings.local.json Personal overrides — gitignored automatically
  - Directoryrules/
    testing.md Path-gated: loads when Claude reads a matching test file
    api-design.md Path-gated: loads when Claude reads src/api/
  - Directoryskills/
    Directorysecurity-review/
    SKILL.md Entrypoint: trigger, invocability, instructions
    checklist.md Supporting file bundled with the skill
  - Directorycommands/
    fix-issue.md Invoked as /fix-issue — prefer skills/ for new work
  - Directoryoutput-styles/ Project-scoped output style overrides
    …
  - Directoryagents/
    code-reviewer.md Subagent with its own prompt, tools, and model
  - Directoryagent-memory/
    Directorycode-reviewer/
    MEMORY.md Claude writes and maintains this automatically

File reference

File	What it does	Hub
`~/.claude.json`	App state, OAuth, UI toggles, personal MCP servers	Settings
`~/.claude/projects/*/memory/`	Auto memory: Claude’s notes across sessions	Memory → Auto Memory
`~/.claude/keybindings.json`	Custom keyboard shortcuts	Keybindings
`CLAUDE.md`	Instructions loaded every session (global + project)	Memory
`rules/*.md`	Topic-scoped instructions, optionally path-gated	Memory
`settings.json`	Permissions, hooks, env vars, model defaults	Settings
`skills/<name>/SKILL.md`	Reusable prompts invoked with `/name` or auto-invoked	Skills
`commands/*.md`	Single-file prompts — same as skills (legacy)	Skills
`output-styles/*.md`	Custom system-prompt sections	Settings
`agents/*.md`	Subagent definitions with their own prompt and tools	Agents
`agent-memory/<name>/`	Persistent memory for subagents	Agents
`settings.local.json`	Personal overrides, auto-gitignored (project only)	Settings
`.mcp.json`	Team-shared MCP servers, project root	Settings → MCP
`.worktreeinclude`	Gitignored files copied into new worktrees	Sessions

Check what loaded

Run these slash commands to inspect what is active in the current session.

Command	Shows
`/context`	Token usage: system prompt, memory, skills, MCP tools, messages
`/memory`	Which `CLAUDE.md` and rules files loaded, plus auto-memory entries
`/agents`	Configured subagents and their settings
`/hooks`	Active hook configurations
`/mcp`	Connected MCP servers and their status
`/skills`	Available skills from project, user, and plugin sources
`/permissions`	Current allow and deny rules
`/doctor`	Installation and configuration diagnostics

Start with /context for an overview, then the specific command for what you want to investigate.

Application data

~/.claude also holds data Claude Code writes during sessions. These files are plaintext — file contents, command output, and pasted text all land in a transcript on disk.

Cleaned up automatically (deleted on startup once older than cleanupPeriodDays, default 30 days):

projects/<project>/<session>.jsonl — full conversation transcript
projects/<project>/<session>/tool-results/ — large tool outputs
file-history/<session>/ — pre-edit snapshots for checkpoint restore
plans/ — plan files from plan mode
debug/ — debug logs (only written with --debug or /debug)
paste-cache/, image-cache/ — large pastes and attached images

Kept until you delete them:

history.jsonl — every prompt you’ve typed, with timestamp and project
stats-cache.json — token and cost totals shown by /cost
backups/ — timestamped copies of ~/.claude.json from config migrations

Do not delete ~/.claude.json, ~/.claude/settings.json, or ~/.claude/plugins/ — those hold your auth, preferences, and installed plugins.

Memory — write and organize CLAUDE.md, rules, and auto memory
Settings — permissions, hooks, environment variables, model defaults
Skills — build reusable prompts and workflows
Agents — define specialized subagents with their own context
Hooks — wire shell commands to Claude Code lifecycle events
Keybindings — customize keyboard shortcuts
Sessions → Transcript Storage — how session data is stored on disk