Last updated: 2026-06-07

Claude Code Configuration Options the Official Docs Don't Cover

The .claude/settings.json file is far more powerful than the official documentation suggests. Community discovery has surfaced dozens of options that meaningfully change how Claude Code behaves — from skipping permission prompts to injecting environment variables and hooking into every tool call.

The settings.json file: your real control panel

Claude Code reads .claude/settings.json (project-level) and ~/.claude/settings.json (global) at startup. The official docs explain a handful of top-level keys, but the file supports many more. Project-level settings override global ones, so you can lock down dangerous commands site-wide while allowing them in a specific repo.

The most impactful undocumented fields:

autoApprove — an array of bash command prefixes Claude can run without prompting. Example: ["npm test", "git status", "git diff"]. Saves dozens of confirmation clicks in long sessions.
bash.allowedCommands — a finer-grained allowlist that supports glob patterns: ["git *", "npm run *", "ls *"]. Commands not matching any pattern always prompt.
model — override the default model at the project level. Useful for locking a cost-sensitive project to Haiku while your main work uses Sonnet.
disableToolUseStreaming — set to true to disable streaming for tool calls. Useful when a proxy or corporate firewall mangles chunked responses.

Hooks: intercept every tool call

The hooks key is arguably the most powerful undocumented feature. It lets you register scripts that run before or after any Claude Code tool event. The hook system fires on PreBash, PostBash, PreEdit, PostEdit, PreWrite, and several others.

Example settings.json hooks configuration:

{
  "hooks": {
    "PreBash": [{"command": "python .claude/hooks/validate_bash.py"}],
    "PostEdit": [{"command": "node .claude/hooks/lint_on_edit.mjs"}]
  }
}

The hook script receives the event payload as JSON on stdin and can exit non-zero to block the action. This is how teams enforce security policies (block rm -rf), auto-run linters, or log every file Claude touches to an audit trail.

Environment variable injection

You can inject environment variables into Claude Code's subprocess environment via the env key in settings.json. This is useful for setting NODE_ENV=test, pointing to a local API mock, or providing credentials without exporting them in your shell profile. Variables set here take precedence over the shell environment.

Where to find more

The best discovery method is reading Claude Code changelog entries closely — new settings options often appear as "internal infrastructure improvements." The community maintains lists in the HN thread "Everything you can configure that the docs don't tell you" (326 points, June 2026) and in GitHub searches for .claude/settings.json in public repos. See also our Claude Cowork FAQ for more commonly asked configuration questions.