Claude Code Configuration

claude-code-config.md

Claude Code Configuration

Overview

1. .claude/ at the project root (per-repo, team config)
2. ~/.claude/ in your home directory (global, personal config)

There is also a separate file ~/.claude.json (not a directory) that Claude Code writes to for app state and OAuth tokens. Think of it like .git/ vs .gitconfig: one is a per-project directory, one is global.

Note: There is no .claude-code directory, Claude Code uses .claude/.

---

Project-level .claude/ (lives in the repo)

This is the folder you commit to git so your team gets the same rules, commands, and permissions. A full-featured layout looks like this:

my-project/
├── CLAUDE.md                    # Instructions loaded every session (project root, not inside .claude/)
├── CLAUDE.local.md              # Your private notes for this project (add to .gitignore)
├── .mcp.json                    # Team-shared MCP server definitions (repo root)
├── .worktreeinclude             # Gitignored files to copy into new git worktrees
├── .claudeignore                # Paths Claude should never read
└── .claude/
    ├── settings.json            # Permissions, hooks, env vars, model defaults
    ├── settings.local.json      # Personal overrides, auto-gitignored
    ├── rules/
    │   ├── testing.md           # Topic-scoped instructions (can be path-gated)
    │   └── security.md
    ├── skills/
    │   └── code-review/
    │       ├── SKILL.md         # Reusable workflow, auto-invoked when relevant
    │       └── reference.md     # Supporting docs the skill reads on demand
    ├── commands/
    │   └── deploy.md            # Single-file slash command (/deploy)
    ├── agents/
    │   └── security-auditor.md  # Subagent with its own prompt and tool allowlist
    ├── agent-memory/
    │   └── security-auditor/    # Persistent memory for that subagent
    ├── output-styles/
    │   └── terse.md             # Custom system-prompt sections
    └── docs/                    # Unofficial but common: reference docs skills read on demand
        └── architecture.md

Loading behavior

A few things worth knowing about loading behavior, because this trips people up:

• CLAUDE.md sits at the repo root, not inside .claude/. It loads every session. Claude walks from your current working directory up to the root, so nested CLAUDE.md files in subdirectories also apply, with deeper files taking priority.
• rules/*.md loads automatically too, so keep them short and topical. Heavy reference material belongs in skills/ or docs/ where it only loads when needed. The analogy here is eager vs lazy imports: rules are eager, skills are lazy.
• settings.local.json gets added to .gitignore automatically when Claude writes to it. Safe place to put personal permission overrides.
• commands/ and skills/ are converging. A file at .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Skills are the newer form and support a folder with extra files plus frontmatter.

---

Global ~/.claude/ (lives in your home directory)

This is your personal setup, shared across every project on this machine. You do not commit this anywhere.

~/.claude/
├── CLAUDE.md                    # Your global instructions (loaded every session, everywhere)
├── settings.json                # Your global permissions, hooks, model defaults
├── settings.local.json          # Machine-local overrides
├── rules/                       # Global topic-scoped rules
├── skills/                      # Skills available across all projects
│   └── my-personal-skill/
│       └── SKILL.md
├── commands/                    # Personal slash commands
├── agents/                      # Personal subagents
├── agent-memory/                # Persistent memory for personal subagents
├── output-styles/
├── keybindings.json             # Custom keyboard shortcuts
│
│   # Data Claude writes during sessions (not config you author):
├── projects/
│   └── <project-hash>/
│       ├── <session>.jsonl      # Full session transcripts (plaintext, not encrypted)
│       └── memory/              # Auto-memory: Claude's notes to itself across sessions
├── history.jsonl                # Your prompt history across all sessions
├── todos/                       # Task lists per session
├── plans/                       # Plan-mode markdown documents
├── file-history/                # File checkpoints for undo/rollback
├── shell-snapshots/             # Shell environment snapshots (cleared on clean exit)
├── session-env/                 # Per-session environment variables
├── stats-cache.json             # Aggregated usage statistics
└── debug/                       # Debug logs per session

The config files mirror the project layout so muscle memory transfers. The session data directories (projects/, history.jsonl, todos/, file-history/, etc.) are machine-written, not hand-edited. Files in most of them get cleaned up automatically once older than cleanupPeriodDays (default 30).

Security note: Transcripts in projects/<project>/<session>.jsonl are plaintext. If a tool reads a .env or a command prints a credential, that value lands on disk. Lower cleanupPeriodDays in settings.json or set CLAUDE_CODE_SKIP_PROMPT_HISTORY=1 to reduce exposure.

You can also redirect everything with the CLAUDE_CONFIG_DIR environment variable. Every ~/.claude/ path above will live under that directory instead. Useful if you want XDG-style placement under ~/.config/claude/.

---

Minimal starter examples

A bare-bones CLAUDE.md

# Project Name

Short description of what this project does and who uses it.

## Stack

- Language: Python 3.12
- Framework: Flask
- Database: SQLite (dev), PostgreSQL (prod)

## Conventions

- Prefer standard library over third-party deps
- Use pytest for tests, files in tests/ mirror src/
- No heavy frameworks; keep it simple

## Commands

- `make dev` - start dev server on :5000
- `make test` - run pytest
- `make lint` - ruff check

A minimal .claude/settings.json

With the $schema line for editor autocomplete:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(make *)",
      "Bash(pytest *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Read(**)",
      "Edit(src/**)",
      "Edit(tests/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)",
      "Bash(curl * | sh)",
      "Read(.env)",
      "Read(**/*secret*)"
    ]
  },
  "model": "claude-opus-4-7"
}

Anything not in allow or deny will prompt you for confirmation, which is the intentional middle ground.

A simple slash command

At .claude/commands/review.md:

---
description: Review the current branch diff before merging
---

## Changes

!`git diff --name-only main...HEAD`

## Full diff

!`git diff main...HEAD`

Review for code quality, security issues, missing tests, and performance.
Give specific feedback per file.

That becomes /review in your session, with the actual git diff injected via the !`backtick` shell-execution syntax.

---

Quick verification commands

Once you are in a session, you can see what actually loaded:

Command	Description
/context	Token usage across system prompt, memory, skills, MCP tools
/memory	Which CLAUDE.md and rules files are loaded
/skills	Available skills from project, user, and plugin sources
/permissions	Current allow/deny rules
/mcp	Connected MCP servers
/hooks	Active hook configurations
/agents	Configured subagents
/doctor	Installation and configuration diagnostics

Start with /context when something feels off, then drill into the specific subsystem.

---

What to commit and what to ignore

Add these to .gitignore at the project level:

.claude/settings.local.json
CLAUDE.local.md

Commit everything else in .claude/. That way your team gets consistent rules, permissions, skills, and commands, while personal overrides stay on your machine.

---

Official reference: https://code.claude.com/docs/en/claude-directory