Claude Code settings.json: configuración avanzada

Qué es settings.json y dónde vive

El archivo settings.json controla el comportamiento técnico de Claude Code: qué herramientas puede usar sin pedir permiso, qué scripts se ejecutan automáticamente y qué servidores externos están conectados.

Mientras que CLAUDE.md define el "qué" (instrucciones en lenguaje natural), settings.json define el "cómo" (configuración técnica).

Hay dos ubicaciones:

• ~/.claude/settings.json — Configuración global (personal, no se comparte). Aplica a todos los proyectos.
• .claude/settings.json — Configuración del proyecto (se sube a git, la comparte el equipo). Tiene prioridad sobre la global.

La jerarquía de precedencia es: proyecto > global. Si defines allowedTools en ambos, el del proyecto gana. Los MCP servers se combinan (merge): puedes tener MCPs globales y añadir más a nivel de proyecto.

Referencia completa de settings.json

Todas las claves disponibles en settings.json:

{
 // Herramientas permitidas sin confirmación
 "allowedTools": ["Bash(comando)", "Read", "Write", "Edit"],

 // Herramientas bloqueadas (nunca se ejecutan)
 "deniedTools": ["Bash(rm -rf *)"],

 // Scripts automáticos por evento
 "hooks": {
   "PreCommit": [],
   "PostCommit": [],
   "PreFileWrite": [],
   "PostFileWrite": [],
   "PreToolUse": [],
   "PostToolUse": [],
   "SessionStart": [],
   "SessionEnd": []
 },

 // Servidores MCP (conexiones externas)
 "mcpServers": {},

 // Modelo por defecto
 "model": "claude-sonnet-4-20250514",

 // Modelo para tareas de agente (subagentes)
 "smallModel": "claude-haiku-4-20250514",

 // Máximo de tokens de respuesta
 "maxTokens": 16384,

 // Activar/desactivar telemetría
 "telemetry": true,

 // Directorio de trabajo (rara vez necesario)
 "cwd": "/ruta/absoluta"
}

Configurar permisos de herramientas

Por defecto, Claude Code pide confirmación antes de ejecutar cualquier comando o modificar archivos. Con allowedTools puedes definir qué acciones se ejecutan sin preguntarte:

{
 "allowedTools": [
 "Bash(npm test)",
 "Bash(npm run lint)",
 "Bash(npm run build)",
 "Bash(git status)",
 "Bash(git diff)",
 "Bash(git log *)",
 "Bash(pytest *)",
 "Read",
 "Write",
 "Edit",
 "Glob",
 "Grep"
 ]
}

Cada entrada permite una acción específica. Bash(npm test) permite ejecutar solo npm test, no cualquier comando bash. Read permite leer cualquier archivo. Write y Edit permiten modificar archivos. El asterisco (*) funciona como wildcard: Bash(git log *) permite cualquier variación de git log.

Patrones de permisos por tipo de proyecto

// Frontend (Next.js / React)
"allowedTools": [
 "Bash(npm test)", "Bash(npm run lint)", "Bash(npm run build)",
 "Bash(npx tsc --noEmit)", "Bash(git *)",
 "Read", "Write", "Edit", "Glob", "Grep"
]

// Backend (Python / FastAPI)
"allowedTools": [
 "Bash(pytest *)", "Bash(ruff check *)", "Bash(ruff format *)",
 "Bash(python -m mypy *)", "Bash(git *)",
 "Read", "Write", "Edit", "Glob", "Grep"
]

// Full-stack (monorepo)
"allowedTools": [
 "Bash(npm test)", "Bash(pytest *)", "Bash(git *)",
 "Bash(docker compose *)", "Bash(make *)",
 "Read", "Write", "Edit", "Glob", "Grep"
]

También puedes bloquear herramientas con deniedTools:

{
 "deniedTools": [
 "Bash(rm -rf *)",
 "Bash(git push --force *)",
 "Bash(git reset --hard *)",
 "Bash(git checkout -- .)",
 "Bash(docker system prune *)"
 ]
}

Hooks: automatizar acciones

Los hooks ejecutan scripts automáticamente cuando ocurre un evento. Son la clave para convertir Claude Code en un sistema proactivo que mantiene calidad sin que tú intervengas.

{
 "hooks": {
 "PreCommit": [
 {
 "command": "npm run lint && npm test",
 "description": "Lint y tests antes de commit"
 }
 ],
 "PostFileWrite": [
 {
 "command": "prettier --write $FILE",
 "description": "Formatear archivo después de escribir"
 }
 ],
 "PreToolUse": [
 {
 "command": "echo 'Tool: $TOOL_NAME'",
 "description": "Log de herramientas usadas"
 }
 ],
 "SessionStart": [
 {
 "command": "echo 'Session started at $(date)'",
 "description": "Log inicio de sesión"
 }
 ]
 }
}

Eventos disponibles y cuándo se disparan:

• PreCommit: antes de crear un commit. Si falla, el commit se cancela. Ideal para lint + tests.
• PostCommit: después de un commit exitoso. Para notificaciones o deploys.
• PreFileWrite: antes de escribir un archivo. Para validaciones.
• PostFileWrite: después de escribir. Para formateo automático (Prettier, Black).
• PreToolUse: antes de usar cualquier herramienta. Para logging o guardrails.
• PostToolUse: después de usar una herramienta. Para auditoría.
• SessionStart: al iniciar Claude Code. Para cargar contexto.
• SessionEnd: al cerrar. Para cleanup o reportes.

Variables de entorno en hooks

Cada hook recibe variables de contexto:

• $FILE — Ruta del archivo afectado (en PostFileWrite, PreFileWrite)
• $TOOL_NAME — Nombre de la herramienta (en PreToolUse, PostToolUse)
• $COMMIT_MSG — Mensaje del commit (en PreCommit)

Servidores MCP

MCP (Model Context Protocol) permite conectar Claude Code con herramientas externas. La configuración va en settings.json:

{
 "mcpServers": {
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"],
 "env": {
 "GITHUB_TOKEN": "${GITHUB_TOKEN}"
 }
 },
 "supabase": {
 "command": "npx",
 "args": ["-y", "@supabase/mcp-server-supabase"],
 "env": {
 "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
 }
 },
 "filesystem": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ruta/extra"]
 }
 }
}

Cada MCP server se ejecuta como un proceso hijo de Claude Code. Se inicia al arrancar y permanece activo durante la sesión. Para profundizar en MCP, consulta nuestra guía de MCP en Claude Code y el tutorial de MCP + Supabase.

Selección de modelo

Puedes especificar qué modelo usa Claude Code por defecto:

{
 // Modelo principal para tareas complejas
 "model": "claude-sonnet-4-20250514",

 // Modelo para subagentes (más rápido y barato)
 "smallModel": "claude-haiku-4-20250514"
}

Modelos disponibles y cuándo usar cada uno:

• claude-opus-4-20250514: el más potente. Para arquitectura compleja, refactoring masivo, y decisiones que requieren razonamiento profundo. Más lento y caro.
• claude-sonnet-4-20250514: equilibrio entre calidad y velocidad. El default recomendado para desarrollo diario.
• claude-haiku-4-20250514: el más rápido. Para clasificación, tareas simples, y subagentes que necesitan respuestas inmediatas.

También puedes cambiar el modelo durante la sesión con el flag --model al iniciar Claude Code, o con /model dentro de una sesión activa.

Variables de entorno

Los settings.json soportan variables de entorno con la sintaxis ${VARIABLE}. Esto evita poner secretos directamente en archivos que podrían acabar en git:

// settings.json usa variables del sistema
{
 "mcpServers": {
 "github": {
 "env": {
 "GITHUB_TOKEN": "${GITHUB_TOKEN}"
 }
 }
 }
}

// Las variables se definen en tu shell profile (~/.zshrc):
// export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
// export SUPABASE_ACCESS_TOKEN="sbp_xxxxxxxxxxxx"
// export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxx"

Variables de entorno que Claude Code reconoce automáticamente:

• ANTHROPIC_API_KEY — Tu API key de Anthropic (necesaria para el API direct mode)
• CLAUDE_CODE_USE_BEDROCK — Usar AWS Bedrock como backend
• CLAUDE_CODE_USE_VERTEX — Usar Google Vertex AI como backend
• DISABLE_PROMPT_CACHING — Desactivar prompt caching (no recomendado)

Configuración compartida en equipo

El archivo .claude/settings.json del proyecto se sube a git y todos los miembros del equipo lo comparten. Esto garantiza consistencia:

// .claude/settings.json (del proyecto, en git)
{
 "allowedTools": [
 "Bash(npm test)",
 "Bash(npm run lint)",
 "Read", "Edit", "Write", "Glob", "Grep"
 ],
 "deniedTools": [
 "Bash(git push --force *)",
 "Bash(rm -rf *)"
 ],
 "hooks": {
 "PreCommit": [
 {
   "command": "npm run lint && npm run test:unit",
   "description": "Calidad de código antes de commit"
 }
 ]
 },
 "mcpServers": {
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"],
 "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
 }
 }
}

Buenas prácticas para configuración de equipo:

• El settings.json del proyecto define el mínimo necesario para trabajar en el repo
• No incluyas tokens ni secretos. Usa siempre ${VARIABLE}
• Documenta en el README qué variables de entorno necesita cada desarrollador
• Los MCPs que necesitan todos van en el proyecto. Los personales (Gmail, Calendar) en tu global.
• Usa deniedTools para proteger operaciones peligrosas que nadie debería automatizar

Migración entre máquinas

Cuándo cambias de ordenador o configuras un nuevo entorno de desarrollo:

Qué copiar

• ~/.claude/settings.json — Tu configuración global
• ~/.claude/CLAUDE.md — Tus instrucciones globales personales
• ~/.claude/projects/ — Memoria por proyecto (opcional, se regenera)

Qué reconfigurar

• Variables de entorno (tokens, API keys) en tu ~/.zshrc o ~/.bashrc
• Dependencias de MCPs (Node.js, npx deben estar instalados)
• Autenticación con claude login

Automatizar con dotfiles

# En tu repo de dotfiles:
# ~/.dotfiles/claude/settings.json → symlink a ~/.claude/settings.json

# Script de setup:
#!/bin/bash
mkdir -p ~/.claude
ln -sf ~/.dotfiles/claude/settings.json ~/.claude/settings.json
ln -sf ~/.dotfiles/claude/CLAUDE.md ~/.claude/CLAUDE.md

# Las variables de entorno van en ~/.dotfiles/shell/exports.sh
# (que se carga desde ~/.zshrc)

Ejemplo completo de settings.json

Un settings.json de producción para un proyecto Next.js + FastAPI + Supabase:

{
 "model": "claude-sonnet-4-20250514",
 "smallModel": "claude-haiku-4-20250514",
 "allowedTools": [
 "Bash(npm test)",
 "Bash(npm run lint)",
 "Bash(npm run build)",
 "Bash(npx tsc --noEmit)",
 "Bash(pytest *)",
 "Bash(ruff check *)",
 "Bash(git status)",
 "Bash(git diff *)",
 "Bash(git log *)",
 "Bash(git add *)",
 "Read",
 "Edit",
 "Write",
 "Glob",
 "Grep"
 ],
 "deniedTools": [
 "Bash(rm -rf *)",
 "Bash(git push --force *)",
 "Bash(git reset --hard *)",
 "Bash(git checkout -- .)",
 "Bash(DROP TABLE *)",
 "Bash(docker system prune *)"
 ],
 "hooks": {
 "PreCommit": [
 {
 "command": "npm run lint && pytest --tb=short -q",
 "description": "Lint frontend + tests backend antes de commit"
 }
 ],
 "PostFileWrite": [
 {
 "command": "prettier --write $FILE",
 "description": "Autoformato al crear/modificar archivos"
 }
 ]
 },
 "mcpServers": {
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"],
 "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
 },
 "supabase": {
 "command": "npx",
 "args": ["-y", "@supabase/mcp-server-supabase"],
 "env": { "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}" }
 }
 }
}

Errores comunes

• JSON inválido: Un settings.json con comas extra o comillas rotas hace que Claude Code ignore toda la configuración. Valida con cat .claude/settings.json | python -m json.tool antes de guardar.
• Permisos demasiado amplios: "allowedTools": ["Bash(*)"] es un riesgo de seguridad. Sé granular.
• Hooks que fallan silenciosamente: Si un hook falla, puede bloquear la acción (ej: PreCommit impide el commit). Testea los hooks manualmente primero: ejecuta el comando del hook directamente en tu terminal.
• Tokens en settings.json: Si el archivo se sube a git (el de proyecto), nunca pongas tokens directamente. Usa variables de entorno: "${GITHUB_TOKEN}".
• Confundir global con proyecto: La configuración de ~/.claude/settings.json aplica a todo. Si solo quieres algo para un proyecto, usa .claude/settings.json del proyecto.
• MCP servers que no arrancan: Verifica que tienes Node.js instalado y actualizado. Ejecuta el comando del MCP manualmente para ver errores. Comprueba que las variables de entorno están exportadas en tu shell actual.
• Hooks con paths relativos: Los hooks se ejecutan desde el directorio del proyecto. Si tu script está en otro lugar, usa path absoluto.

Preguntas frecuentes

¿Puedo tener settings.json diferentes por rama?

Sí, porque .claude/settings.json es un archivo normal en git. Cada rama puede tener su propia versión. Útil para ramas de feature que necesitan MCPs específicos o permisos diferentes.

¿Se puede usar settings.json sin CLAUDE.md?

Sí. Son independientes. settings.json funciona solo y viceversa. Pero la combinación es donde está el poder real: CLAUDE.md dice qué hacer, settings.json controla cómo puede hacerlo.

¿Los hooks funcionan en modo agente (subagentes)?

Los hooks del proyecto aplican a todos los agentes que trabajan en ese directorio. Si un subagente crea un commit, el PreCommit hook se ejecuta igualmente.

¿Cómo desactivo temporalmente un hook?

No hay flag de desactivación temporal. Puedes comentar la línea (pero es JSON, no admite comentarios). La opción más limpia: renombra temporalmente el settings.json o usa una rama diferente.

Siguiente paso

Con un settings.json bien configurado, Claude Code se adapta a tu flujo de trabajo. Combínalo con un buen CLAUDE.md para que Claude Code sepa qué hacer Y cómo hacerlo.

Después, explora la memoria de Claude Code para persistir contexto entre sesiones, los skills para crear comandos personalizados, y el tutorial de MCP + Supabase para ver en la práctica cómo funciona un MCP configurado.