Cap 7: Settings

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)

Desde v2.1.211, las aprobaciones de tipo “Yes, don’t ask again” se guardan en .claude/settings.local.json ubicado en la raíz del repo git (resuelta a través de worktrees), y ese archivo se carga desde esa raíz aunque la sesión se inicie en un subdirectorio.

Prioridad

1. Managed (no se puede overridear)
2. CLI arguments (override por sesión)
3. Local
4. Project
5. User

Excepción documentada: las reglas de permisos (allow/ask/deny) no siguen esta precedencia — se fusionan entre todos los scopes. Ver Permissions.

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/

Windows: la ruta histórica C:\ProgramData\ClaudeCode\managed-settings.json quedó deprecada y eliminada en v2.1.75. La vigente es C:\Program Files\ClaudeCode\managed-settings.json. Lo mismo aplica al CLAUDE.md de política y a managed-mcp.json.

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/max (default high)
alwaysThinkingEnabled	Extended thinking default para todas las sesiones
showThinkingSummaries	Mostrar summaries de extended thinking (default redactado)

Los niveles de esfuerzo son low | medium | high | xhigh | max. En Claude Code el menú /effort muestra además ultracode, que no es un nivel del modelo: es un ajuste de sesión que envía xhigh y hace que Claude orqueste dynamic workflows para tareas sustanciales.

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 (alias manual desde v2.1.200, etiquetado Manual en la UI), acceptEdits, plan, auto, dontAsk, bypassPermissions
permissions.disableBypassPermissionsMode	"disable" para impedir bypass mode. Funciona desde cualquier scope
permissions.skipDangerousModePermissionPrompt	Skip confirmación antes de bypass mode
permissions.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)

En managed settings, ni permissions.disableAutoMode ni permissions.disableBypassPermissionsMode pueden sobrescribirse, tampoco con flags de CLI.

defaultMode: "auto" se ignora cuando viene de .claude/settings.json o .claude/settings.local.json (desde v2.1.142), para que un repo no pueda autoconcederse auto mode. Para fijarlo hay que ponerlo en ~/.claude/settings.json o en managed settings.

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

Fusión entre scopes

Las reglas allow/ask/deny son la excepción documentada a la precedencia de scopes: se fusionan entre todos ellos. Un deny en cualquier scope bloquea un allow de cualquier otro, incluido --allowedTools.

La especificidad no altera el orden de evaluación: Bash(aws *) en deny bloquea Bash(aws s3 ls) aunque esté en allow. No hay excepciones dentro de un deny.

Los arrays de settings se fusionan y deduplican entre scopes, salvo fallbackModel (máximo 3), que no se fusiona.

Qué herramientas se evalúan por ruta

Desde v2.1.210 solo Edit(path) y Read(path) se evalúan en los chequeos de permisos de archivo. Write(path), NotebookEdit(path) y Glob(path) se aceptan en el settings pero nunca coinciden y emiten un warning de arranque.

Desde v2.1.208, un deny de Read bloquea también Edit sobre esa ruta.

Anclajes de ruta

Las rutas de las reglas siguen la especificación gitignore, con cuatro anclajes:

Forma	Significado
//path	Absoluta desde la raíz del filesystem
~/path	Relativa al home
/path	Relativa al origen del settings (project root, ~/.claude, …)
path o ./path	Relativa al cwd

Es decir, Read(/Users/alice/file) no es una ruta absoluta: para eso se escribe Read(//Users/alice/file).

Desde v2.1.214, un patrón de un solo segmento como Edit(src/**) coincide solo con src en el directorio de trabajo; para cualquier profundidad hay que escribir Edit(**/src/**). Esto aplica también al campo if de los hooks.

Protected paths

Existen rutas cuyas escrituras nunca se auto-aprueban, salvo en bypassPermissions:

• Directorios: .git, .config/git, .vscode, .idea, .husky, .cargo, .devcontainer, .yarn, .mvn y .claude (excepto .claude/worktrees)
• Archivos: .bashrc, .zshrc, .envrc, .npmrc, .mcp.json, .claude.json

permissions.allow no las pre-aprueba: el chequeo de protected paths corre antes de evaluar allow.

Workspace trust y additionalDirectories

permissions.allow y permissions.additionalDirectories de un settings de proyecto solo aplican después de aceptar el diálogo de workspace trust; deny y ask no lo requieren.

additionalDirectories concede únicamente acceso a archivos: no carga skills ni subagentes, a diferencia de --add-dir.

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. Default: falla abierto (warning + comandos sin sandbox)
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
sandbox.enableWeakerNetworkIsolation	Aislamiento de red más débil. Reduce security
sandbox.filesystem.disabled	(v2.1.216+) Apaga el aislamiento de filesystem manteniendo el de red. Solo se honra desde user/managed/--settings
sandbox.network.tlsTerminate	(Experimental, v2.1.199+) Termina TLS, pero no filtra contenido
sandbox.credentials	(v2.1.187+) Denegar o enmascarar credenciales (ver abajo)

Comportamiento por defecto

Por defecto el sandbox permite escritura solo en el cwd y en el $TMPDIR de la sesión, pero lectura de todo el equipo salvo los directorios denegados.

Si el sandbox no puede iniciarse, por defecto se emite un warning y los comandos corren sin sandbox: falla abierto. Para que falle cerrado hay que poner sandbox.failIfUnavailable: true.

Rutas: convenciones distintas a las reglas de permisos

Las rutas de sandbox.filesystem.* usan convenciones estándar, no las de las reglas Read/Edit:

Forma	Significado
/tmp/build	Absoluta
~/.kube	Relativa al home
./dist o dist	Relativa a la raíz del proyecto (settings de proyecto) o a ~/.claude (settings de usuario)

Acá no se usa el prefijo // de las reglas Read/Edit. Es una fuente directa de error al copiar patrones de una sección a la otra.

Credenciales

{
  "sandbox": {
    "credentials": {
      "files": [{ "path": "~/.aws/credentials", "mode": "deny" }],
      "envVars": [
        { "name": "GITHUB_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] }
      ]
    }
  }
}

• files[].mode: "deny" bloquea el acceso al archivo.
• envVars[].mode acepta "deny" o "mask".
• mask (v2.1.199+) sustituye la credencial por un sentinel por sesión y el proxy inyecta el valor real solo hacia los injectHosts. Requiere network.tlsTerminate y se ignora si viene de settings de proyecto o local.

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
allowManagedHooksOnly	(Managed) Bloquea hooks de usuario, proyecto y plugin, salvo plugins force-enabled
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
allowAllClaudeAiMcps	(Managed) permitir todos los conectores de claude.ai

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
strictPluginOnlyCustomization	(Managed) Bloquea skills, agents, hooks y MCP servers de fuentes de usuario y proyecto
disableSideloadFlags	(Managed) Desactiva las flags de sideload

Claves managed-only

Estas claves no tienen efecto en scope user ni project; solo se honran desde managed settings. Son las relevantes para endurecer la extensibilidad:

Key	Efecto
allowManagedPermissionRulesOnly	Solo se aplican las reglas de permisos gestionadas
allowManagedHooksOnly	Bloquea hooks de usuario/proyecto/plugin, salvo plugins force-enabled
allowManagedMcpServersOnly	El allowlist de MCP se limita a fuentes gestionadas
allowAllClaudeAiMcps	Permite todos los conectores de claude.ai
strictPluginOnlyCustomization	Bloquea skills, agents, hooks y MCP servers de fuentes de usuario y proyecto
disableSideloadFlags	Desactiva las flags de sideload
sandbox.filesystem.allowManagedReadPathsOnly	Solo se honran los read paths gestionados
sandbox.network.allowManagedDomainsOnly	Solo se honran los dominios gestionados

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 omitir
claudeMd	(Managed) instrucciones inyectadas como org-managed memory

Attribution

{
  "attribution": {
    "commit": "🤖 Generated with Claude Code\n\nCo-Authored-By: Claude Opus 4.8 <[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}

Alias de modelo vigentes para armar el template: opus → Opus 4.8, sonnet → Sonnet 5.

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

• Agrega "$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): un deny en cualquier scope bloquea un allow de cualquier otro, incluido --allowedTools
• Los arrays de settings se fusionan y deduplican entre scopes, salvo fallbackModel (máx. 3), que no se fusiona
• Sandbox y permission rules son complementarios (se combinan)
• Backups timestamped automáticos (5 más recientes)

---

Siguiente: Memory y CLAUDE.md