Claude Code

~/.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

---
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

# 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/

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…

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

<!-- .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

# 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

---
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…

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

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

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

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

{
  "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
          }
        ]
      }
    ]
  }
}

{
  "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'"
          }
        ]
      }
    ]
  }
}

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

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

"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)

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

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

# 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...]

# 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

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

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

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

## 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/`

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