Config

What CLAUDE.md does

Claude automatically reads CLAUDE.md files at session start. It is your way to give Claude persistent context about your project without repeating yourself every session.

• ·Place it in the repo root for project-wide context.
• ·You can also place CLAUDE.md in subdirectories for component-specific context.

What to put in it

Think of CLAUDE.md as onboarding notes for Claude — the same things you would tell a new developer joining your project.

# Project context
This is a Next.js app that does X for Y audience.

# Tech stack
- Next.js 15 App Router
- TypeScript strict mode
- Tailwind CSS
- Postgres via Prisma

# Key commands
- Dev: npm run dev
- Test: npm test
- Build: npm run build

# Conventions
- Use server components by default
- Client components in /components/client/
- Never commit .env files

# Do not
- Modify the /migrations folder without asking
- Change auth logic without a review comment

Keep it focused

CLAUDE.md should be concise and high-signal. Every line takes up context window. If it gets long, trim what Claude does not actually need.

• ·Aim for under 100 lines for most projects.
• ·Separate concerns into subdirectory CLAUDE.md files if needed.

Let Claude help write it

Ask Claude to draft your CLAUDE.md from your codebase.

claude "read this repo and write a CLAUDE.md that captures what a new dev would need to know"

How permissions work

Claude Code asks for permission before performing actions it is not certain about — running commands, writing files, making network requests. You can approve once, always, or deny.

Approve for session vs always

When prompted, you can allow an action for the current session only, or always allow it. "Always" writes a rule to your settings.

• ·"Always allow" is convenient but reduces oversight — use it for trusted, low-risk operations.
• ·Review your always-allow rules periodically.

View and edit permissions

Use /permissions to see and modify what is currently allowed.

/permissions

Skip permissions for automation

In trusted CI or scripted contexts, skip all permission prompts.

claude --dangerously-skip-permissions "run the test suite and fix failures"

• ·Only use this in environments you control.
• ·Claude can run commands, write files, and make requests without asking.

What tools Claude has

Claude Code has tools like Read, Edit, Write, Bash, Glob, Grep, and others. By default, all are available (subject to permission prompts).

Restrict to read-only for audits

If you want Claude to explore and explain but not change anything, limit it to read-only tools.

claude --allowedTools "Read,Glob,Grep" "audit the security of the auth module"

Common tool sets

Useful combinations for different contexts.

# Read-only (exploration, audit)
claude --allowedTools "Read,Glob,Grep"

# Edit but no shell
claude --allowedTools "Read,Edit,Write,Glob,Grep"

# Everything including bash
claude --allowedTools "Bash,Read,Edit,Write,Glob,Grep"

In CLAUDE.md

You can document tool expectations in your CLAUDE.md to guide Claude without hard restrictions.

• ·Hard restrictions via --allowedTools take precedence over CLAUDE.md guidance.

Settings file location

Claude Code stores settings in a JSON file. Open it via /config or find it at ~/.claude/settings.json.

/config

What you can configure

Settings let you control defaults: model, theme, permission rules, always-allow lists, and more.

• ·Changes in /config are written to settings.json.
• ·You can edit the file directly for advanced configuration.

Hooks

Hooks let you run shell commands automatically in response to Claude Code events — before a tool runs, after a response, on session start, etc.

// Example in settings.json:
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "echo \"Running bash command: $CLAUDE_TOOL_INPUT\""
        }]
      }
    ]
  }
}

• ·Hooks are powerful for logging, auditing, or blocking specific operations.
• ·See docs for full event list: PreToolUse, PostToolUse, Notification, Stop, SubagentStop.

Why context matters

Claude Code has a context window limit. As sessions grow long, older content gets pushed out or quality degrades. Managing context keeps sessions productive.

Check context usage

See how much of the context window is in use.

/context

Compact when getting long

Use /compact to summarize the conversation and free up context space.

/compact

• ·Claude summarizes the conversation so far.
• ·You can continue the session with a much smaller footprint.

Clear and restart

For a completely fresh start within the same session.

/clear

Use CLAUDE.md to reduce repetition

Instead of re-explaining your project every session, put stable context in CLAUDE.md so Claude starts informed.

• ·This is the most impactful thing you can do for context efficiency.

Resume vs restart

Use -c or --resume to continue a session rather than re-explaining context from scratch.

claude -c