Claude Code

Claude Code Setup

Configuration and customization reference for Claude Code — skills, commands, agents, hooks, permissions, and MCP servers.

When to Activate

• Setting up skills, slash commands, or agents in a new project or globally
• Writing or debugging hook configurations in settings.json
• Configuring tool permissions to reduce approval prompts
• Registering or troubleshooting an MCP server
• Writing CLAUDE.md project instructions
• Asking how Claude Code loads context or resolves settings
• Integrating Claude Code with VS Code or JetBrains

Directory Layout

~/.claude/                        # global — applies to all projects
├── settings.json                 # global permissions, hooks, env vars
├── CLAUDE.md                     # global instructions read at every session
├── skills/
│   └── <name>/skill.md           # or <name>.md (flat)
├── agents/
│   └── <name>.md
└── commands/
    └── <name>.md

<project>/
├── CLAUDE.md                     # project instructions (commit this)
└── .claude/
    ├── settings.json             # project permissions + hooks (commit this)
    ├── settings.local.json       # personal overrides (gitignore this)
    ├── skills/                   # project-scoped skills
    ├── agents/                   # project-scoped agents
    └── commands/                 # project-scoped commands

Settings are merged: settings.local.json overrides .claude/settings.json overrides ~/.claude/settings.json.

Skills

Skills are markdown files that Claude loads contextually when the task matches.

File Format

---
name: my-skill
description: One keyword-dense sentence used for activation matching.
---

# Title

One-sentence intro.

## When to Activate
- Verb-leading trigger condition
- Another trigger condition

## Content sections…

## Checklist
- [ ] At least one item

Installation

# Single skill (global)
cp -r skills/my-skill ~/.claude/skills/

# All skills from a library
cp -r skills/* ~/.claude/skills/

# Project-scoped (available only in this project)
cp -r skills/my-skill .claude/skills/

How Skills Load

Claude matches the task description against the description frontmatter field and the ## When to Activate bullet points. No manual invocation needed — skills activate automatically. The name field must match the folder name (or file stem for flat layout).

Slash Commands

Slash commands are prompt templates invoked with /command-name in the Claude Code prompt.

File Format

Do the thing the user asked.

## Instructions

1. First step — use `$ARGUMENTS` for any text the user typed after the command name
2. Second step
3. Output format…

$ARGUMENTS is replaced with everything the user typed after the command name:

/my-command foo bar   →   $ARGUMENTS = "foo bar"
/my-command           →   $ARGUMENTS = ""

Examples

<!-- .claude/commands/summarize.md -->
Summarize the file at $ARGUMENTS.

Read the file, identify the top 3 key points, and return them as a numbered list.
Each point should be one sentence.

<!-- .claude/commands/fix-issue.md -->
Fix GitHub issue #$ARGUMENTS in this repository.

1. Run `gh issue view $ARGUMENTS` to read the issue
2. Find the relevant code
3. Implement the fix
4. Write or update tests
5. Summarize what changed

Installation

# Global (available in all projects)
cp .claude/commands/my-command.md ~/.claude/commands/

# Project-only (stays in this repo)
# Already in .claude/commands/ — no copy needed

Agents

Agents run in an isolated context window with their own tool set and system prompt.

File Format

---
name: my-agent
description: Use this agent when… (triggers auto-delegation)
tools: Read, Grep, Glob, Bash
model: sonnet
color: blue
---

You are a … agent. Your job is to …

## Methodology
Step-by-step approach…

## Output Format
What the agent should return…

Frontmatter Fields

Available Tools

Read, Write, Edit, Bash, Glob, Grep,
WebFetch, WebSearch,
Agent, TaskCreate, TaskUpdate, TaskList,
NotebookEdit

Principle of least privilege: a read-only audit agent should declare tools: Read, Grep, Glob, Bash — no Write or Edit.

Installation

# Global
cp .claude/agents/my-agent.md ~/.claude/agents/

# Project-only
# Already in .claude/agents/ — committed with the repo

Hooks

Hooks run shell commands automatically in response to Claude Code events.

Settings Structure

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName",
        "hooks": [
          {
            "type": "command",
            "command": "shell command here",
            "timeout": 10,
            "async": false
          }
        ]
      }
    ]
  }
}

Hook Events

Hook Environment Variables

Common Hook Patterns

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATH",
            "if": "Write(**/*.ts)"
          },
          {
            "type": "command",
            "command": "black $CLAUDE_FILE_PATH",
            "if": "Write(**/*.py)"
          }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "eslint --fix $CLAUDE_FILE_PATH",
            "if": "Edit(**/*.ts)"
          },
          {
            "type": "command",
            "command": "ruff check --fix $CLAUDE_FILE_PATH",
            "if": "Edit(**/*.py)"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[$(date)] $CLAUDE_TOOL_INPUT\" >> .claude/command.log",
            "async": true
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "git status" }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python ~/tools/notify.py 'Claude finished'",
            "async": true
          }
        ]
      }
    ]
  }
}

The if field inside a hook entry is a secondary glob filter on top of the matcher. Use it to handle multiple file types under one matcher block.

async: true — hook runs in background; Claude doesn't wait for it. Use for logging, notifications.
async: false (default) — Claude waits for the hook to complete before continuing. Use for formatters, validators.

PreToolUse Blocking

A PreToolUse hook with exit code 2 blocks the tool call and surfaces the hook's stdout as an error message to Claude.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'echo $CLAUDE_TOOL_INPUT | grep -q \"rm -rf\" && { echo \"rm -rf blocked\"; exit 2; } || exit 0'"
          }
        ]
      }
    ]
  }
}

Settings and Permissions

Settings Files

~/.claude/settings.json           # global defaults
<project>/.claude/settings.json   # project (commit — shared with team)
<project>/.claude/settings.local.json  # personal overrides (gitignore)

Permissions

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Write(**/*.ts)",
      "Write(**/*.py)",
      "Bash(docker compose up *)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(rm -rf *)"
    ]
  }
}

Permission string syntax:

"Bash(command prefix *)"   — allow bash commands matching the prefix
"Write(**/*.ext)"          — allow writing files matching the glob
"Read(**/*)"               — allow reading any file
"*"                        — allow everything (use in dev only)

Deny rules take precedence over allow rules.

Environment Variables

{
  "env": {
    "NODE_ENV": "development",
    "PYTHONPATH": "/app/src",
    "LOG_LEVEL": "debug"
  }
}

Model Override

{
  "model": "claude-opus-4-7"
}

MCP Servers

MCP (Model Context Protocol) servers expose tools and resources to Claude Code.

Registration

# Register globally (available in all projects)
claude mcp add -s user <name> <command> [args...]

# Register for current project only (stored in .claude/mcp.json)
claude mcp add -s project <name> <command> [args...]

# Register locally (personal, stored in .claude/mcp.local.json — gitignored)
claude mcp add -s local <name> <command> [args...]

Examples

# Python MCP server
claude mcp add -s user memory_map \
  /home/user/memory_map/venv/bin/python \
  /home/user/memory_map/server.py

# Node MCP server
claude mcp add -s user filesystem \
  npx @modelcontextprotocol/server-filesystem /tmp

# With environment variables
claude mcp add -s project my-server \
  --env API_KEY=abc123 \
  node server.js

Management

claude mcp list                  # list all registered servers
claude mcp remove <name>         # unregister a server
claude mcp get <name>            # show config for one server

MCP config is stored as JSON:

{
  "mcpServers": {
    "memory_map": {
      "command": "/home/user/memory_map/venv/bin/python",
      "args": ["/home/user/memory_map/server.py"]
    }
  }
}

CLAUDE.md

CLAUDE.md files inject persistent instructions into every session.

Load Order

~/.claude/CLAUDE.md              # always loaded (global)
<project>/CLAUDE.md              # loaded when in that project
<project>/src/CLAUDE.md          # loaded when working in src/ (scoped)

All matching files are concatenated — lower-level files extend rather than replace.

What to Put in CLAUDE.md

## Session Setup
<!-- Steps Claude must run at session start -->
1. Run `load_memory` with the current working directory
2. Run `suggest_history` with the current working directory and the user's first message

## Project Context
<!-- What the project is and how it's structured -->
This is a FastAPI service that handles payment processing.
Main entry point: src/main.py. Tests: tests/.

## Conventions
<!-- Non-obvious decisions that Claude should follow -->
- Use `snake_case` for all Python identifiers
- Never commit directly to main — always branch
- Database migrations live in alembic/versions/

## Commands
<!-- Common tasks Claude should know how to run -->
- Run tests: `pytest tests/ -x`
- Start dev server: `uvicorn src.main:app --reload`
- Lint: `ruff check src/`

Avoid documenting things derivable from reading the code. Focus on: session setup, non-obvious conventions, workflow automation steps, and external context Claude can't infer.

IDE Integration

VS Code

Install the Claude Code extension from the VS Code marketplace. After installing:

Ctrl+Shift+P → "Claude Code: Open"   — open Claude Code panel
Ctrl+Shift+P → "Claude Code: Focus"  — focus without opening a new window

The extension reads .claude/settings.json from the workspace root automatically.

JetBrains (IntelliJ, PyCharm, WebStorm, etc.)

Install the Claude Code plugin from the JetBrains Marketplace. After installing:

Tools → Claude Code → Open Session

Both IDEs support inline diff review, file context injection, and running Claude Code commands from within the editor.

Red Flags

• Secrets in CLAUDE.md — CLAUDE.md is read into every session context and often committed to git; never put API keys, passwords, or tokens there; reference environment variables instead
• Hooks with no timeout set — a hook that hangs (network call, blocked process) suspends Claude Code indefinitely; always set "timeout": N seconds on every hook command
• "deny": ["Bash(*)"] blocking all shell access — over-broad deny rules prevent running tests, linters, and build tools; scope deny rules to the specific dangerous patterns (e.g., rm -rf, git push --force)
• MCP server registered with --scope project for personal tools — project-scoped MCP servers are stored in the repo and apply to everyone who checks it out; use --scope user for personal servers
• PostToolUse hook on Write that itself uses Write — a write hook that writes files triggers another write event, causing infinite recursion; hooks must not trigger the same event they listen to
• No matcher on broad hooks — a hook with an empty or missing matcher fires on every single tool use; always specify a matcher to limit execution to the tool or pattern that needs it
• CLAUDE.md with per-feature implementation notes — CLAUDE.md is for team-wide project conventions; per-feature context belongs in inline comments, ADRs, or feature-specific docs alongside the code

Checklist

• Skills installed to ~/.claude/skills/ (global) or .claude/skills/ (project-scoped)
• Each skill has name, description frontmatter and a ## When to Activate section
• Slash commands installed to ~/.claude/commands/ or .claude/commands/; use $ARGUMENTS for user input
• Agents declare minimum required tools — read-only agents exclude Write and Edit
• Agent description written as "Use this agent when…" for correct auto-delegation
• settings.json committed to .claude/ for shared project permissions; personal overrides in settings.local.json (gitignored)
• Formatter/linter hooks use async: false so files are fixed before Claude continues
• Logging/notification hooks use async: true so they don't block Claude
• PreToolUse safety hooks exit 2 to block, 0 to allow
• MCP servers registered with correct scope: user for personal tools, project for shared
• CLAUDE.md covers session setup steps, non-obvious conventions, and key commands — not things readable from the code
• Global ~/.claude/CLAUDE.md contains only instructions that apply across all projects