From 0e7826eceba64b140b448b2aa3d1da22b31e2771 Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Thu, 29 Jan 2026 00:16:30 +0500 Subject: [PATCH] added settings --- README.md | 4 + reports/claude-settings.md | 710 +++++++++++++++++++++++++++++++++++++ 2 files changed, 714 insertions(+) create mode 100644 reports/claude-settings.md diff --git a/README.md b/README.md index 6db034d..b0bdd8b 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/reports/claude-settings.md b/reports/claude-settings.md new file mode 100644 index 0000000..b696a7e --- /dev/null +++ b/reports/claude-settings.md @@ -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 ", + "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/)