Claude Folder Structure: .claude and ~/.claude Explained

November 11, 2026 · 12 min read

Claude Folder Structure: What Goes in .claude and ~/.claude

The Claude folder structure has two halves. Claude Code reads a .claude/ folder inside your project, which you commit and share with your team, and a ~/.claude/ folder in your home directory, which holds personal config for every project. Below is a full tree of both, what each file does, which scope wins and what to commit.

What Is the Claude Folder Structure?

Each half has a different job. Project files travel with the repo, so a teammate who clones it gets the same permissions, skills and subagents you do. Home files hold your personal defaults, plus the transcripts and history Claude Code writes as you work.

On Windows, ~/.claude resolves to %USERPROFILE%\.claude. If you set the CLAUDE_CONFIG_DIR environment variable, every home path moves under that directory instead. Per the official .claude directory reference, most people only ever edit CLAUDE.md and settings.json, and everything else is optional.

A quick note on placement: CLAUDE.md sits at the project root or inside .claude/, with a personal copy at ~/.claude/CLAUDE.md, and a separate guide covers what to write in it. Like the rest of these files, it's plain Markdown, the format we explain in why AI tools run on Markdown. And if you arrived looking for how Cowork or claude.ai Projects organize your files, that's a different product; this page is about Claude Code's config folders.

A Full .claude Directory Tree for a Project

Here's the Claude Code folder structure for a sample repo with every optional piece filled in. You won't need all of it, but seeing the whole map makes it easier to know where a new file belongs.

my-app/
├── CLAUDE.md                 # team instructions (or .claude/CLAUDE.md)
├── CLAUDE.local.md           # your private notes for this repo
├── .mcp.json                 # team MCP servers
├── .worktreeinclude          # gitignored files to copy into new worktrees
└── .claude/
    ├── settings.json         # shared permissions, hooks, env vars
    ├── settings.local.json   # your personal overrides
    ├── rules/
    │   └── testing.md
    ├── skills/
    │   └── review-pr/
    │       ├── SKILL.md
    │       └── checklist.md
    ├── commands/
    │   └── deploy.md
    ├── agents/
    │   └── code-reviewer.md
    ├── output-styles/
    │   └── teaching.md
    ├── workflows/
    │   └── bug-sweep.js
    └── agent-memory/
        └── code-reviewer/

To sketch a tree like this for your own repo, paste an indented list of paths into our directory tree generator. For an existing repo, the Linux tree command prints the real layout, and -a includes hidden folders like .claude.

Note that three files sit at the repo root rather than inside .claude/. Here's what each entry does and whether it belongs in git, based on the docs' file reference:

PathWhat it doesCommit?
CLAUDE.mdInstructions loaded every sessionYes
CLAUDE.local.mdYour private notes for this repoNo
.mcp.jsonMCP servers the whole team usesYes
.worktreeincludeGitignored files to copy into new worktreesYes
.claude/settings.jsonPermissions, hooks, env vars, model defaultsYes
.claude/settings.local.jsonYour personal overridesNo
.claude/rules/Topic-scoped instruction filesYes
.claude/skills/Reusable prompts, run as /name or picked by ClaudeYes
.claude/commands/Single-file prompts, the older skill formatYes
.claude/agents/Subagents with their own prompt and toolsYes
.claude/output-styles/Instruction sets that change how Claude respondsYes
.claude/workflows/Saved dynamic workflow scriptsYes
.claude/agent-memory/Persistent memory for project subagentsYes

settings.json, settings.local.json and Which Scope Wins

Claude Code reads four settings files. Your user file is ~/.claude/settings.json. The shared project file is .claude/settings.json, and the local project file is .claude/settings.local.json. Organizations can add a fourth, managed settings, which your own files can't override, except for a few security-sensitive keys.

When the same key appears in more than one place, the settings precedence order decides, highest first:

  1. Managed settings from your organization
  2. Command line JSON passed with --settings
  3. Project local: .claude/settings.local.json
  4. Shared project: .claude/settings.json
  5. User: ~/.claude/settings.json

List keys behave differently. If permissions.allow appears in three files, Claude Code merges all three lists instead of picking one. That's why your personal allow rules and your team's rules both apply at once.

A small shared project file might look like this:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Bash(npm run build)", "Bash(npm run test *)"],
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

This lets Claude run your build and test scripts without asking and blocks it from reading .env files. The schema line gives you autocomplete in editors that support JSON Schema. Settings files are strict JSON, so a // comment or a trailing comma is a syntax error.

There's no hooks folder. Hooks, environment variables and model defaults are all keys inside settings.json. The local file is also where Claude Code saves a "Yes, and don't ask again" approval, as an allow rule. Run /status and check the Setting sources line to see which files loaded.

Are Commands and Skills the Same Thing Now?

Mostly, yes. The skills documentation says custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working.

The difference is what a skill can carry. A skill is a folder, so it can hold supporting files like a checklist or a script next to SKILL.md. Claude can also load a skill on its own when your request matches its description, while a command file is a single prompt you call by name. The docs recommend skills for new work.

When two definitions share a name, these rules decide:

  • A skill beats a command file with the same name.
  • Enterprise skills beat personal ones in ~/.claude/skills/, and personal skills beat project skills.
  • If you start Claude Code at the repo root, it doesn't load a nested skill folder such as apps/web/.claude/skills/ at startup. Those skills load the first time Claude reads or edits a file in apps/web/.

A minimal SKILL.md looks like this:

---
description: Reviews the current branch against main. Use when the user asks for a PR review.
---

# Review a pull request

1. Read the diff against main.
2. Run the test command.
3. List risks, then give a verdict.

The YAML block between the --- lines is frontmatter. Claude Code only reads it when the opening --- is the very first line of the file. Only description is recommended; every other field is optional.

Before you save a skill, it helps to check that its headings, lists and tables read cleanly. Paste the body below the frontmatter into the editor here. Our preview doesn't render YAML front matter, so leave that block out of the paste.

Review a pull request

Use when the user asks for a review of the current branch.

Steps

  1. Read the diff against main.
  2. Run the test command.
  3. Check that new code has tests.
  4. Flag risky changes such as migrations or auth.

Output

  • A summary in three bullets
  • A list of risks, highest first
  • A verdict: approve or request changes
Severity Meaning
High Blocks the merge
Low Fix in a follow-up
89 words439 characters21 lines
Markdown

The left pane holds the Markdown and the right pane shows the live preview, so a broken list or table shows up before Claude ever reads the file.

Subagents, Rules, Output Styles, Workflows and .mcp.json

The rest of the project folder is for more specialized jobs. Add these only when you have a reason to.

agents/ holds subagents, one Markdown file each. A subagent runs in its own context with its own system prompt, tool list and model. Per the subagent docs, the frontmatter requires name and description, and often sets tools and model. A subagent with project-scoped persistent memory keeps its notes in .claude/agent-memory/, in a folder named after it.

rules/ holds topic files, such as one for testing and one for API style, that can be limited to certain paths.

output-styles/ holds Markdown files that change how Claude responds, for example a custom style that turns Claude into a writing assistant. workflows/ holds JavaScript files saved from the /workflows command, and each one runs as /name in later sessions. Dynamic workflows aren't on every plan, and on Pro you turn them on in /config.

MCP servers split by scope too. Team servers go in .mcp.json at the repo root. Your personal servers live in ~/.claude.json, which isn't committed.

What Lives in ~/.claude in Your Home Directory?

Your home folder holds two kinds of files: config you write, and data Claude Code writes as you work.

~/
├── .claude.json              # app state, account, personal MCP servers
└── .claude/
    ├── CLAUDE.md             # your instructions for every project
    ├── settings.json         # your default settings
    ├── keybindings.json      # custom shortcuts
    ├── themes/               # custom color themes
    ├── skills/  agents/  commands/  output-styles/  rules/  workflows/
    ├── plugins/              # installed plugins
    ├── projects/
    │   └── <project>/
    │       ├── <session>.jsonl   # conversation transcripts
    │       └── memory/           # auto memory
    ├── history.jsonl         # prompts you've typed
    ├── file-history/         # snapshots for checkpoint restore
    └── plans/                # plan mode files

Notice that ~/.claude.json sits beside the folder, not inside it. The personal skills, agents and commands here work like the project versions but follow you into every repo.

The app data needs more care than the config. Transcripts and history are plaintext, and anything a tool reads, including a .env file, can end up in a transcript. Claude Code deletes transcripts and similar session files older than cleanupPeriodDays, which defaults to 30 days. To clear one project's state, run claude purge with the project path; older versions named it claude project purge.

Never delete ~/.claude.json, ~/.claude/settings.json or ~/.claude/plugins/. They hold your account details, preferences and installed plugins.

Which Files in .claude Should You Commit to Git?

Commit everything in the project folder that your team should share: CLAUDE.md, .claude/settings.json, rules/, skills/, commands/, agents/, output-styles/, workflows/, agent-memory/ and .mcp.json. Nothing from ~/.claude belongs in a repo. Think of the split this way: your README explains the project to humans, and .claude/ explains it to the agent.

Keep two files out. Claude Code adds **/.claude/settings.local.json to your global git excludes, but only when it writes that file itself. If you create it by hand, or create CLAUDE.local.md, you have to ignore it yourself:

# Personal Claude Code files
CLAUDE.local.md
.claude/settings.local.json

One behavior surprises teams. Allow rules in a committed settings.json wait until each teammate trusts the folder, while deny and ask rules apply right away. Don't assume a new teammate gets your committed allow list on day one.

A Starter Claude Folder Structure for a New Repo

We prefer starting with only CLAUDE.md and .claude/settings.json. Add a skill once you've typed the same prompt three times, and a subagent once a task keeps flooding your main conversation. Our guide to writing a CLAUDE.md file covers what belongs in it.

my-app/
├── CLAUDE.md
└── .claude/
    └── settings.json

Grow it in this order: permissions in settings.json first, then one or two skills, then subagents. Treat these files like any other docs, with short sections and clear headings, as our guide to Markdown for documentation describes.

The honest limitation is that this layout changes often between Claude Code releases. Check the official directory page before copying an old tree, including this one.

For the instruction file itself, our CLAUDE.md generator fills in CLAUDE.md, AGENTS.md, .cursorrules and .github/copilot-instructions.md from a short form. It doesn't create the .claude/ folder, settings files, skills or agents, and it doesn't scan your repo. If your repo already has an AGENTS.md for other coding agents, Claude Code can read it in place of CLAUDE.md. Our AGENTS.md guide shows how to keep one file for every agent.

Once you know the Claude folder structure, most changes have an obvious home. Team rules go in the project's .claude/, personal habits go in your home folder, and settings follow a clear precedence order. Start small, commit the shared files and keep the local ones out of git. When you draft a new skill, paste its body into the editor to check its headings, lists and tables before you save it.