The .claude/ Folder: Complete Setup Guide for Claude Code

You have been using Claude Code for a while. You have typed claude, watched it edit files, maybe even wired up an MCP server or two. But there is a quiet folder in your project root that does more than you think: .claude/.

This is where individual developers become teams. It is where "Claude works for me" becomes "Claude works for us." Without it, every teammate reinvents the wheel — the same permission prompts, the same manual commands, the same style drift across reviews.

This guide walks through every surface the .claude/ folder exposes — settings, hooks, slash commands, sub-agents, memory — plus six battle-tested templates you can copy today and four mistakes that bite every team at least once.

Here is the full file tree, with every file Claude Code will recognize:

.claude/
├── settings.json             # Committed team config (permissions, hooks, env)
├── settings.local.json       # Per-dev overrides — gitignore this
├── CLAUDE.md                 # Project-specific instructions for Claude
├── commands/
│   ├── review.md             # Custom /review slash command
│   └── deploy.md             # Custom /deploy slash command
├── agents/
│   ├── security-reviewer.md  # Specialized sub-agent definition
│   └── doc-writer.md         # Another specialized agent
├── hooks/
│   └── pre-commit.sh         # Shell script triggered before tool use
└── memory/                   # Auto-managed; skills read/write here
    └── MEMORY.md             # Index of per-topic memory filesCOPY

What to Commit vs Ignore

Commit to git: settings.json, CLAUDE.md, commands/, agents/, and hooks/. These define team behavior and belong in your repo.

Add to .gitignore: settings.local.json (contains API keys, personal paths) and memory/ (per-user state).

Claude Code resolves configuration from three scopes, applied in order of increasing priority:

Scope	Location	Committed	Purpose
User	~/.claude/settings.json	No	Your personal defaults across all projects
Project	.claude/settings.json	Yes	Team-wide agreement
Local	.claude/settings.local.json	No	Per-dev project override

When keys collide, Local wins, then Project, then User. This means a teammate can temporarily grant themselves a permission their laptop needs without affecting the shared config.

Debugging Effective Config

If Claude behaves differently than you expect, inspect the merged state in-session by asking:

Show me what permissions are currently activeCOPY

Claude will display the resolved permission set, telling you which scope contributed each entry.

1. Minimal settings.json (solo use)

{
  "permissions": {
    "allow": ["Bash(npm run *)", "Edit", "Write", "Read"]
  }
}COPY

Enough to unblock most workflows without full wildcard exposure.

2. Team-Wide Permission Allowlist

{
  "permissions": {
    "allow": [
      "Bash(npm run *)", "Bash(git status)", "Bash(git diff)",
      "Bash(git log *)", "Bash(pnpm install)",
      "Edit", "Write", "Read", "Grep", "Glob"
    ],
    "deny": [
      "Bash(git push *)", "Bash(rm -rf *)", "Bash(sudo *)"
    ]
  }
}COPY

Denies write-to-remote and destructive commands but allows everyday dev loops without prompting.

3. Pre-Commit Hook for Type Safety

In .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "sh .claude/hooks/typecheck.sh" }
        ]
      }
    ]
  }
}COPY

And .claude/hooks/typecheck.sh:

#!/bin/sh
npm run check || exit 1COPY

Any Edit/Write tool call is gated by a passing type check. Non-zero exit forces Claude to fix before proceeding.

4. Custom /review Slash Command

Create .claude/commands/review.md:

---
name: review
description: Run a disciplined PR review on the current branch
---

Review the current branch compared to main. Focus on:
1. Security issues (input validation, auth, secrets)
2. Performance regressions
3. Test coverage gaps
4. Anti-patterns relative to our existing code style

Report findings as a numbered list with file:line references.
End with a PASS/FAIL verdict.COPY

Now typing /review in the CLI runs this prompt against the current repo state.

5. Specialized Sub-Agent

In .claude/agents/security-reviewer.md:

---
name: security-reviewer
description: Reviews code for security vulnerabilities. Use for auth flows, input handling, and secret management.
tools: Read, Grep, Glob
model: sonnet
---

You are a security-focused code reviewer. Read the target files and look for OWASP Top 10 categories: injection, broken auth, sensitive data exposure, XXE, broken access control, security misconfiguration, XSS, insecure deserialization, vulnerable dependencies, and logging gaps.

Report each finding with CWE reference and proposed fix.COPY

Delegate via: @agent-security-reviewer review client/src/auth/.

6. Multi-Stack env Setup

{
  "env": {
    "PYTHONPATH": "./src",
    "NODE_ENV": "development",
    "RUST_LOG": "debug"
  }
}COPY

Every tool invocation starts with these env vars. Useful for projects that mix stacks.

1. Committing API keys in settings.json

The classic. If you need a secret, reference an environment variable, never inline it:

{
  "env": {
    "OPENAI_API_KEY": "$OPENAI_API_KEY"
  }
}COPY

Your shell resolves the variable at invocation time — the key never sits in your repo.

2. Using wildcard permissions

"Bash(*)" feels convenient until a hallucinated sudo rm -rf wipes your node_modules (and your weekend). Allowlist specific patterns.

3. Forgetting to gitignore settings.local.json

Always add it to .gitignore. It is designed to hold local-only overrides — your personal API keys and paths specific to your laptop have no business in a team repo.

4. Blocking hooks that break the session

If a PreToolUse hook takes 30 seconds to run, the entire session stalls. Keep hooks under 2s. For heavier checks, use PostToolUse (async) or defer to CI.

You now have a working .claude/. The next two pieces that compound this setup:

• Install the MCP Buddy server — if you are missing the terminal pet ecosystem, our MCP guide walks you through the 5-minute install.
• Explore Claude Code's hidden features — KAIROS, ULTRAPLAN, and the Undercover Mode that surfaced in the March 2026 source leak.
• Find your account UUID — some of the settings above reference your user ID for personalization.

Questions or battle-tested snippets of your own? Check your own buddy on claudebuddy.art and join the discussion under any article.

Can I share my .claude/ folder across multiple projects?

Put shared settings in ~/.claude/settings.json (user scope). Anything project-specific should stay in .claude/settings.json. For slash commands you want everywhere, put them in ~/.claude/commands/.

Does .claude/ work with IDE extensions like Cursor or VS Code?

The .claude/ folder is specific to Claude Code. Cursor has its own .cursorrules system. Claude Code's VS Code extension respects the same folder as the CLI, so settings are shared automatically.

What happens if settings.json has a syntax error?

Claude Code prints a validation error on startup and falls back to defaults for the invalid section. A quick way to verify before committing: open the file and check JSON parses (cat .claude/settings.json | jq .).

How do I debug which permissions are actually applied?

Start a session and ask Claude "Show me your current permissions" — it will list the merged effective set across all three scopes. You can also toggle --verbose on launch to see the resolution chain.

Can I override Claude Code's built-in slash commands?

Yes. If you create .claude/commands/help.md, it takes priority over the built-in /help. Use this carefully — you lose the default behavior until you remove your override.