Jerarquía y scope
Claude Code usa un sistema de scopes para precedencia y sharing:
| Scope | Location | Aplica a | Shareable |
|---|
| Managed | Server-managed, MDM/registry, system managed-settings.json | Toda la org | Sí (IT) |
| User | ~/.claude/ | Todos tus proyectos | No |
| Project | .claude/ en repo | Colaboradores del repo | Sí (git) |
| Local | .claude/settings.local.json | Vos en este repo | No (gitignored) |
Prioridad
- Managed (no se puede overridear)
- CLI arguments (override por sesión)
- Local
- Project
- User
En Windows, ~/.claude resuelve a %USERPROFILE%\.claude.
Managed settings deployment
- macOS: domain
com.anthropic.claudecode (preferences) o /Library/Application Support/ClaudeCode/
- Windows:
HKLM\SOFTWARE\Policies\ClaudeCode (Settings REG_SZ), o C:\Program Files\ClaudeCode\. User-level: HKCU\SOFTWARE\Policies\ClaudeCode
- Linux/WSL:
/etc/claude-code/
Drop-in directory: managed-settings.d/ con archivos merged en orden alfabético (10-telemetry.json, 20-security.json).
Claude Code crea backups timestamped automáticamente (retiene los 5 más recientes).
Ejemplo settings.json
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm run test *)", "Read(~/.zshrc)"],
"deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"]
},
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1"
}
}
Settings disponibles
Modelo y comportamiento
| Key | Descripción |
|---|
agent | Corre el main thread como un subagent (su system prompt, tools, modelo) |
model | Override del modelo default. --model y ANTHROPIC_MODEL lo overridean por sesión |
modelOverrides | Mapear IDs Anthropic a provider IDs (ej Bedrock ARNs) |
availableModels | Restringe qué modelos puede elegir el user via /model, --model, ANTHROPIC_MODEL |
effortLevel | Persistir effort: low/medium/high/xhigh |
alwaysThinkingEnabled | Extended thinking default para todas las sesiones |
showThinkingSummaries | Mostrar summaries de extended thinking (default redactado) |
UI
| Key | Descripción |
|---|
editorMode | "normal" o "vim" |
tui | "fullscreen" flicker-free o "default" |
viewMode | Default: "default", "verbose", o "focus" |
language | Idioma preferido para respuestas |
outputStyle | Output style (ej "Explanatory") |
autoScrollEnabled | Seguir output al fondo (fullscreen) |
prefersReducedMotion | Reduce animaciones (a11y) |
spinnerTipsEnabled | Tips en el spinner |
spinnerTipsOverride | Override de tips ({ "excludeDefault": true, "tips": ["..."] }) |
spinnerVerbs | Verbos custom ({"mode": "append", "verbs": ["Pondering"]}) |
showTurnDuration | Mostrar duración de turnos (default true) |
terminalProgressBarEnabled | Progress bar en terminales soportadas |
preferredNotifChannel | auto/terminal_bell/iterm2/iterm2_with_bell/kitty/ghostty/notifications_disabled |
awaySummaryEnabled | Recap al volver tras estar away |
syntaxHighlightingDisabled | Desactivar highlighting en diffs |
Skills
| Key | Descripción |
|---|
skillListingBudgetFraction | Fracción del context window para skill listing (default 0.01 = 1%). min-ver 2.1.105 |
maxSkillDescriptionChars | Cap por skill de description + when_to_use (default 1536). min-ver 2.1.105 |
skillOverrides | Visibility por skill: "on", "name-only", "user-invocable-only", "off". min-ver 2.1.129 |
disableSkillShellExecution | Bloquea ejecución inline !\…“ en skills |
Permissions
{
"permissions": {
"allow": ["Bash(npm run lint)", "Bash(npm run test *)"],
"ask": ["Bash(git push *)"],
"deny": ["Bash(curl *)", "Read(./.env)", "Read(./secrets/**)"],
"additionalDirectories": ["../docs/"],
"defaultMode": "acceptEdits",
"disableBypassPermissionsMode": "disable",
"skipDangerousModePermissionPrompt": true
}
}
| Key | Descripción |
|---|
permissions.allow | Array de reglas que permiten tool use |
permissions.ask | Array de reglas que piden confirmación |
permissions.deny | Array de reglas que deniegan |
permissions.additionalDirectories | Working dirs adicionales para file access |
permissions.defaultMode | default, acceptEdits, plan, auto, dontAsk, bypassPermissions |
permissions.disableBypassPermissionsMode | "disable" para impedir bypass mode |
permissions.skipDangerousModePermissionPrompt | Skip confirmación antes de bypass mode |
disableAutoMode | "disable" para impedir auto mode |
autoMode | Customize qué bloquea el classifier (environment, allow, soft_deny, hard_deny) |
useAutoModeDuringPlan | Plan mode usa semántica auto (default true) |
Reglas: format Tool o Tool(specifier). Evaluación en orden: deny → ask → allow. Primer match gana.
| Ejemplo | Efecto |
|---|
Bash | Todos los Bash |
Bash(npm run *) | Comandos npm run ... |
Read(./.env) | Leer .env |
WebFetch(domain:example.com) | Fetch a example.com |
Sandbox
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true,
"excludedCommands": ["docker *"],
"filesystem": {
"allowWrite": ["/tmp/build", "~/.kube"],
"denyRead": ["~/.aws/credentials"]
},
"network": {
"allowedDomains": ["github.com", "*.npmjs.org"],
"deniedDomains": ["uploads.github.com"]
}
}
}
| Key | Descripción |
|---|
sandbox.enabled | macOS/Linux/WSL2. Default false |
sandbox.failIfUnavailable | Exit si el sandbox no puede iniciar |
sandbox.autoAllowBashIfSandboxed | Auto-approve bash bajo sandbox (default true) |
sandbox.excludedCommands | Comandos fuera del sandbox |
sandbox.allowUnsandboxedCommands | Permitir comandos fuera del sandbox (default true) |
sandbox.filesystem.allowWrite | Paths adicionales para escritura |
sandbox.filesystem.denyWrite | Paths bloqueados para escritura |
sandbox.filesystem.denyRead | Paths bloqueados para lectura |
sandbox.filesystem.allowRead | Re-allow lectura en zonas denyRead |
sandbox.network.allowedDomains | Dominios outbound permitidos |
sandbox.network.deniedDomains | Dominios bloqueados |
sandbox.network.allowUnixSockets | (macOS) sockets Unix accesibles |
sandbox.network.allowAllUnixSockets | Permitir todos los Unix sockets |
sandbox.network.allowLocalBinding | (macOS) bind a localhost ports |
sandbox.network.allowMachLookup | (macOS) XPC/Mach service names |
sandbox.network.httpProxyPort / socksProxyPort | Proxies |
sandbox.enableWeakerNestedSandbox | Sandbox débil para Docker unprivileged. Reduce security |
Hooks y Statusline
| Key | Descripción |
|---|
hooks | Configurar hooks |
disableAllHooks | Deshabilita TODOS los hooks y statusline |
allowedHttpHookUrls | Allowlist URL patterns para HTTP hooks (* wildcard) |
httpHookAllowedEnvVars | Env vars que pueden interpolar en HTTP hooks |
statusLine | Configurar status line ({ "type": "command", "command": "..." }) |
MCP Servers
| Key | Descripción |
|---|
enableAllProjectMcpServers | Auto-approve todos los MCP en .mcp.json del proyecto |
enabledMcpjsonServers | Lista de MCP servers a approve |
disabledMcpjsonServers | Lista a rechazar |
allowedMcpServers | (Managed) allowlist |
deniedMcpServers | (Managed) denylist |
allowManagedMcpServersOnly | (Managed) solo allowlist gestionado |
Plugins
| Key | Descripción |
|---|
allowedChannelPlugins | (Managed) allowlist de channel plugins |
blockedMarketplaces | (Managed) blocklist de marketplaces |
strictKnownMarketplaces | (Managed) allowlist de marketplaces |
pluginTrustMessage | (Managed) mensaje custom en plugin trust warning |
Worktrees
| Key | Descripción |
|---|
worktree.baseRef | "fresh" (default) o "head" |
worktree.symlinkDirectories | Dirs a symlinkear desde repo principal |
worktree.sparsePaths | Dirs via git sparse-checkout |
Agents y teams
| Key | Descripción |
|---|
disableAgentView | Apagar background agents y agent view |
teammateMode | auto/in-process/tmux |
disableRemoteControl | Desactivar Remote Control. min-ver 2.1.128 |
Updates
| Key | Descripción |
|---|
autoUpdatesChannel | "stable" (~1 semana) o "latest" (default) |
minimumVersion | Floor que impide auto-updates por debajo |
Auth
| Key | Descripción |
|---|
forceLoginMethod | claudeai o console |
forceLoginOrgUUID | UUID(s) requeridos para login |
apiKeyHelper | Script custom que genera auth value (X-Api-Key, Authorization Bearer) |
awsAuthRefresh | Script que modifica .aws/ |
awsCredentialExport | Script que outputea JSON con AWS credentials |
gcpAuthRefresh | Script que refresca GCP ADC |
otelHeadersHelper | Script para OTel headers dinámicos |
File/Memory
| Key | Descripción |
|---|
fileSuggestion | Custom script para @ autocomplete |
respectGitignore | @ file picker respeta .gitignore (default true) |
plansDirectory | Dónde se guardan los plans (default ~/.claude/plans) |
autoMemoryDirectory | Dir custom para auto-memory |
autoMemoryEnabled | Auto-memory on/off (default true) |
claudeMdExcludes | Globs o paths absolutos de CLAUDE.md a saltear |
claudeMd | (Managed) instrucciones inyectadas como org-managed memory |
Attribution
{
"attribution": {
"commit": "🤖 Generated with Claude Code\n\nCo-Authored-By: Claude Sonnet 4.6 <[email protected]>",
"pr": "🤖 Generated with Claude Code"
}
}
| Key | Descripción |
|---|
attribution.commit / attribution.pr | Templates de commit/PR |
includeGitInstructions | Built-in workflow de commit/PR en system prompt (default true) |
prUrlTemplate | Substituye {host}, {owner}, {repo}, {number}, {url} |
Channels y org
| Key | Descripción |
|---|
channelsEnabled | (Managed) Channels para la org |
companyAnnouncements | Array de announcements al startup |
Avanzado
| Key | Descripción |
|---|
defaultShell | "bash" (default) o "powershell" para ! commands del input box |
fastModePerSessionOptIn | Fast mode no persiste entre sesiones |
disableDeepLinkRegistration | "disable" para no registrar claude-cli:// |
sshConfigs | Conexiones SSH para el dropdown del Desktop |
policyHelper | (min-ver 2.1.136) ejecutable que computa managed settings dinámicamente |
parentSettingsBehavior | (Managed, min-ver 2.1.133) "first-wins" o "merge" |
forceRemoteSettingsRefresh | (Managed) blockea startup hasta fetch fresh |
wslInheritsWindowsSettings | (Windows managed) WSL lee del policy chain |
feedbackSurveyRate | Probabilidad (0-1) del survey de quality |
cleanupPeriodDays | Borrar session files más viejos (default 30, min 1) |
Global config (~/.claude.json)
Se guarda en ~/.claude.json (no en settings.json):
| Key | Descripción |
|---|
autoConnectIde | Auto-conectar a IDE al iniciar |
autoInstallIdeExtension | Auto-instalar extension del IDE (default true) |
externalEditorContext | Prepend respuesta previa como comments en editor externo |
teammateDefaultModel | Modelo default para teammates |
Cuándo usar cada scope
- Managed: políticas org-wide, compliance, IT configs standard
- User: preferencias personales, API keys
- Project: settings team-shared, permissions, hooks, MCP servers
- Local: overrides personales, testing, machine-specific
Tips
- Agregá
"$schema": "https://json.schemastore.org/claude-code-settings.json" para autocomplete y validación inline
- Las permission rules se mergean entre scopes (los scalars siguen prioridad)
- Sandbox y permission rules son complementarios (se combinan)
- Backups timestamped automáticos (5 más recientes)
Siguiente: Memory y CLAUDE.md