There's a specific moment most Claude Code users hit: you want to tweak some behavior — enable PowerShell support, extend a Bash timeout, or run headlessly in CI — and you end up digging through scattered docs trying to find the right knob to turn.
This guide gathers all of those knobs in one place. Claude Code exposes three layers of configuration (settings files, environment variables, and CLI flags), and understanding which layer to reach for makes the difference between a smooth workflow and a frustrating afternoon.
The Three Configuration Layers
Claude Code's settings are organized by scope. Choosing the right layer depends on how broadly you want a change to apply.
1. ~/.claude/settings.json (User-global settings)
Applies to every project on your machine. Best for personal defaults: your preferred model, theme, and permission policies that make sense across all your work.
2. .claude/settings.json (Project settings)
Applies only to the current project. You can commit this file to your repository so the whole team shares the same configuration. Project settings override user-global settings.
3. Environment variables and CLI flags (Dynamic overrides) Applied at runtime to a single invocation or shell session. Perfect for CI/CD pipelines, temporary experiments, or one-off configuration changes.
The precedence order is: CLI flags > environment variables > project settings.json > global settings.json
What You Can Configure in settings.json
Here's a practical example of a ~/.claude/settings.json setup:
{
"model": "claude-sonnet-4-6",
"theme": "dark",
"autoUpdates": true,
"permissions": {
"allow": [
"Bash(git:*)",
"Bash(npm:*)",
"Bash(node:*)",
"Read(**)",
"Write(src/**)"
],
"deny": [
"Bash(rm -rf:*)",
"Write(.env:*)"
]
},
"env": {
"NODE_ENV": "development",
"BASH_DEFAULT_TIMEOUT_MS": "300000"
}
}Key fields:
model: Default model for all sessions.claude-sonnet-4-6for most tasks,claude-haiku-4-5-20251001for lightweight work where speed matterstheme: UI theme —dark,light, orautoautoUpdates: Whether Claude Code updates itself automatically (default:true)permissions.allow: Tool patterns that run without confirmationpermissions.deny: Tool patterns that are always blocked —denytakes precedence overallowenv: Environment variables injected into every command Claude Code runs
For a deep dive into the permissions system, see Claude Code Permission Modes and Production Security Guide.
Environment Variable Reference
These can be set with export in your shell profile, or persisted via settings.json's env field.
API and Authentication
# Your Anthropic API key (required)
export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
# Use Amazon Bedrock as the backend
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1"
# AWS credentials via ~/.aws/credentials or IAM role
# Use Google Vertex AI as the backend
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-east5"
export ANTHROPIC_VERTEX_PROJECT_ID="your-project-id"Behavior Control
# Enable the PowerShell tool (Windows / WSL environments)
# Unlocks .ps1 script execution and system management commands
export CLAUDE_CODE_USE_POWERSHELL_TOOL=1
# Bash command timeout in milliseconds (default: 120000 = 2 minutes)
# Increase this for slow builds, Docker, or full test suite runs
export BASH_DEFAULT_TIMEOUT_MS=600000 # 10 minutes
# Disable update checks at startup (helpful on slow connections)
export CLAUDE_CODE_DISABLE_UPDATE_CHECK=1
# Use GitHub Copilot API (for users with an active Copilot subscription)
export CLAUDE_CODE_USE_COPILOT=1Telemetry and Debugging
# Opt out of usage telemetry
export CLAUDE_TELEMETRY_DISABLED=1
# Enable debug logging — invaluable when something behaves unexpectedly
export CLAUDE_CODE_DEBUG=1
# Write debug logs to a file instead of stderr
export CLAUDE_CODE_LOG_FILE="/tmp/claude-debug.log"CI/CD and Automation
# Force non-interactive mode (standard CI convention)
# When set, confirmation prompts are automatically skipped
export CI=1
# Skip all permission checks
# ⚠️ Only use this in fully trusted automation environments
# Never set this for local development — unintended file changes are hard to catch
export CLAUDE_CODE_SKIP_PERMISSIONS=1CLI Flag Reference
Flags apply only to the current command invocation — they're the highest-priority override and require no file editing.
# Interactive session (default)
claude
# One-shot execution
claude "Describe what this function does"
# Non-interactive / piped input (useful for scripts)
claude -p "Review this diff for issues" < changes.diff
claude --print "Suggest a better variable name for this code"
# Model selection
claude --model claude-sonnet-4-6
claude --model claude-haiku-4-5-20251001 # Faster and cheaper for simple tasks
# Session continuity
claude --continue # Resume the most recent conversation
claude --resume SESSION_ID # Resume a specific session (see: claude history)
# Permission control
claude --dangerously-skip-permissions # Skip all confirmations
claude --allowedTools "Bash,Read,Write" # Explicitly whitelist tools
# Output formats (for scripting and pipelines)
claude --output-format json # Structured JSON response
claude --output-format stream-json # Streaming JSON for incremental processing
# Miscellaneous
claude --no-update-check # Skip startup update checkConfiguration Recipes for Common Scenarios
Enabling PowerShell on Windows or WSL
If you're working on Windows natively or via WSL and need PowerShell capabilities, add this to your shell profile:
# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export CLAUDE_CODE_USE_POWERSHELL_TOOL=1Alternatively, set it permanently in settings.json:
{
"env": {
"CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
}
}For a full Windows setup walkthrough, see Claude Code Windows Native + WSL2 Complete Guide.
Fixing Bash Timeout Errors on Long Builds
If you're seeing timeout failures with next build, Docker image builds, or full test runs, the default 2-minute limit is likely the culprit.
# Extend to 10 minutes for the current session
export BASH_DEFAULT_TIMEOUT_MS=600000To apply this project-wide so teammates don't hit the same issue, add it to .claude/settings.json:
{
"env": {
"BASH_DEFAULT_TIMEOUT_MS": "600000"
}
}Automated Code Review in GitHub Actions
Setting CI=1 is usually all you need to make Claude Code work non-interactively:
# .github/workflows/ai-review.yml
name: AI Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Claude Code review
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
CI: "1"
run: |
npm install -g @anthropic-ai/claude-code
git diff origin/main...HEAD > diff.txt
claude -p "Review this PR diff. Flag any bugs, security issues, or significant code quality problems." \
< diff.txtSharing a Consistent Configuration Across Your Team
Committing .claude/settings.json to your repository ensures everyone works under the same constraints without manual setup.
// .claude/settings.json — commit this to your repo
{
"permissions": {
"allow": [
"Bash(npm:*)",
"Bash(npx:*)",
"Bash(git:*)",
"Bash(node:*)",
"Read(**)",
"Write(src/**)",
"Write(tests/**)",
"Write(docs/**)"
],
"deny": [
"Bash(rm -rf:*)",
"Write(.env:*)",
"Write(.env.local:*)",
"Write(*.pem:*)"
]
}
}The explicit deny on .env files is worth highlighting: it prevents Claude Code from accidentally overwriting API keys or other secrets, even when operating in a permissive allow mode.
Next Step
Start with ~/.claude/settings.json. Add permissions.allow entries for the commands you run most often in your projects. You'll notice fewer interrupting confirmation prompts immediately, and the workflow becomes noticeably smoother.
If you want to go deeper on the full settings.json schema, the Claude Code settings.json Complete Guide covers every available field with detailed examples.