Claude Settings: The Complete Guide

Used for all main tasks: code writing, analysis, planning, complex reasoning.

"model": "claude-sonnet-4-6"   // Best balance: speed + quality
"model": "claude-opus-4-6"    // Maximum capability (slower, higher cost)
"model": "claude-haiku-4-5-20251001"  // Fastest, cheapest (simple tasks only)

Used automatically for lightweight operations: summarisation, quick lookups, tool call routing. Keeping this as Haiku saves tokens without sacrificing quality on your main work.

"smallFastModel": "claude-haiku-4-5-20251001"

Claude asks for approval before every tool call — every file edit, every bash command. Safe but slow and disruptive.

Commands matching the pattern run automatically. Claude stops and asks only for commands not in your allow list.

Commands matching deny patterns are blocked entirely — Claude cannot run them even if you ask. Your last line of defence.

"permissions": {
  "allow": [
    "bash(git:*)", "bash(npm:*)", "bash(npx:*)",
    "bash(node:*)", "bash(python3:*)", "bash(pip3:*)",
    "bash(ls:*)", "bash(cat:*)", "bash(echo:*)",
    "bash(mkdir:*)", "bash(cp:*)", "bash(mv:*)",
    "read(*)", "edit(~/Projects/**)"
  ],
  "deny": [
    "bash(rm -rf:*)", "bash(sudo:*)",
    "bash(curl * | bash:*)", "bash(eval:*)"
  ]
}

"permissions": {
  "allow": [
    "bash(ls:*)", "bash(cat:*)", "bash(echo:*)",
    "bash(grep:*)", "bash(find:*)",
    "read(*)", "edit(~/Documents/**)", "edit(~/Desktop/**)"
  ],
  "deny": [
    "bash(rm:*)", "bash(sudo:*)", "bash(curl:*)",
    "bash(wget:*)", "bash(chmod:*)"
  ]
}

"permissions": {
  "allow": [
    "bash(ls:*)", "bash(cat:*)", "bash(grep:*)",
    "bash(git log:*)", "bash(git diff:*)", "bash(git status:*)",
    "read(*)"
  ],
  "deny": [
    "bash(git commit:*)", "bash(git push:*)",
    "edit(*)", "bash(rm:*)", "bash(mv:*)",
    "bash(sudo:*)", "bash(curl:*)"
  ]
}

Environment variables available: $TOOL_NAME, $TOOL_INPUT_PATH (JSON file with tool args)

Use for: approval gates, audit logging, rate limiting, validating file paths before edits

Additional env var: $TOOL_OUTPUT_PATH (JSON file with result)

Use for: auto-running tests after code changes, committing after edits, notifying on completion

Use for: desktop notifications, Slack alerts, sound cues — so you can walk away and come back

Use for: session summaries, cleanup tasks, end-of-session logs

"notification": [{
  "command": "osascript -e 'display notification "Claude needs your attention" with title "Claude" sound name "Glass"'"
}]

"pre_tool_call": [{
  "command": "echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] TOOL: $TOOL_NAME INPUT: $(cat $TOOL_INPUT_PATH)" >> ~/claude-audit.log"
}]

"post_tool_call": [{
  "command": "if echo "$TOOL_NAME" | grep -q 'write'; then FILEPATH=$(cat $TOOL_INPUT_PATH | python3 -c "import json,sys; print(json.load(sys.stdin).get('path',''))" 2>/dev/null); if echo "$FILEPATH" | grep -q '.test.'; then cd $(dirname $FILEPATH) && npm test --testPathPattern=$(basename $FILEPATH) 2>&1 | tail -5; fi; fi"
}]

Checks if Claude wrote to a .test.* file, then runs just that test file automatically.

"pre_tool_call": [{
  "command": "if [ "$TOOL_NAME" = "edit" ]; then FILEPATH=$(cat $TOOL_INPUT_PATH | python3 -c "import json,sys; print(json.load(sys.stdin).get('path',''))"); if echo "$FILEPATH" | grep -qE "(production|prod.env|.env.prod)"; then echo "BLOCKED: Cannot edit production files" >&2; exit 1; fi; fi"
}]

"stop": [{
  "command": "echo "[$(date)] Claude session ended" >> ~/claude-sessions.log"
}]

"env": {
  "GITHUB_TOKEN": "ghp_abc123realtoken"  // ❌ Plaintext secret in config
}

// In ~/.claude/settings.json:
"env": {
  "GITHUB_TOKEN": "$GITHUB_TOKEN",
  "ANTHROPIC_API_KEY": "$ANTHROPIC_API_KEY"
}

// In ~/.zshrc or ~/.bash_profile:
export GITHUB_TOKEN="ghp_abc123realtoken"
export ANTHROPIC_API_KEY="sk-ant-..."

This way the secret lives in your shell profile (which you can exclude from backups) not in settings.json (which might sync).

When true, Claude adds “Co-Authored-By: Claude” to every commit message it writes. Useful for transparency in team repos. Set to false for personal/private projects where you'd rather not expose your tooling.

"includeCoAuthoredBy": true   // Recommended for team repos
"includeCoAuthoredBy": false  // For private/personal repos

How many days of conversation history to retain locally. Higher values mean Claude can reference older context across sessions. Lower values reduce disk usage and keep Claude's memory focused on recent work.

"cleanupPeriodDays": 30   // Recommended: 30 for active projects
"cleanupPeriodDays": 7    // For privacy-sensitive or shared machines
"cleanupPeriodDays": 90   // For long-running research projects

I am a software developer. Please be helpful and concise.

Adds no real value — Claude already tries to be helpful and concise.

I am a senior Python/FastAPI engineer at a fintech startup.

Context:
- Stack: Python 3.12, FastAPI, PostgreSQL, SQLAlchemy, pytest
- We use async/await throughout — never suggest synchronous patterns
- Our API follows OpenAPI 3.1 — always include type hints and docstrings
- We run Ruff for linting (pyproject.toml config)

Communication preferences:
- Lead with the answer, then explain
- Flag security issues proactively even when not asked
- For complex changes, show a before/after diff, not just the new code
- Use British English spelling

What to avoid:
- Never suggest JavaScript/TypeScript alternatives when I ask Python questions
- Don't add requirements.txt changes without explaining why

Claude automatically saves: your name and role, recurring preferences it notices, project context you've mentioned, correction patterns (if you frequently correct the same thing, Claude saves to avoid repeating).

You can view and edit your memory at any time. Regularly review it and delete outdated entries. Tell Claude explicitly what to remember: “Remember that I prefer TypeScript over JavaScript for all my projects.”

# Tell Claude what to remember:
"Remember: I work in the healthcare domain. All data examples
should use synthetic/fake patient data, never real examples."

# Tell Claude to forget something:
"Please forget that you remembered my old company name —
I changed jobs in January 2026."

Shared accounts, privacy-sensitive environments, or when you want each conversation to be fully independent. Go to Settings → Memory → toggle off. Existing memories are not deleted, just not used.

Enables Claude to “think out loud” before responding — visible reasoning chain. Best for: complex decisions, multi-step planning, math-heavy tasks. Slower and higher cost per message. Best practice: Leave enabled. You can request it per-message: “Think step by step before answering.”

Claude suggests follow-up questions at the end of responses. Useful when you are exploring a topic. Can be distracting in focused coding workflows. Best practice: Turn off if you find yourself ignoring them — they consume UI space.

Allows Claude to search the web during conversations. Critical for current events, recent API changes, and anything that may have changed since Claude's training cutoff. Best practice: Always leave on. You can suppress it per-message: “Answer from your training data only, don't search.”

model              → Main model (sonnet recommended)
smallFastModel     → Sub-task model (haiku recommended)
mcpServers         → External tools Claude can use
permissions.allow  → Commands that run without asking
permissions.deny   → Commands that are blocked entirely
hooks.pre_tool_call  → Runs before any tool call
hooks.post_tool_call → Runs after any tool call
hooks.notification   → Runs when Claude needs you
hooks.stop           → Runs when session ends
env                → Environment variables injected per session
includeCoAuthoredBy → Add Claude attribution to commits
cleanupPeriodDays  → How long to keep conversation history

Profile → Custom Instructions  → Global system prompt
Profile → Memory               → Cross-conversation facts
Features → Extended Thinking   → Visible reasoning chain
Features → Web Search          → Real-time internet access
Features → Suggested Prompts   → Follow-up suggestions
Appearance                     → Dark/light mode, font size
Notifications                  → Email digest settings