Best Claude Code Configuration: The Complete Settings Guide (2026)

The Best Claude Code Configuration in One Paragraph

The best Claude Code configuration combines four files: a project .claude/settings.json with explicit permissions and a Sonnet 4.6 model, a root CLAUDE.md with stack context and commands, a .mcp.json registering the tools your team uses, and PreToolUse hooks in .claude/hooks/ for anything destructive. Anything less is either unsafe or annoying.

The 5-Layer Configuration Hierarchy

Claude Code reads configuration from five sources, merged in a specific priority order. According to the official Claude Code docs at code.claude.com/docs/en/settings, array fields like permissions.allow merge across layers instead of overwriting, so team rules and personal rules coexist.

The Starter settings.json (Copy This)

Drop this into .claude/settings.json at your repo root. It covers the fields that matter on day one: schema, model, permissions, env, statusline, and hooks scaffolding.

{
  "$schema": "https://code.claude.com/schemas/settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm run:*)",
      "Bash(npm test:*)",
      "Bash(bun run:*)",
      "Bash(pnpm run:*)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm publish)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(curl:*| sh)",
      "Read(.env)",
      "Read(.env.*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "0",
    "NODE_ENV": "development"
  },
  "statusLine": {
    "type": "command",
    "command": ".claude/statusline.sh"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/guard-bash.sh"
          }
        ]
      }
    ]
  }
}

The $schema field enables autocomplete in VS Code and JetBrains. That alone catches ~90% of typos before you hit save.

Permissions: Allow, Deny, Ask, defaultMode

The permissions object is the single highest-leverage setting in Claude Code. Rules are evaluated in order: deny first, then ask, then allow. First match wins. Deny always takes precedence.

Permission Mode Comparison

Rule Patterns You Will Actually Use

• ●Exact match: Bash(git status) allows only that exact command.
• ●Prefix wildcard: Bash(npm run:*) allows any npm run subcommand.
• ●Full tool: Read allows every file read. Scope it if you have secrets on disk.
• ●File-scoped: Read(.env) in deny blocks env file reads even when Read is allowed.

Model Selection: Which ID to Set in 2026

The model field accepts a full model ID or an alias. For most teams in 2026, Claude Sonnet 4.6 (claude-sonnet-4-6) is the default. It costs a fraction of Opus per token while matching Opus on most coding benchmarks.

Pin your daily driver at the project level. Override with /model inside Claude Code when a task actually needs Opus. Do not default to Opus globally. Most tasks do not need it and the token bill piles up fast.

Environment Variables and the env Key

The env key in settings.json sets environment variables that Claude Code reads on startup. Use it for feature flags, API endpoints, and telemetry toggles. Never put secrets here because the file is checked into git.

Hooks: The Safety Net Permissions Cannot Replace

Hooks run shell commands at specific lifecycle events. PreToolUse is the most valuable hook type because it sees every tool call before execution and can block, warn, or allow it. Unlike permission rules, hooks can do real validation: parameter inspection, path checks, risk scoring.

Minimum Viable guard-bash.sh

#!/usr/bin/env bash
# .claude/hooks/guard-bash.sh
# Read the tool call from stdin
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# Hard deny dangerous patterns
if echo "$cmd" | grep -qE 'rm -rf|sudo|curl.*\| ?sh|:\(\)\{'; then
  echo "{\"decision\": \"deny\", \"reason\": \"Blocked dangerous pattern\"}"
  exit 0
fi

# Ask before git push
if echo "$cmd" | grep -qE '^git push'; then
  echo "{\"decision\": \"ask\", \"reason\": \"git push is reviewed manually\"}"
  exit 0
fi

# Default: allow
echo "{\"decision\": \"allow\"}"

Make the file executable with chmod +x .claude/hooks/guard-bash.sh and register it under hooks.PreToolUse with matcher "Bash". For a full list of 26 lifecycle events, see our Claude Code Hooks Guide.

MCP Servers: .mcp.json at the Repo Root

Model Context Protocol servers extend Claude Code with tools that the built-in set does not cover. GitHub, Linear, Sentry, Stripe, browser automation, database connectors. Register them with claude mcp add <name> <command>, which writes to .mcp.json.

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/devdb"
      ]
    }
  }
}

Use environment variable interpolation for secrets instead of hardcoding them. Claude Code expands ${VAR} from the parent shell at startup. For a deeper walkthrough, see our Claude Code MCP Servers Guide.

Statusline: Show Context You Actually Care About

The statusline is a shell script that prints a one-line status bar at the bottom of Claude Code. The default one is fine. A custom one showing your current git branch, active model, and token budget is better.

#!/usr/bin/env bash
# .claude/statusline.sh
input=$(cat)
model=$(echo "$input" | jq -r '.model.id')
cwd=$(echo "$input" | jq -r '.workspace.current_dir')
branch=$(git -C "$cwd" branch --show-current 2>/dev/null || echo "-")
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')

printf "[%s] %s @ %s ($%.2f)" "$branch" "$model" "$(basename "$cwd")" "$cost"

Claude Code pipes a JSON payload into the script on stdin. Fields include model.id, workspace.current_dir, and cost.total_cost_usd. Keep the output under one line. Statusline refreshes are synchronous.

The Complete .claude/ Directory Layout

A mature Claude Code project has a predictable structure under .claude/. Slash commands, hooks, subagents, and skills each have a dedicated subdirectory. This makes behavior discoverable and reviewable in PRs.

.
├── CLAUDE.md                # project context (checked in)
├── .mcp.json                # MCP server registry (checked in)
└── .claude/
    ├── settings.json        # team config (checked in)
    ├── settings.local.json  # personal config (gitignored)
    ├── statusline.sh        # custom statusline script
    ├── commands/            # custom slash commands
    │   ├── ship.md
    │   └── review.md
    ├── hooks/               # PreToolUse, PostToolUse scripts
    │   ├── guard-bash.sh
    │   └── format-on-save.sh
    ├── agents/              # custom subagents
    │   └── code-reviewer.md
    └── skills/              # custom skills (if used)
        └── seo-2026/
            └── SKILL.md

Add this to .gitignore so personal overrides stay out of the repo: .claude/settings.local.json.

5 Configuration Mistakes That Cost Us Days

Every item below burned real hours at KaiShips. Skip the tuition by copying the lesson.

Verify Your Configuration in 60 Seconds

Once your settings.json is in place, run a quick check. Do not commit and push without confirming the config actually loads.

• ●Run /config inside Claude Code. It prints the merged configuration. Confirm model, permissions, and hooks look right.
• ●Try a denied command. Ask Claude to run rm -rf /tmp/foo. It should refuse. If it does not, your deny list is not wired up.
• ●Check MCP servers. Run claude mcp list to confirm every registered server started successfully.
• ●Watch the statusline. If it is blank or shows an error, the script is missing, non-executable, or taking too long.

Claude Code Configuration FAQ

Short answers to the questions we hear most often from teams adopting Claude Code in 2026.

Keep Going

Configuration is the foundation. These companion guides layer on top of what you just built.