gilles/claude-code-best-practice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added settings

Browse Source
This commit is contained in:
Shayan Rais
2026-01-29 00:16:30 +05:00
parent 3054c81414
commit 0e7826eceb
2 changed files with 714 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+4
View File
@@ -97,3 +97,7 @@ practice makes claude perfect
**Why it works:** Progressive disclosure • Single execution context • Clean separation • Reusability
See [docs/weather-flow-architecture.md](docs/weather-flow-architecture.md) for implementation details.
## SETTINGS
See [reports/claude-settings.md](reports/claude-settings.md) for a comprehensive reference of all available `settings.json` configuration options.
reports/claude-settings.md
+710
View File
@@ -0,0 +1,710 @@
# Claude Code Settings Reference
A comprehensive guide to all available configuration options in Claude Code's `settings.json` files.
## Table of Contents
1. [Settings Hierarchy](#settings-hierarchy)
2. [Core Configuration](#core-configuration)
3. [Permissions](#permissions)
4. [Hooks](#hooks)
5. [MCP Servers](#mcp-servers)
6. [Sandbox](#sandbox)
7. [Plugins](#plugins)
8. [Model Configuration](#model-configuration)
9. [Display & UX](#display--ux)
10. [AWS & Cloud Credentials](#aws--cloud-credentials)
11. [Environment Variables](#environment-variables-via-env)
12. [Useful Commands](#useful-commands)
---
## Settings Hierarchy
Claude Code uses a 4-tier configuration hierarchy (highest to lowest priority):
| Priority | Location | Scope | Version Control | Purpose |
|----------|----------|-------|-----------------|---------|
| 1 | Command line arguments | Session | N/A | Single-session overrides |
| 2 | `.claude/settings.local.json` | Project | No (git-ignored) | Personal project-specific |
| 3 | `.claude/settings.json` | Project | Yes (committed) | Team-shared settings |
| 4 | `~/.claude/settings.json` | User | N/A | Global personal settings |
| 5 | `managed-settings.json` | System | Read-only | Organization policies |
**Important**: Later values override earlier ones EXCEPT for:
- `deny` rules (highest priority - cannot be overridden)
- Managed settings (cannot be overridden by any local settings)
---
## Core Configuration
### General Settings
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `model` | string | `"default"` | Override default model. Accepts aliases (`sonnet`, `opus`, `haiku`) or full model IDs |
| `language` | string | `"english"` | Claude's preferred response language |
| `cleanupPeriodDays` | number | `30` | Sessions inactive longer than this are deleted at startup |
| `autoUpdatesChannel` | string | `"latest"` | Release channel: `"stable"` or `"latest"` |
| `alwaysThinkingEnabled` | boolean | `false` | Enable extended thinking by default for all sessions |
**Example:**
```json
{
"model": "opus",
"language": "japanese",
"cleanupPeriodDays": 60,
"autoUpdatesChannel": "stable",
"alwaysThinkingEnabled": true
}
```
### Plans Directory
Store plan files in a custom location relative to project root.
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `plansDirectory` | string | `.claude/plans/` | Directory where `/plan` outputs are stored |
**Example:**
```json
{
"plansDirectory": "./my-plans"
}
```
**Use Case:** Useful for organizing planning artifacts separately from Claude's internal files, or for keeping plans in a shared team location.
### Attribution Settings
Customize attribution messages for git commits and pull requests.
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `attribution.commit` | string | Co-authored-by | Git commit attribution (supports trailers) |
| `attribution.pr` | string | Generated message | Pull request description attribution |
| `includeCoAuthoredBy` | boolean | `true` | **DEPRECATED** - Use `attribution` instead |
**Example:**
```json
{
"attribution": {
"commit": "Generated with AI\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
"pr": "Generated with Claude Code"
}
}
```
**Note:** Set to empty string (`""`) to hide attribution entirely.
### Authentication Helpers
Scripts for dynamic authentication token generation.
| Key | Type | Description |
|-----|------|-------------|
| `apiKeyHelper` | string | Shell script path that outputs auth token (sent as `X-Api-Key` header) |
| `forceLoginMethod` | string | Restrict login to `"claudeai"` or `"console"` accounts |
| `forceLoginOrgUUID` | string | UUID to automatically select organization during login |
**Example:**
```json
{
"apiKeyHelper": "/bin/generate_temp_api_key.sh",
"forceLoginMethod": "console",
"forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
### Company Announcements
Display custom announcements to users at startup (cycled randomly).
| Key | Type | Description |
|-----|------|-------------|
| `companyAnnouncements` | array | Array of strings displayed at startup |
**Example:**
```json
{
"companyAnnouncements": [
"Welcome to Acme Corp!",
"Remember to run tests before committing!",
"Check the wiki for coding standards"
]
}
```
---
## Permissions
Control what tools and operations Claude can perform.
### Permission Structure
```json
{
"permissions": {
"allow": [],
"ask": [],
"deny": [],
"additionalDirectories": [],
"defaultMode": "acceptEdits",
"disableBypassPermissionsMode": "disable"
}
}
```
### Permission Keys
| Key | Type | Description |
|-----|------|-------------|
| `permissions.allow` | array | Rules allowing tool use without prompting |
| `permissions.ask` | array | Rules requiring user confirmation |
| `permissions.deny` | array | Rules blocking tool use (highest precedence) |
| `permissions.additionalDirectories` | array | Extra directories Claude can access |
| `permissions.defaultMode` | string | Default permission mode |
| `permissions.disableBypassPermissionsMode` | string | Prevent bypass mode activation |
### Permission Modes
| Mode | Behavior |
|------|----------|
| `"default"` | Standard permission checking with prompts |
| `"acceptEdits"` | Auto-accept file edits without asking |
| `"askEdits"` | Ask before every operation |
| `"viewOnly"` | Read-only mode, no modifications |
| `"bypassPermissions"` | Skip all permission checks (dangerous) |
| `"plan"` | Read-only exploration mode |
### Tool Permission Syntax
| Tool | Syntax | Examples |
|------|--------|----------|
| `Bash` | `Bash(command pattern)` | `Bash(npm run *)`, `Bash(git commit *)` |
| `Read` | `Read(path pattern)` | `Read(.env)`, `Read(./secrets/**)` |
| `Edit` | `Edit(path pattern)` | `Edit(src/**)`, `Edit(*.ts)` |
| `Write` | `Write(path pattern)` | `Write(*.md)`, `Write(./docs/**)` |
| `NotebookEdit` | `NotebookEdit(pattern)` | `NotebookEdit(*)` |
| `WebFetch` | `WebFetch(domain:pattern)` | `WebFetch(domain:example.com)` |
| `WebSearch` | `WebSearch` | Global web search |
| `Task` | `Task(agent-name)` | `Task(Explore)`, `Task(my-agent)` |
| `Skill` | `Skill(skill-name)` | `Skill(weather-fetcher)` |
| `MCP` | `mcp__server__tool` | `mcp__memory__*`, `mcp__github__*` |
**Example:**
```json
{
"permissions": {
"allow": [
"Edit(*)",
"Write(*)",
"Bash(npm run *)",
"Bash(git *)",
"WebFetch(domain:*)",
"mcp__*"
],
"ask": [
"Bash(rm *)",
"Bash(git push *)"
],
"deny": [
"Read(.env)",
"Read(./secrets/**)",
"Bash(curl *)"
],
"additionalDirectories": ["../shared-libs/"]
}
}
```
---
## Hooks
Execute custom shell commands at various points in Claude Code's lifecycle.
### Hook Events (13 total)
| Event | When Fired | Matcher Support | Common Use Cases |
|-------|------------|-----------------|------------------|
| `SessionStart` | New or resumed session | No | Load context, set environment |
| `SessionEnd` | Session terminates | No | Cleanup, logging |
| `UserPromptSubmit` | User submits prompt | No | Validate input, add context |
| `PreToolUse` | Before tool execution | Yes | Validate commands, modify inputs |
| `PostToolUse` | After tool succeeds | Yes | Run linters, verify output |
| `PostToolUseFailure` | After tool fails | Yes | Log failures, recovery |
| `PermissionRequest` | Permission dialog appears | Yes | Auto-approve/deny patterns |
| `Notification` | Notification sent | Yes | Sound alerts, logging |
| `Stop` | Claude finishes responding | No | Block/continue decisions |
| `SubagentStart` | Subagent spawned | Yes | Per-agent setup |
| `SubagentStop` | Subagent completes | Yes | Cleanup, validation |
| `PreCompact` | Before context compaction | Yes | Backup, logging |
| `Setup` | Repository init (`--init`, `--maintenance`) | Yes | One-time setup |
### Hook Configuration Structure
```json
{
"hooks": {
"EventName": [
{
"matcher": "ToolPattern",
"hooks": [
{
"type": "command",
"command": "script.sh",
"timeout": 60000,
"once": true
}
]
}
]
},
"disableAllHooks": false,
"allowManagedHooksOnly": false
}
```
### Hook Properties
| Property | Type | Description |
|----------|------|-------------|
| `matcher` | string | Regex pattern to match tool/event (optional) |
| `type` | string | `"command"` or `"prompt"` |
| `command` | string | Shell command to execute (for `type: "command"`) |
| `prompt` | string | LLM prompt for evaluation (for `type: "prompt"`) |
| `timeout` | number | Timeout in milliseconds |
| `once` | boolean | Run only once per session |
### Hook Matcher Patterns
| Pattern | Matches |
|---------|---------|
| `"Bash"` | Exact match only |
| `"Edit\|Write"` | Multiple tools with regex OR |
| `"mcp__.*"` | All MCP tools |
| `"mcp__memory__.*"` | Specific MCP server tools |
| `"*"` or `""` | All tools |
### Hook Exit Codes
| Exit Code | Behavior |
|-----------|----------|
| `0` | Success, continue |
| `1` | Error (logged, continues) |
| `2` | Block the operation |
### Environment Variables in Hooks
| Variable | Description |
|----------|-------------|
| `${CLAUDE_PROJECT_DIR}` | Project root directory |
| `CLAUDE_TOOL_NAME` | Current tool name |
| `CLAUDE_TOOL_INPUT` | Tool input (JSON) |
| `CLAUDE_TOOL_OUTPUT` | Tool output (PostToolUse only) |
**Example:**
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/validate.py",
"timeout": 5000
}
]
}
],
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Session started!'",
"timeout": 1000,
"once": true
}
]
}
]
},
"disableAllHooks": false
}
```
---
## MCP Servers
Configure Model Context Protocol servers for extended capabilities.
### MCP Settings
| Key | Type | Scope | Description |
|-----|------|-------|-------------|
| `enableAllProjectMcpServers` | boolean | Any | Auto-approve all `.mcp.json` servers |
| `enabledMcpjsonServers` | array | Any | Allowlist specific server names |
| `disabledMcpjsonServers` | array | Any | Blocklist specific server names |
| `allowedMcpServers` | array | Managed only | Allowlist with name/command/URL matching |
| `deniedMcpServers` | array | Managed only | Blocklist with matching |
### MCP Server Matching (Managed Settings)
```json
{
"allowedMcpServers": [
{ "serverName": "github" },
{ "serverCommand": "npx @modelcontextprotocol/*" },
{ "serverUrl": "https://mcp.company.com/*" }
],
"deniedMcpServers": [
{ "serverName": "dangerous-server" }
]
}
```
**Example:**
```json
{
"enableAllProjectMcpServers": true,
"enabledMcpjsonServers": ["memory", "github", "filesystem"],
"disabledMcpjsonServers": ["experimental-server"]
}
```
---
## Sandbox
Configure bash command sandboxing for security.
### Sandbox Settings
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `sandbox.enabled` | boolean | `false` | Enable bash sandboxing |
| `sandbox.autoAllowBashIfSandboxed` | boolean | `true` | Auto-approve bash when sandboxed |
| `sandbox.excludedCommands` | array | `[]` | Commands to run outside sandbox |
| `sandbox.allowUnsandboxedCommands` | boolean | `true` | Allow `dangerouslyDisableSandbox` |
| `sandbox.network.allowUnixSockets` | array | `[]` | Unix sockets accessible in sandbox |
| `sandbox.network.allowLocalBinding` | boolean | `false` | Allow binding to localhost ports (macOS) |
| `sandbox.network.httpProxyPort` | number | - | HTTP proxy port (custom proxy) |
| `sandbox.network.socksProxyPort` | number | - | SOCKS5 proxy port (custom proxy) |
| `sandbox.enableWeakerNestedSandbox` | boolean | `false` | Weaker sandbox for Docker (reduces security) |
**Example:**
```json
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"excludedCommands": ["git", "docker", "gh"],
"allowUnsandboxedCommands": false,
"network": {
"allowUnixSockets": ["/var/run/docker.sock"],
"allowLocalBinding": true
}
}
}
```
---
## Plugins
Configure Claude Code plugins and marketplaces.
### Plugin Settings
| Key | Type | Scope | Description |
|-----|------|-------|-------------|
| `enabledPlugins` | object | Any | Enable/disable specific plugins |
| `extraKnownMarketplaces` | object | Any | Add custom plugin marketplaces |
| `strictKnownMarketplaces` | array | Managed only | Allowlist of permitted marketplaces |
**Example:**
```json
{
"enabledPlugins": {
"formatter@acme-tools": true,
"deployer@acme-tools": true,
"experimental@acme-tools": false
},
"extraKnownMarketplaces": {
"acme-tools": {
"source": {
"source": "github",
"repo": "acme-corp/claude-plugins"
}
}
}
}
```
---
## Model Configuration
### Model Aliases
| Alias | Description |
|-------|-------------|
| `"default"` | Recommended for your account type |
| `"sonnet"` | Latest Sonnet model (Claude 4.5) |
| `"opus"` | Latest Opus model (Claude 4.5) |
| `"haiku"` | Fast Haiku model |
| `"sonnet[1m]"` | Sonnet with 1M token context |
| `"opusplan"` | Opus for planning, Sonnet for execution |
**Example:**
```json
{
"model": "opus"
}
```
### Model Environment Variables
Configure via `env` key:
```json
{
"env": {
"ANTHROPIC_MODEL": "sonnet",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "custom-haiku-model",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "custom-sonnet-model",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "custom-opus-model",
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
"MAX_THINKING_TOKENS": "10000"
}
}
```
---
## Display & UX
### Display Settings
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `statusLine` | object | - | Custom status line configuration |
| `outputStyle` | string | `"default"` | Output style (e.g., `"Explanatory"`) |
| `spinnerTipsEnabled` | boolean | `true` | Show tips while waiting |
| `terminalProgressBarEnabled` | boolean | `true` | Show progress bar in terminal |
| `showTurnDuration` | boolean | `true` | Show turn duration messages |
| `respectGitignore` | boolean | `true` | Respect .gitignore in file picker |
### Status Line Configuration
```json
{
"statusLine": {
"type": "command",
"command": "~/.claude/statusline.sh",
"padding": 0
}
}
```
### File Suggestion Configuration
```json
{
"fileSuggestion": {
"type": "command",
"command": "~/.claude/file-suggestion.sh"
},
"respectGitignore": true
}
```
**Example:**
```json
{
"statusLine": {
"type": "command",
"command": "git branch --show-current 2>/dev/null || echo 'no-branch'"
},
"spinnerTipsEnabled": false,
"terminalProgressBarEnabled": true,
"showTurnDuration": false
}
```
---
## AWS & Cloud Credentials
### AWS Settings
| Key | Type | Description |
|-----|------|-------------|
| `awsAuthRefresh` | string | Script to refresh AWS auth (modifies `.aws` dir) |
| `awsCredentialExport` | string | Script outputting JSON with AWS credentials |
**Example:**
```json
{
"awsAuthRefresh": "aws sso login --profile myprofile",
"awsCredentialExport": "/bin/generate_aws_grant.sh"
}
```
### OpenTelemetry
| Key | Type | Description |
|-----|------|-------------|
| `otelHeadersHelper` | string | Script to generate dynamic OpenTelemetry headers |
**Example:**
```json
{
"otelHeadersHelper": "/bin/generate_otel_headers.sh"
}
```
---
## Environment Variables (via `env`)
Set environment variables for all Claude Code sessions.
```json
{
"env": {
"ANTHROPIC_API_KEY": "...",
"NODE_ENV": "development",
"DEBUG": "true"
}
}
```
### Common Environment Variables
| Variable | Description |
|----------|-------------|
| `ANTHROPIC_API_KEY` | API key for authentication |
| `ANTHROPIC_AUTH_TOKEN` | OAuth token |
| `ANTHROPIC_BASE_URL` | Custom API endpoint |
| `CLAUDE_CODE_USE_BEDROCK` | Use AWS Bedrock (`1` to enable) |
| `CLAUDE_CODE_USE_VERTEX` | Use Google Vertex AI (`1` to enable) |
| `CLAUDE_CODE_USE_FOUNDRY` | Use Microsoft Foundry (`1` to enable) |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enable/disable telemetry (`0` or `1`) |
| `DISABLE_ERROR_REPORTING` | Disable error reporting (`1` to disable) |
| `DISABLE_TELEMETRY` | Disable telemetry (`1` to disable) |
| `MCP_TIMEOUT` | MCP startup timeout in ms (default: 10000) |
| `MAX_MCP_OUTPUT_TOKENS` | Max MCP output tokens (default: 50000) |
| `BASH_MAX_TIMEOUT_MS` | Bash command timeout |
| `BASH_MAX_OUTPUT_LENGTH` | Max bash output length |
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Auto-compact threshold percentage |
| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Keep cwd between bash calls (`1` to enable) |
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Disable background tasks (`1` to disable) |
| `ENABLE_TOOL_SEARCH` | MCP tool search threshold (e.g., `auto:5`) |
| `DISABLE_PROMPT_CACHING` | Disable all prompt caching (`1` to disable) |
| `DISABLE_PROMPT_CACHING_HAIKU` | Disable Haiku prompt caching |
| `DISABLE_PROMPT_CACHING_SONNET` | Disable Sonnet prompt caching |
| `DISABLE_PROMPT_CACHING_OPUS` | Disable Opus prompt caching |
---
## Useful Commands
| Command | Description |
|---------|-------------|
| `/config` | Interactive configuration UI |
| `/memory` | View/edit all memory files |
| `/agents` | Manage subagents |
| `/mcp` | Manage MCP servers |
| `/hooks` | View configured hooks |
| `/plugin` | Manage plugins |
| `--doctor` | Diagnose configuration issues |
| `--debug` | Debug mode with hook execution details |
---
## Quick Reference: Complete Example
```json
{
"model": "sonnet",
"language": "english",
"cleanupPeriodDays": 30,
"autoUpdatesChannel": "stable",
"alwaysThinkingEnabled": true,
"plansDirectory": "./plans",
"permissions": {
"allow": [
"Edit(*)",
"Write(*)",
"Bash(npm run *)",
"Bash(git *)",
"WebFetch(domain:*)",
"mcp__*"
],
"deny": [
"Read(.env)",
"Read(./secrets/**)"
],
"additionalDirectories": ["../shared/"]
},
"enableAllProjectMcpServers": true,
"hooks": {
"PreToolUse": [
{
"hooks": [
{
"type": "command",
"command": "echo 'Tool starting'",
"timeout": 5000
}
]
}
]
},
"disableAllHooks": false,
"sandbox": {
"enabled": true,
"excludedCommands": ["git", "docker"]
},
"attribution": {
"commit": "Generated with Claude Code",
"pr": ""
},
"statusLine": {
"type": "command",
"command": "git branch --show-current"
},
"spinnerTipsEnabled": true,
"showTurnDuration": false,
"env": {
"NODE_ENV": "development"
}
}
```
---
## Sources
- [Claude Code Settings Documentation](https://code.claude.com/docs/en/settings)
- [Claude Code Configuration Guide](https://claudelog.com/configuration/)
- [Claude Code GitHub Settings Examples](https://github.com/feiskyer/claude-code-settings)
- [Eesel AI - Developer's Guide to settings.json](https://www.eesel.ai/blog/settings-json-claude-code)
- [Shipyard - Claude Code CLI Cheatsheet](https://shipyard.build/blog/claude-code-cheat-sheet/)