Explore the .claude Directory

The full directory tree

When you work with Claude Code in a project, a .claude/ folder is created at the project root. Here is everything it can contain:

File by file

.claude/CLAUDE.md — project instructions (committed)

This is the most important file. Every time a session starts, Claude reads it automatically. Use it to describe the project, its conventions, forbidden patterns, and preferred tools — so Claude always has the right context.

# Project: Inventory API

## Stack
- Node.js 20, Express 5, PostgreSQL 16
- Tests: Vitest — run with `npm test`
- Lint: ESLint + Prettier — run with `npm run lint`

## Conventions
- All DB queries must use parameterised statements
- Never commit .env files
- Feature branches follow: feat/<ticket-id>-short-description

.claude/settings.json — shared project config (committed)

Holds hooks, permission rules, and other project-wide settings. Because it is committed, every team member gets the same Claude behaviour automatically.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/lint.sh"
          }
        ]
      }
    ]
  }
}

.claude/settings.local.json — private overrides (gitignored)

Same format as settings.json but gitignored. Use it for personal preferences — your own extra hooks, local path overrides, or developer-only permission rules — that you don't want to push to the repo.

.claude/hooks/ — shell scripts called by hook events

Store your hook shell scripts here. Reference them from settings.json using the $CLAUDE_PROJECT_DIR variable so paths stay correct regardless of where Claude is run from.

#!/bin/bash
# .claude/hooks/lint.sh
FILE=$(cat | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" == *.ts || "$FILE" == *.tsx ]]; then
  npx eslint --fix "$FILE" 2>/dev/null
fi

exit 0

.claude/agents/ — custom sub-agent definitions

Each Markdown file here defines a custom sub-agent with a YAML frontmatter header. Claude Code spawns the agent when instructed, giving it a focused role and optional tool restrictions.

---
name: code-reviewer
description: Reviews code for security issues and code quality
tools:
  - Read
  - Grep
  - Glob
---

You are a focused code reviewer. Scan for:
- Security vulnerabilities (SQL injection, XSS, hardcoded secrets)
- Missing error handling
- Performance anti-patterns

Report findings clearly with file and line references.

.claude/skills/ — custom slash-command definitions

Each file becomes a /skill-name slash command inside Claude Code. Use $ARGUMENTS as a placeholder for anything typed after the command name. Invoke with: /add-types src/utils/helpers.js

---
name: add-types
description: Add TypeScript types to a JavaScript file
---

Convert the file at $ARGUMENTS to TypeScript:
1. Add explicit types to all function parameters and return values
2. Replace `any` with proper types where possible
3. Keep the same logic — only add type annotations, no refactoring

At a glance

Git hygiene

Add this block to your project's .gitignore to keep private files out of version control while committing the shared config:

# Claude Code — keep private settings out of Git
.claude/settings.local.json

# Commit everything else in .claude/ to share with the team
# .claude/CLAUDE.md
# .claude/settings.json
# .claude/hooks/
# .claude/agents/
# .claude/skills/

Before you continue

• CLAUDE.md — project instructions loaded at every session start.
• settings.json — shared hooks and permissions; settings.local.json for private overrides.
• hooks/, agents/, and skills/ extend automation, delegation, and slash commands.
• Commit .claude/ minus settings.local.json so the team shares the same setup.
• Next lesson: Claude Code in VS Code — integrate directly into your editor.

What's Next

You know your way around the .claude/ directory. Next: integrate Claude Code directly into your VS Code editor for an in-editor experience.