Overview
The settings.json file controls Claude Code’s behavior, model selection, token limits, and environment variables. Proper configuration significantly reduces costs without sacrificing quality.
File Location
Token Optimization Settings
Recommended Configuration
Setting Details
Model Selection
Switch models based on task complexity:
Plugin Configuration
Installing Plugins
MCP Server Management
Disabling Unused MCP Servers
Each MCP tool description consumes tokens from your 200k context window, potentially reducing it to ~70k.
Project-level disable (.claude/settings.json):
Best practices:
- Keep under 10 MCPs enabled per project
- Keep under 80 tools active total
- Disable unused MCPs in project config
Context Window Management
Strategic Compaction
When to compact:
- After research/exploration, before implementation
- After completing a milestone, before starting the next
- After debugging, before continuing feature work
- After a failed approach, before trying a new one
When NOT to compact:
- Mid-implementation (you’ll lose variable names, file paths, partial state)
Daily Workflow Commands
Agent Teams Cost Warning
Agent Teams spawns multiple context windows. Each teammate consumes tokens independently. Only use for tasks where parallelism provides clear value (multi-module work, parallel reviews). For simple sequential tasks, subagents are more token-efficient.
Environment Variables
Package Manager Detection
Supported values: npm, pnpm, yarn, bun
Hooks Configuration
For Claude Code v2.1+: Do NOT add a "hooks" field to .claude-plugin/plugin.json. Claude Code automatically loads hooks/hooks.json from installed plugins. Explicitly declaring it causes duplicate detection errors.