Guía de Claude Code CLI: instalación, configuración, comandos, variables de entorno

En resumen: Claude Code es un CLI agéntico que lee tu código fuente, ejecuta comandos y modifica archivos a través de un sistema por capas de permisos, hooks, integraciones MCP y subagents. Domina cinco sistemas centrales (configuración, permisos, hooks, MCP y subagents) y desbloqueas una productividad multiplicadora. Elige el nivel de modelo que se ajuste a cada tarea — Opus para razonamiento complejo, Sonnet para trabajo general, Haiku para exploración rápida — o estandariza en Opus si la calidad es tu única variable. Usa hooks (no prompts) para todo lo que deba ejecutarse siempre.

Claude Code opera como un sistema agéntico, no como una interfaz de chat con conocimientos de programación. El CLI lee tu código fuente, ejecuta comandos, modifica archivos, gestiona flujos de trabajo en git, se conecta a servicios externos mediante MCP y delega tareas complejas a subagents especializados. Todo fluye a través de una interfaz de línea de comandos que se integra en la forma en que los desarrolladores realmente trabajan. A febrero de 2026, el 4% de los commits públicos en GitHub (~135.000 por día) son creados por Claude Code — un crecimiento de 42.896× en 13 meses desde la versión preliminar de investigación — y el 90% del código propio de Anthropic está escrito por IA.¹¹⁰

La diferencia entre un uso casual y uno efectivo de Claude Code se reduce a cinco sistemas centrales. Domínalos y Claude Code se convierte en un multiplicador de fuerza:

1. Jerarquía de configuración: controla el comportamiento
2. Sistema de permisos: regula las operaciones
3. Sistema de hooks: permite automatización determinista
4. Protocolo MCP: extiende las capacidades
5. Sistema de subagents: gestiona tareas complejas de múltiples pasos

Puntos Clave

• Cinco sistemas determinan tu efectividad: la jerarquía de configuración, los permisos, los hooks, MCP y los subagents controlan todo, desde el comportamiento hasta la automatización.
• Delega trabajo a la capa de delegación: los subagents previenen la saturación de contexto al aislar la exploración en ventanas de contexto limpias, devolviendo solo resúmenes.
• Los hooks garantizan la ejecución; los prompts no: usa hooks para linting, formateo y verificaciones de seguridad que deben ejecutarse siempre, independientemente del comportamiento del modelo.
• La segmentación por modelos ahorra costos sin sacrificar calidad: dirige la exploración de subagents a modelos más económicos y reserva Opus para razonamiento arquitectónico genuino — o estandariza en Opus si la calidad es tu única variable.
• MCP conecta a Claude con tu cadena de herramientas: bases de datos, GitHub, Sentry y más de 3.000 integraciones extienden a Claude más allá de la lectura de archivos y los comandos de bash.

Pasé meses llevando Claude Code al límite en bases de código en producción, pipelines de CI/CD y despliegues empresariales. Esta guía destila esa experiencia en la referencia completa que me hubiera gustado tener cuando empecé. Cada función incluye la sintaxis real, ejemplos de configuración concretos y los casos límite que confunden incluso a usuarios experimentados.

Elige Tu Camino

Cómo Usar Esta Guía

Esta es una referencia de más de 5.000 líneas — no necesitas leerla de principio a fin. Comienza donde se ajuste a tu nivel de experiencia:

Usa Ctrl+F / Cmd+F en tu navegador para buscar flags, comandos o claves de configuración específicas. La Tarjeta de referencia rápida al final ofrece un resumen escaneable de todos los comandos principales.

Artículos Relacionados en Profundidad

Estas publicaciones del blog exploran aspectos específicos de Claude Code en detalle:

Inicio rápido en 60 segundos

Si solo quieres ejecutar Claude Code y ver resultados, haz esto en orden:

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

Eso es todo. Todo lo que aparece debajo de esta sección amplía las opciones de instalación, configura permisos y hooks, conecta servidores MCP y cubre el despliegue empresarial, pero nada de eso es necesario para empezar.

Requisitos previos: Node 18+ (para la ruta de npm), macOS / Linux / Windows 10+. Una suscripción Claude Pro, Max, Team o Enterprise, o una API de Anthropic de pago por token, cubre el uso. Consulta ¿Cómo instalo Claude Code? para ver detalles específicos de cada plataforma, solución de problemas y la ruta del binario nativo (predeterminado desde v2.1.113).

Cómo funciona Claude Code: el modelo mental

Antes de sumergirte en las funciones, comprende cómo la arquitectura de Claude Code da forma a todo lo que haces con él. El sistema opera en tres capas:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Capa Core: tu conversación principal. Cada mensaje, lectura de archivo y salida de herramienta consume contexto de una ventana compartida (200K tokens estándar⁹⁸, 1M tokens con Opus 4.6 o modelos de contexto extendido). Cuando el contexto se llena, Claude pierde el hilo de decisiones anteriores y la calidad se degrada. Esta capa cuesta dinero por token.

Capa de delegación: los subagents se generan con contextos limpios, realizan trabajo enfocado y devuelven resúmenes. Los resultados de la exploración no saturan tu conversación principal; solo regresan las conclusiones. Enruta los subagents a niveles de modelo más económicos para la exploración, o usa tu modelo principal en todo momento si la calidad importa más que el costo.

Capa de extensión: MCP conecta servicios externos (bases de datos, GitHub, Sentry). Los hooks garantizan la ejecución de comandos de shell independientemente del comportamiento del modelo. Los skills codifican experiencia de dominio que Claude aplica automáticamente. Los plugins empaquetan todo esto para su distribución.

La idea clave: la mayoría de los usuarios trabaja totalmente en la capa Core, viendo cómo el contexto se infla y los costos suben. Los usuarios avanzados trasladan la exploración y el trabajo especializado a la capa de delegación, mantienen la capa de extensión configurada para su flujo de trabajo y usan la capa Core solo para orquestación y decisiones finales.

Tabla de contenidos

1. ¿Cómo instalo Claude Code?
2. Inicio rápido: tu primera sesión
3. Modos de interacción principales
4. Análisis profundo del sistema de configuración
5. ¿Qué modelo debo elegir?
6. ¿Cuánto cuesta Claude Code?
7. Marcos de decisión
8. ¿Cómo funciona el sistema de permisos?
9. ¿Cómo funcionan los hooks?
10. ¿Qué es MCP (Model Context Protocol)?
11. ¿Qué son los subagents?
12. ¿Qué es el modo de pensamiento extendido?
13. Estilos de salida
14. Slash Commands
15. ¿Cómo funcionan los skills?
16. Sistema de plugins
17. ¿Cómo funciona la memoria?
18. Entrada de imágenes y multimodal
19. Modo de voz
20. ¿Cómo funciona la integración con Git?
21. ¿Cómo uso Claude Code en mi IDE?
22. Patrones de uso avanzados
23. Agentes remotos y en segundo plano [VISTA PREVIA DE INVESTIGACIÓN]
24. Claude en Chrome
25. Claude Code en Slack [VISTA PREVIA DE INVESTIGACIÓN]
26. Claude Code en la web [VISTA PREVIA DE INVESTIGACIÓN]
27. Optimización del rendimiento
28. ¿Cómo depuro problemas?
29. Despliegue empresarial
30. Referencia de atajos de teclado
31. Mejores prácticas
32. Recetas de flujo de trabajo
33. Guía de migración
34. Orientación según la audiencia
35. Tarjeta de referencia rápida
36. Registro de cambios
37. Referencias

¿Cómo instalo Claude Code?

Requisitos del sistema

Claude Code funciona en macOS 13+, Ubuntu 20.04+/Debian 10+ y Windows 10+ (nativo o WSL). El sistema requiere un mínimo de 4 GB de RAM y una conexión activa a internet.⁹⁹ La compatibilidad de shell funciona mejor con Bash, Zsh o Fish.

Para Windows, tanto WSL 1 como WSL 2 funcionan. Git Bash también funciona si prefieres Windows nativo. Alpine Linux y otros sistemas basados en musl requieren paquetes adicionales:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Matriz de compatibilidad de plataformas

Instalación, actualización y desinstalación de un vistazo

Búsqueda rápida: cada método, cada comando, verificación de versión en una sola pantalla. Las subsecciones a continuación cubren los detalles específicos de cada método y la solución de problemas.

Desde la v2.1.113, la CLI canónica genera un binario nativo de Claude Code a través de una dependencia opcional específica de cada plataforma en lugar de un JavaScript incluido; usa el instalador nativo para la distribución probada. La ruta de npm sigue funcionando, pero recibe el aviso de obsolescencia que se añadió por primera vez en la v2.1.15.

Métodos de instalación

Instalación nativa (recomendada)

El binario nativo proporciona la experiencia más limpia sin dependencia de Node.js:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Para instalación de una versión específica:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Instalación con NPM (obsoleta)

Nota: A partir de la v2.1.15, las instalaciones con npm muestran un aviso de obsolescencia. El binario nativo es ahora el método de instalación recomendado. Migra con claude install.

Para entornos heredados donde aún se necesita npm:

npm install -g @anthropic-ai/claude-code

Nunca uses sudo con la instalación de npm. Crea problemas de permisos que complican todo lo posterior.

Migración desde una instalación existente

Si tienes una instalación antigua basada en npm, migra al binario nativo:

claude install

Opciones de autenticación

Claude Code admite tres rutas de autenticación, cada una con diferentes ventajas y desventajas:

Consola de Claude (facturación de API)

Conéctate directamente a la API de Anthropic a través de platform.claude.com (anteriormente console.anthropic.com). Crea una cuenta, configura la facturación y autentícate a través de la CLI. La Consola ofrece facturación basada en uso con acceso completo a la API. Se crea automáticamente un espacio de trabajo dedicado “Claude Code”; no puedes crear claves de API para este espacio de trabajo, pero puedes monitorear el uso.

Suscripción a Claude Pro o Max

Usa las credenciales de tu cuenta de claude.ai. La suscripción cubre tanto la interfaz web como el uso de la CLI bajo un único plan mensual. La suscripción simplifica la facturación para usuarios individuales que desean costos predecibles.

Plataformas empresariales

AWS Bedrock, Google Vertex AI y Microsoft Foundry proporcionan acceso de nivel empresarial con relaciones de facturación en la nube ya existentes. Asistente de configuración de Bedrock (v2.1.92+): Un asistente interactivo en la pantalla de inicio de sesión te guía por la autenticación de AWS, la selección de región, la verificación de credenciales y la fijación de modelos.¹⁴⁴ Asistente de configuración de Vertex AI (v2.1.98+): Un asistente equivalente para Google Cloud que guía la autenticación de GCP, la configuración de proyecto y región, la verificación de credenciales y la fijación de modelos.¹⁴⁹ Federación de identidades de carga de trabajo mTLS de Vertex AI (v2.1.121+): Vertex AI ahora acepta la Federación de Identidades de Carga de Trabajo basada en certificados X.509 (Credenciales de Aplicación Predeterminadas mTLS): tokens de GCP de corta duración generados a partir de un certificado de cliente, sin necesidad de JSON de cuenta de servicio.¹⁶¹ Confianza en certificados CA del SO (v2.1.101+): Los proxies TLS empresariales ahora funcionan de forma predeterminada: Claude Code confía en el almacén de certificados del SO. Configura CLAUDE_CODE_CERT_STORE=bundled para usar solo las CAs incluidas.¹⁵⁰

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

Para implementaciones empresariales detrás de proxies o a través de gateways de LLM:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Verificación

claude doctor

El comando reporta el tipo de instalación, la versión, la configuración del sistema y cualquier problema detectado.

Gestión de autenticación (v2.1.41+)

Gestiona la autenticación sin entrar en el REPL:⁹⁷

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

Flujo de trabajo común para cambiar entre cuentas u organizaciones:

claude auth logout && claude auth login

Consulta también: ¿Cómo depuro problemas? para solucionar fallos de autenticación.

Actualizaciones

Claude Code se actualiza automáticamente de forma predeterminada, comprobando al inicio y periódicamente durante las sesiones. Las actualizaciones se descargan en segundo plano y se aplican en el siguiente lanzamiento.

Desactiva las actualizaciones automáticas:

export DISABLE_AUTOUPDATER=1

O en settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Actualización manual:

claude update

Desinstalación

Instalación nativa (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Instalación nativa (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Configuración limpia (elimina toda la configuración):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Inicio rápido: tu primera sesión

1. Instala e inicia:

claude                           # Launch in current directory

2. Navega a un proyecto:

cd ~/my-project && claude        # Or launch from any git repo

3. Pídele a Claude que haga algo:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. Usa atajos clave durante tu sesión:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Continúa más tarde:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Consejo experto: Crea un archivo CLAUDE.md en la raíz de tu proyecto con comandos de compilación, convenciones de código y notas sobre la arquitectura. Claude lo lee en cada sesión: es lo que más impacto tiene en la calidad.

Modos de interacción principales

REPL interactivo

Inicia Claude Code sin argumentos para entrar al bucle interactivo de leer-evaluar-imprimir:

cd your-project
claude

El REPL mantiene el contexto de la conversación entre turnos. Escribe consultas directamente, recibe respuestas y continúa hasta que salgas con /exit o Ctrl+D.

Comienza con un prompt inicial para enfocar la sesión:

claude "explain the authentication flow in this project"

Consejo experto: El REPL conserva el estado entre eventos de compactación. Cuando el contexto crece demasiado, Claude resume automáticamente las conversaciones más antiguas mientras preserva las decisiones clave y los fragmentos de código. Puedes activarlo manualmente con /compact o agregar instrucciones personalizadas sobre qué preservar.

Modo no interactivo

El modo de impresión (-p) ejecuta una sola consulta y sale:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

Para una salida estructurada apta para analizar en scripts:

claude -p "count lines by file type" --output-format json

La salida JSON incluye todo lo que necesitas para automatización:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

Para procesamiento en tiempo real de la salida en streaming:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

Opciones de formato de salida:

Códigos de salida:

Controlar el comportamiento agéntico en modo -p:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-4-5-20250929

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

Patrón de integración CI/CD:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

Gestión de sesiones

Las sesiones conservan el historial de conversación para continuarla. La persistencia de sesión es esencial para trabajos complejos que abarcan varias sesiones:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

Sesiones vinculadas a PR (v2.1.27+, ampliado en v2.1.119+): Inicia una sesión vinculada a una pull request o merge request específica. A partir de v2.1.119, --from-pr acepta URLs de MR de GitLab, PR de Bitbucket y PR de GitHub Enterprise, además de github.com:⁸¹¹⁵⁹

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

Las sesiones también se vinculan automáticamente a PRs cuando las creas con gh pr create durante una sesión. Esto facilita retomar el trabajo en un PR específico más adelante. La insignia de PR del pie de página puede apuntar a una URL personalizada de revisión de código mediante la configuración prUrlTemplate (v2.1.119+); resulta útil cuando tu equipo enlaza desde los PRs hacia una herramienta de revisión separada.¹⁵⁹

/resume acepta URLs de PR (v2.1.122+). Pegar la URL de un PR en el cuadro de búsqueda de /resume ahora encuentra la sesión que originalmente creó ese PR; funciona en github.com, GitHub Enterprise, gitlab.com (y GitLab autoalojado) y bitbucket.org.¹⁶¹

Sesiones con nombre: Asigna un nombre a las sesiones al iniciarlas o durante una sesión:

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

Nota: --session-id requiere un UUID válido (por ejemplo, 550e8400-e29b-41d4-a716-446655440000). Para nombrar sesiones de forma legible, usa /rename y --resume en su lugar.

Claude Code almacena las sesiones como transcripciones JSONL. La ejecución de agentes asigna valores únicos de agentId con transcripciones almacenadas como agent-{agentId}.jsonl. La reanudación preserva el contexto completo de conversaciones previas.

Modo de planificación

El modo de planificación restringe a Claude a la exploración de solo lectura: sin ediciones de archivos, sin ejecución de bash, sin acciones destructivas. Claude diseña un enfoque de implementación, lo escribe en un archivo de plan y espera tu aprobación antes de ejecutar nada.

Entrar al modo de planificación:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

Cómo funciona:

1. Claude entra al modo de planificación (automáticamente para tareas complejas, o mediante Shift+Tab)
2. Explora el código usando herramientas de solo lectura: Read, Glob, Grep, WebSearch, WebFetch
3. Escribe un plan en .claude/plans/{session-slug}.md
4. Sale del modo de planificación con ExitPlanMode, presentando el plan para tu revisión
5. Tú apruebas, solicitas cambios o rechazas

Herramientas disponibles en modo de planificación: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. Las herramientas de edición (Edit, Write, Bash, NotebookEdit) están bloqueadas.

Después de aprobar el plan (v2.1.32+): Claude ofrece tres opciones: - “Sí, limpiar el contexto y aceptar ediciones automáticamente” (Shift+Tab): empieza desde cero con todo el contexto para el plan - “Sí, y aprobar las ediciones manualmente”: preserva el contexto, tú apruebas cada cambio - “Sí, aceptar ediciones automáticamente”: preserva el contexto, Claude ejecuta sin aprobación por edición

Limpiar el contexto automáticamente al aprobar es el flujo recomendado. Le da al plan una ventana de contexto fresca, lo que mejora significativamente la adherencia al plan: Claude se mantiene en el camino correcto durante más tiempo, sin que conversaciones antiguas interfieran.

Cuándo usar el modo de planificación: - Implementaciones de funciones nuevas con decisiones arquitectónicas - Refactorizaciones de varios archivos donde quieras revisar el enfoque primero - Bases de código desconocidas donde la exploración debe preceder a la modificación - Cualquier tarea donde existan múltiples enfoques válidos y quieras dar tu opinión

Consejo experto: Cuanto más tiempo dediques al modo de planificación, más probable será que Claude tenga éxito en la implementación. El modo de planificación es exploración prácticamente gratuita: sin llamadas a herramientas riesgosas, sin ediciones desperdiciadas. Úsalo con generosidad.

Análisis Profundo del Sistema de Configuración

Claude Code utiliza un sistema de configuración por capas. Comprender la jerarquía es esencial porque los niveles superiores anulan los inferiores, y las configuraciones empresariales no pueden eludirse de ninguna manera.

Jerarquía de Configuración

Consejo de experto: Usa .claude/settings.local.json para preferencias personales en proyectos compartidos (agrégalo a .gitignore). Usa .claude/settings.json para configuración de todo el equipo que se incluye en el control de versiones.

Referencia Completa de settings.json

Una configuración completa que demuestra todas las opciones principales:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-4-6-20260312-v1:0",
    "vertex": "claude-opus-4-6@20260312",
    "foundry": "anthropic.claude-opus-4-6"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

Referencia de Variables de Entorno

Autenticación y API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Configuración de modelo:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (Max/Team Premium default)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Configuración de proveedor en la nube:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region

Control de comportamiento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]

Configuración de herramientas:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Red y proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI y terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

Exportadores de OpenTelemetry + control de campos sensibles:¹⁶³

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set

Atributos de span de solicitud LLM en v2.1.121+: stop_reason, gen_ai.response.finish_reasons y user_system_prompt ahora se emiten en los spans de solicitud LLM. user_system_prompt está controlado por OTEL_LOG_USER_PROMPTS=1 ya que puede contener PII.¹⁶¹

Cambios a nivel de evento en v2.1.122+: Los atributos numéricos en los eventos de log api_request y api_error ahora se emiten como números (antes eran cadenas) — esto corrige los recolectores OTel descendentes que aplicaban tipado estricto al esquema. El nuevo evento de log claude_code.at_mention se dispara cuando Claude Code resuelve una mención @.¹⁶¹

Control de API / Modelo:¹⁶³

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:¹⁶³

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)

Shell / IDE:¹⁶³

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

Empresa / autenticación:¹⁶³

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)

Variables de skill (v2.1.69+):

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

Identidad del invocador SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=[email protected]        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Depuración:

ANTHROPIC_LOG=debug                             # Enable API request logging

¿Qué modelo debería elegir?

Elegir el modelo correcto para cada tarea afecta significativamente tanto el costo como la calidad. Claude Code ofrece cambio flexible de modelos en múltiples niveles.

Modelos disponibles

Opus 4.7 (16 de abril de 2026): El buque insignia actual. Ventana de contexto de 1M tokens a precio estándar — sin recargo por contexto largo. Salida máxima de 128K, solo pensamiento adaptativo (se eliminó el pensamiento extendido) y un nuevo nivel de esfuerzo xhigh recomendado como punto de partida para cargas de trabajo de codificación y agénticas.¹⁵² Corte de conocimiento confiable: enero de 2026. Corte de datos de entrenamiento: enero de 2026. ID del modelo: claude-opus-4-7. El precio coincide con Opus 4.6 a $5/$25 por MTok con escritura en caché de 5 min de $6.25, escritura en caché de 1 hora de $10 y lectura en caché de $0.50 por MTok.¹⁵¹ Opus 4.7 resuelve 3 veces más tareas de producción en SWE-Bench que Opus 4.6, obtiene un 70% en CursorBench (frente al 58% de 4.6) y eleva la resolución un 13% en el benchmark interno de codificación de 93 tareas de Anthropic.¹⁵¹ Utiliza un nuevo tokenizador — espera aproximadamente entre 1× y 1,35× recuentos de tokens para el mismo texto; aumenta el margen de max_tokens y los activadores de compactación.¹⁵² La visión admite imágenes de hasta 2.576 px / 3,75 MP con coordenadas de píxeles 1:1.¹⁵²

Benchmarks de codificación de Opus 4.7 (abril de 2026):¹⁵⁸

Opus 4.7 lidera SWE-bench Verified por 12,7 puntos sobre la línea base ampliamente citada de GPT-5-Codex y SWE-bench Pro por 6,6 puntos sobre GPT-5.4 (57,7%). En Terminal-Bench 2.0, GPT-5.3-Codex aún supera ligeramente a GPT-5.4 (77,3% frente a 75,1%) y ambos superan a Opus 4.7 (69,4%). El liderazgo en benchmarks es fluido; consulta las páginas de los proveedores antes de comprometerte con una elección de varios trimestres.

Modelo predeterminado por plan (Claude Code):¹⁵⁴

Opus 4.7 requiere Claude Code v2.1.111 o posterior; ejecuta claude update para actualizar.¹⁵⁴ Bedrock, Vertex y Foundry exponen Opus 4.7 mediante nombres de modelos completos explícitos o pins ANTHROPIC_DEFAULT_OPUS_MODEL, no a través del alias opus por defecto.¹⁵⁴

Cambios incompatibles en Messages API en Opus 4.7 (visibles para el llamador):¹⁵²

• Se eliminó budget_tokens del pensamiento extendido. Usa thinking: {type: "adaptive"} en su lugar. El pensamiento adaptativo está desactivado por defecto; las solicitudes sin el campo thinking se ejecutan sin pensamiento.
• Establecer temperature, top_p o top_k a un valor no predeterminado devuelve HTTP 400. Omite estos parámetros y guía al modelo mediante prompts.
• El contenido de pensamiento se omite de las respuestas por defecto. Establece thinking.display: "summarized" para restaurar el razonamiento visible (necesario si tu producto transmite el pensamiento a los usuarios).

Los presupuestos de tareas (encabezado beta task-budgets-2026-03-13) te permiten informar al modelo de un objetivo de tokens a través de un bucle agéntico completo mediante output_config.task_budget; mínimo 20K tokens.¹⁵²

Opus 4.6 (heredado): Aún disponible en claude-opus-4-6 con contexto de 1M y salida máxima de 128K. Considera migrar a Opus 4.7 para una mejor codificación agéntica. Opus 4.6 se lanzó originalmente el 5 de febrero de 2026.⁸⁶¹⁵¹ A partir de v2.1.117 (22 de abril de 2026), los suscriptores Pro y Max usan por defecto el esfuerzo high en Opus 4.6 y Sonnet 4.6 (anteriormente medium); Opus 4.7 se mantiene en xhigh. Este cambio restauró la inteligencia tras la degradación del esfuerzo del 4 de marzo al 7 de abril documentada en la autopsia del 23 de abril.¹⁵⁹¹⁶⁰

Sonnet 4.6 (17 de febrero de 2026): Modelo equilibrado; reemplazó a Sonnet 4.5 como predeterminado en claude.ai y Claude Cowork.¹⁰⁰ Mismo precio que Sonnet 4.5 ($3/$15 por MTok). Mejor rendimiento en búsqueda agéntica consumiendo menos tokens. Admite pensamiento extendido, pensamiento adaptativo y una ventana de contexto de 1M tokens (beta). Salida máxima de 64K (límite superior de 128K en v2.1.77).¹²⁶ Corte de conocimiento: agosto de 2025 (confiable), enero de 2026 (datos de entrenamiento). ID del modelo: claude-sonnet-4-6.

Claude Mythos Preview (7 de abril de 2026): Un modelo frontera de vista previa de investigación para trabajo de ciberseguridad defensiva, ofrecido bajo Project Glasswing.¹⁴⁶ Solo por invitación; no disponible de forma general. Anthropic presenta a Opus 4.7 como deliberadamente menos capaz que Mythos en dimensiones cibernéticas — un compromiso de seguridad — y ha abierto un Cyber Verification Program en https://claude.com/form/cyber-use-case para investigadores de seguridad legítimos que necesitan acceso elevado.¹⁵³

Por qué importan estas diferencias de precios: Una sesión típica de codificación consume entre 50K y 200K tokens de entrada y entre 10K y 50K tokens de salida. Con Haiku, eso equivale a $0,10-$0,45 por sesión. Con Opus, la misma sesión cuesta $0,50-$2,25, 5 veces más. Reserva Opus para problemas genuinamente difíciles.¹

Cuándo usar cada modelo

Haiku: Úsalo para subagents que hacen exploración, búsquedas simples de archivos, preguntas rápidas. Es ~5× más barato que Opus y responde más rápido. Perfecto para tareas en segundo plano donde no necesitas razonamiento profundo.

Sonnet: El caballo de batalla para el desarrollo diario cuando el costo importa. Maneja la mayoría de las tareas de codificación: implementar funciones, corregir errores, escribir pruebas, revisar código. Sonnet 4.6 ofrece una búsqueda agéntica mejorada y mayor eficiencia de tokens en comparación con Sonnet 4.5, con soporte de pensamiento adaptativo y una ventana de contexto de 1M a precio estándar.¹⁰⁰ A partir de Opus 4.7 (16 de abril de 2026), Claude Code usa Opus por defecto solo en los planes Max y Team Premium; las cuentas Pro, Team Standard, Enterprise y API mantienen Sonnet 4.6 como predeterminado hasta que Enterprise y API cambien a Opus 4.7 el 23 de abril de 2026.¹⁵⁴ Usa Sonnet cuando necesites tokens más baratos, latencia más rápida o economía de subagents.

Opus: El nivel insignia desde el 16 de abril de 2026, y el predeterminado en los planes Max y Team Premium.¹⁵¹¹⁵⁴ Reserva el razonamiento de mayor costo donde valga la pena: decisiones arquitectónicas, depuración complicada, comprensión de sistemas complejos, análisis de seguridad, trabajo agéntico de horizonte largo. Opus 4.7 resuelve 3× más tareas de producción en SWE-Bench que Opus 4.6, obtiene un 70% en CursorBench (frente al 58%) y eleva la resolución un 13% en un benchmark interno de codificación de 93 tareas.¹⁵¹ Claude Code usa por defecto el esfuerzo xhigh en Opus 4.7, ajustable mediante /effort (v2.1.111+).¹⁵³¹⁵⁴ Auto Mode está disponible para los suscriptores Max en Opus 4.7 a través del Anthropic API sin requerir --enable-auto-mode; otros planes/proveedores tienen disponibilidad específica del plan y controlada por administrador.¹⁵³ Contexto de 1M a precio estándar — sin recargo por contexto largo. Cambios de comportamiento que vale la pena conocer: Opus 4.7 sigue las instrucciones de manera más literal, calibra la longitud de la respuesta según la complejidad de la tarea, ejecuta menos subagents por defecto y adopta un tono más directo con menos frases orientadas a la validación. Si tus prompts contienen andamiaje para forzar mensajes de progreso intermedio o verificar el comportamiento, intenta eliminarlo.¹⁵²

Opusplan: Un modo híbrido que usa Opus para planificar (donde la calidad del razonamiento importa más) y Sonnet para ejecutar (donde la velocidad importa). Excelente para refactorización compleja donde quieres el mejor plan pero no necesitas razonamiento de nivel Opus para cada edición individual.

Cambiar de modelo

Durante la sesión:

> /model opus
> /model sonnet
> /model haiku

Al iniciar:

claude --model opus

Mediante variable de entorno:

export ANTHROPIC_MODEL=opus

En settings.json:

{
  "model": "claude-sonnet-4-5-20250929"
}

Específicamente para subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Contexto extendido

Para bases de código grandes o sesiones largas, habilita el contexto de 1M tokens:

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 con contexto de 1M

O dentro de una sesión:

> /model sonnet[1m]
> /model opus[1m]

Opus 4.7, Opus 4.6 y Sonnet 4.6 incluyen la ventana completa de contexto de 1M tokens a precio estándar — sin recargo por contexto largo.¹⁵⁵ Una solicitud de 900K tokens se factura a la misma tarifa por token que una de 9K tokens. Los descuentos por caché de prompts y procesamiento por lotes se aplican a tarifas estándar en toda la ventana de contexto.

En las suscripciones Max, Team y Enterprise, Opus con contexto de 1M se incluye automáticamente — no se necesita el sufijo [1m] (habilitado por defecto desde v2.1.75, 13 de marzo de 2026).¹²⁴¹⁵⁴ En Pro, el contexto de 1M es accesible mediante uso adicional. Los usuarios de API y de pago por uso tienen acceso completo a 1M a tarifas estándar por token.¹⁵⁴

Para deshabilitar las variantes de contexto de 1M en el selector de modelos, establece CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Verificar el modelo actual

> /status

El comando muestra el modelo actual, información de la cuenta, configuración aplicada y otros estados de la sesión.

Etiquetas del selector de modelos (v2.1.51+): El selector /model ahora muestra etiquetas legibles (por ejemplo, “Sonnet 4.6”) en lugar de IDs de modelos sin procesar para versiones ancladas, con sugerencias de actualización cuando hay versiones más nuevas disponibles.¹⁰⁵

Modo rápido (v2.1.36+)

El modo rápido proporciona una salida significativamente más veloz del mismo modelo; no cambia a un modelo más barato. Actívalo durante una sesión con /fast.⁹³

> /fast            # Activa/desactiva el modo rápido

Precios (modo rápido de Opus 4.6):

El modo rápido es vista previa de investigación, exclusivo de Opus 4.6, y ofrece una salida ~2,5× más rápida con un precio 6× la tarifa base.¹⁵⁶ Activar /fast cambia automáticamente la sesión a Opus 4.6 si estabas en otro modelo; desactivar /fast te deja en Opus 4.6 hasta que cambies mediante /model. El modo rápido no está disponible en Opus 4.7, Sonnet, Haiku ni mediante Bedrock/Vertex/Foundry. Requiere uso adicional habilitado y, para Team/Enterprise, habilitación por parte del administrador.

Cuándo usar el modo rápido: - Iterando rápidamente en cambios pequeños donde la latencia es el cuello de botella - Generando pruebas, código repetitivo o boilerplate donde la velocidad importa más que el costo - Trabajando en una lista de tareas similares de forma secuencial

Cuándo NO usar el modo rápido: - Tareas agénticas de larga duración (el costo se acumula rápido a tarifas 6×) - Trabajo de subagents en segundo plano (nadie está esperando la salida) - Sesiones con presupuesto ajustado

El modo rápido de Opus 4.6 incluye la ventana completa de contexto de 1M (v2.1.50+). El precio del modo rápido es plano en todo el contexto de 1M — sin recargo adicional por contexto largo.¹⁰³¹⁵⁶

Consejo de experto: El modo rápido no se combina con opusplan (opusplan ya mezcla Opus y Sonnet; el modo rápido solo afecta a Opus 4.6). Usa el modo rápido directamente cuando la latencia importe más que el costo, y desactívalo para trabajo autónomo o por lotes. /fast requiere uso adicional; los administradores de Team/Enterprise pueden necesitar habilitarlo primero (corrección en v2.1.37).⁹³¹⁵⁶

Control de esfuerzo (v2.1.111+, Opus 4.7)

Opus 4.7 introduce un nuevo dial de esfuerzo que ajusta el equilibrio entre velocidad e inteligencia. Usa /effort durante una sesión:

> /effort              # abre un control deslizante interactivo (teclas de flecha + Enter)
> /effort xhigh        # establecer directamente

Claude Code ahora usa por defecto el esfuerzo xhigh para Opus 4.7. xhigh es exclusivo de Opus 4.7 — otros modelos recurren a high. Claude Managed Agents maneja el esfuerzo automáticamente; el parámetro de esfuerzo es un concepto de Messages API.¹⁵²¹⁵³

Auto Mode en Max (v2.1.111+)

Auto Mode — un reemplazo más seguro para --dangerously-skip-permissions — está disponible para los suscriptores Max en Opus 4.7 a través del Anthropic API sin --enable-auto-mode.¹⁵³ Un clasificador Sonnet-4.6 revisa cada acción antes de ejecutarla, verificando la coincidencia de intención y la seguridad. Nota (v2.1.111+): se eliminó la bandera --enable-auto-mode; inicia una sesión en Auto Mode con --permission-mode auto en su lugar. Auto Mode no está disponible en Pro; según los documentos de modos de permiso de Anthropic, actualmente es solo directo de Anthropic-API — Bedrock, Vertex y Foundry aún no son compatibles.

Reglas personalizadas sin perder los valores predeterminados (v2.1.118+). Las versiones anteriores hacían que autoMode.allow, autoMode.soft_deny y autoMode.environment fueran excluyentes: definías tu propia lista y perdías las reglas de seguridad integradas. El centinela $defaults resuelve esto — se expande en línea a la lista integrada exactamente en la posición donde lo coloques, para que puedas superponer reglas personalizadas a su alrededor:¹⁵⁹

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // tus adiciones, antepuestas
      "$defaults",                // lista de allow integrada insertada aquí
      "Bash(git push:origin/feature/*)"  // añadidas al final
    ]
  }
}

Opt-in “No volver a preguntar” (v2.1.118+). El prompt de opt-in de Auto Mode ahora ofrece una opción “No volver a preguntar”, para que los usuarios frecuentes puedan suprimir el explicador sin tener que automatizar una bandera.¹⁵⁹

Nuevos comandos en v2.1.105–v2.1.114¹⁵³¹⁵⁷

Resumen de sesión (v2.1.108+)

Una nueva función a nivel de sesión que muestra el contexto cuando regresas a una sesión pausada. Habilitada por defecto y desactivable mediante /config o CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0. El modelo también puede invocar comandos slash integrados (/init, /review, /security-review) mediante la herramienta Skill — extiende el patrón de subagent/skill.¹⁵³

Notificaciones push (v2.1.110+)

Cuando Remote Control está configurado con “Push cuando Claude decide” habilitado, Claude ahora puede enviar notificaciones push móviles a su discreción mediante una nueva herramienta de notificación push. Se combina con la superficie móvil/web existente de Remote Control.¹⁵³ /context, /exit y /reload-plugins ahora también funcionan desde clientes Remote Control.

Herramienta Windows PowerShell (v2.1.111+, despliegue)

Claude Code está implementando una herramienta nativa de Windows PowerShell. En Linux/macOS, habilítala con CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (requiere pwsh en PATH). En Windows, la misma variable controla la activación/desactivación durante el despliegue.¹⁵³

Auto-aprobación en modo de permiso (v2.1.119+). Los comandos de la herramienta PowerShell ahora pueden recibir auto-aprobación en modo de permiso de la misma manera que los comandos Bash. Las reglas de permiso como PowerShell(Get-*:*) y la sintaxis de patrones existente ahora omiten el prompt para operaciones de solo lectura, igualando la ergonomía operativa que los equipos ya tienen en Linux/macOS.¹⁵⁹

Reducción de permisos: Bash de solo lectura (v2.1.111+)

Los patrones de Bash de solo lectura con argumentos glob (por ejemplo, ls *.ts, cat src/*.md) y los comandos que comienzan con cd <project-dir> && ya no activan un prompt de permiso.¹⁵³ Combinado con /less-permission-prompts, espera muchas menos interrupciones en los flujos de trabajo cotidianos.

Trazabilidad distribuida (v2.1.110+)

Las sesiones de SDK y headless ahora leen TRACEPARENT y TRACESTATE del entorno, vinculando las ejecuciones de Claude Code a trazas distribuidas. Combina con OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) para emitir cuerpos completos de solicitud/respuesta de API como eventos de log de OpenTelemetry para depuración.¹⁵³

Distribución de binario nativo (v2.1.113+)¹⁵⁷

v2.1.113 cambia la forma en que se lanza CLI: claude ahora genera un binario nativo de Claude Code mediante una dependencia opcional por plataforma en lugar de ejecutar JavaScript empaquetado. Los comandos de instalación y actualización siguen siendo los mismos, y los equipos no necesitan cambiar los scripts de despliegue.

Atajos del editor de prompts (v2.1.113+)¹⁵⁷

El editor de prompts incorpora navegación al estilo readline en entrada multilínea, además de desplazamiento del viewport en pantalla completa:

Están activados por defecto. No se requiere configuración de teclas.

Tiempo de espera por estancamiento de subagents (v2.1.113+)¹⁵⁷

Los subagents que se estancan a mitad del flujo ahora fallan con un error claro después de 10 minutos en lugar de quedar colgados silenciosamente. Combina con CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para una cobertura más amplia de procesos atascados en API de streaming.

Corrección de estabilidad v2.1.114¹⁵⁷

v2.1.114 (18 de abril de 2026) lanza una sola corrección: el diálogo de permiso podía bloquearse cuando un compañero de equipo de agent-teams solicitaba permiso de herramienta. Actualiza si usas Agent Teams.

¿Cuánto cuesta Claude Code?

Entender y controlar los costos es esencial para un uso sostenible de Claude Code. Consulta también Selección de modelo para conocer las capacidades de cada modelo y Marcos de decisión para elegir el modelo adecuado según la tarea.

Visualizar costos

> /cost

Salida:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Los usuarios con suscripción ven un desglose por modelo y por aciertos de caché en /cost, que muestra exactamente qué modelos consumieron tokens y cuánto se sirvió desde la caché (v2.1.92+).¹⁴⁴

Planes de suscripción

Límites de uso (agosto de 2025): Anthropic introdujo límites de uso semanales para los suscriptores de pago. Los suscriptores de Max pueden comprar uso adicional más allá del límite a las tarifas estándar de API.²¹

Precios de tokens de API (abril de 2026)¹¹⁵¹

Para usuarios facturados por API, precios por millón de tokens:

Precios para contexto de 1M (abril de 2026): Opus 4.7, Opus 4.6, Sonnet 4.6 y Mythos Preview incluyen 1M a tarifas estándar por MTok — sin recargo por contexto extendido.¹⁵⁵ Esta es una consolidación reciente; las indicaciones anteriores sobre Opus 4.6 o Sonnet 4.6 pagando 2× en entrada / 1,5× en salida por encima de 200K tokens de entrada ya no están vigentes. Opus 4.5 legado y los modelos anteriores conservan sus estructuras de precios originales.

Precios por residencia de datos: Especificar inferencia solo en EE. UU. mediante inference_geo agrega un multiplicador de 1,1× a todos los precios de tokens, incluyendo lecturas y escrituras de caché (modelos Opus 4.6+).¹⁵⁵

El prompt caching reduce significativamente los costos de entrada repetida: las escrituras de caché cuestan 1,25× la base (caché de 5 min) o 2× (caché de 1 h), pero las lecturas de caché cuestan solo 0,1×, un ahorro del 90%. Para sistemas RAG y asistentes de código con contexto repetido, el caching puede reducir costos entre 88-95%.

Batch API ofrece descuentos del 50% con un tiempo de respuesta de 24 horas para tareas no urgentes como suites de pruebas nocturnas.

Política de cuentas múltiples⁵⁹

¿Puedes tener varias cuentas de Claude? Sí, para casos de uso legítimos. Anthropic permite explícitamente las cuentas múltiples cuando sirven a propósitos distintos.

Lo que está permitido:

Límites técnicos: - Se pueden verificar hasta 3 cuentas con el mismo número de teléfono - Las múltiples suscripciones de pago desde la misma IP/red están explícitamente admitidas - Las cuentas son totalmente separadas; no hay transferencia de chats ni de proyectos entre ellas

Lo que está prohibido (según la Política de uso): - Crear cuentas para evadir prohibiciones después de ser baneado - Coordinar actividad maliciosa entre cuentas para evitar la detección - Usar múltiples cuentas para eludir los límites de uso o los créditos del nivel gratuito

Nota del mundo real: En enero de 2026, el usuario avanzado Jeffrey Emanuel (@doodlestein) tenía 22 cuentas Max marcadas automáticamente y temporalmente bloqueadas. El empleado de Anthropic Thariq (@trq212) lo resolvió en 4 horas tras confirmar el uso legítimo. Si usas Claude Code intensivamente tanto para trabajo como para proyectos personales en múltiples cuentas, eso es exactamente para lo que está diseñado el servicio, pero no intentes burlar el sistema.

En caso de duda: Contacta al Soporte de Anthropic para confirmar tu configuración específica por escrito.

Factores de costo

Ejemplos de costo del mundo real

Consejo de ahorro: Usar Haiku para subagentes de exploración y Sonnet para implementación suele reducir los costos entre 40-50% en comparación con usar Sonnet para todo.

Gestión de costos del equipo

TPM/RPM recomendados según el tamaño del equipo:

Tarifas ocultas de herramientas

Más allá del precio por token, algunas herramientas incurren en cargos separados:¹⁶

Estos se acumulan en los bucles de agentes. Un ciclo de depuración de 100 iteraciones con Bash cuesta ~24.500 tokens de entrada adicionales solo en sobrecarga.

Estrategias de ahorro

1. Usa Haiku para subagentes: La mayor parte de la exploración no necesita Sonnet
2. Activa el prompt caching: Es el predeterminado, pero verifica que no esté desactivado
3. Configura turnos máximos: claude --max-turns 5 evita conversaciones descontroladas
4. Usa el modo plan para exploración: Sin ejecución = sin operaciones costosas accidentales
5. Compacta proactivamente: Menos contexto = menos tokens
6. Limita la salida: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. Batch API para trabajo no urgente: 50% de descuento en tokens de entrada y salida

Monitoreo del uso

• Consola de Claude: platform.claude.com (requiere rol de Admin o Billing)
• Límites del workspace: Establece límites de gasto por workspace
• Bedrock/Vertex: Usa el monitoreo nativo de costos en la nube
• LiteLLM: Para seguimiento detallado por usuario con proveedores externos

Uso de tokens en segundo plano

Algunas operaciones consumen tokens en segundo plano: - Resumen de conversaciones para /resume - Comandos /cost y /status - Compactación automática

Normalmente menos de $0,04 por sesión.

API de analítica de Claude Code (Team/Enterprise)⁵³

Accede programáticamente a la analítica de uso y métricas de productividad de Claude Code de tu organización mediante la Admin API.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requisitos: - Clave de Admin API (sk-ant-admin...) - Plan Team o Enterprise - Rol de Admin, Billing o Developer

Métricas disponibles:

Ejemplo de solicitud:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Casos de uso: - Análisis de productividad de desarrolladores (sesiones, commits, PRs) - Métricas de uso de herramientas (tasas de aceptación/rechazo para Edit, Write, etc.) - Seguimiento y asignación de costos entre equipos - Justificación de ROI para herramientas de codificación con IA

Nota: Los datos aparecen en un plazo de 1 hora tras la finalización de la actividad. Solo los datos con más de 1 hora de antigüedad se incluyen en las respuestas para garantizar la consistencia.

Marcos de decisión

Saber que las funciones existen no es suficiente. Necesitas saber cuándo usar cada una. Estos árboles de decisión transforman el conocimiento en acción.

¿Qué modelo debo usar?

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 4.7 (xhigh effort default)
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.75/task
                           Balance: Best overall when cost matters

Regla general: Opus 4.7 es el predeterminado para Max y Team Premium. En Pro/Team Standard/Enterprise/API, Sonnet 4.6 es el predeterminado (Enterprise + Anthropic API cambian a Opus 4.7 el 23 de abril de 2026).¹⁵⁴ Baja a Haiku para subagents. Escala a Opus cuando la respuesta de Sonnet te parezca superficial. Con equipos de agentes (v2.1.32+), Opus puede coordinar múltiples agentes trabajando en paralelo en diferentes subtareas.⁸⁶

¿Comando vs Skill vs Subagent vs equipo de agentes?

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

¿Hook vs prompt?

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

¿Cuándo usar extended thinking?

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

Alterna con Alt+T durante la sesión. Los presupuestos de pensamiento más altos cuestan más; empieza con el mínimo e increméntalo solo si las respuestas te parecen apresuradas.

Pensamiento adaptativo de Opus 4.6: Opus 4.6 ajusta automáticamente la profundidad del pensamiento según la complejidad del problema. Para la mayoría de las tareas, el control explícito del presupuesto de pensamiento no es necesario — Opus escala para problemas difíciles y se mantiene rápido para los simples. Alternar el pensamiento manualmente es más útil con Sonnet cuando quieres forzar un análisis más profundo.

¿Qué superficie de ejecución?

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Equipos de agentes vs subagents vs sesiones paralelas

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

¿Qué tipo de hook?

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

¿Cuándo usar /fast?

Is response speed more important than depth right now?
│
├── YES → Use /fast
│         Same Opus 4.6 model, faster output
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast activa el modo rápido para la sesión actual. Usa el mismo modelo (Opus 4.6) con velocidad de salida optimizada — NO cambia a un modelo más económico.

¿Cómo funciona el sistema de permisos?

El sistema de permisos de Claude Code proporciona control granular sobre qué operaciones pueden ejecutarse. Comprenderlo es esencial tanto para la seguridad como para la eficiencia del flujo de trabajo. Consulta también Despliegue empresarial para conocer la configuración gestionada que aplica permisos en toda la organización.

Niveles de permisos

Herramientas de solo lectura (aprobadas automáticamente): - Read - Leer el contenido de archivos - Glob - Buscar archivos por patrón - Grep - Buscar dentro del contenido de archivos - WebSearch - Buscar en la web - LSP - Inteligencia de código (ir a definición, buscar referencias, documentación al pasar el cursor)²⁵

Capacidades de la herramienta LSP (v2.0.74+): La herramienta LSP ofrece inteligencia de código similar a la de un IDE: - Ir a definición: salta al lugar donde se define un símbolo - Buscar referencias: enumera todos los usos de un símbolo en el código - Documentación al pasar el cursor: obtén información de tipos y documentación de cualquier símbolo - Funciona con TypeScript, Python, Go, Rust y otros lenguajes con soporte para LSP - Requiere que el servidor de lenguaje esté disponible (normalmente se instala con tu cadena de herramientas)

Herramientas de modificación (requieren aprobación): - Edit - Modificar archivos existentes - Write - Crear archivos nuevos - Bash - Ejecutar comandos de shell - WebFetch - Obtener el contenido de URLs - NotebookEdit - Modificar notebooks de Jupyter

La primera vez que se ejecuta una herramienta de modificación, Claude Code solicita aprobación. Las aprobaciones se mantienen durante la sesión salvo que se configure explícitamente lo contrario.

Modos de permisos

Modo Auto (v2.1.85+): un reemplazo más seguro de --dangerously-skip-permissions. Un modelo clasificador independiente (Sonnet 4.6) revisa cada acción antes de ejecutarla, comprobando que coincida con la intención del usuario y que sea segura.¹³¹

Cómo funciona: - Las acciones de solo lectura y las ediciones de archivos en el directorio de trabajo se aprueban automáticamente - Las reglas personalizadas de allow/deny se resuelven primero - Todo lo demás pasa al clasificador para su evaluación - Si se bloquea, Claude prueba un enfoque alternativo automáticamente

Bloqueado automáticamente por defecto: curl | bash, force-push a main, despliegues/migraciones en producción, eliminaciones masivas en la nube, cambios de IAM/permisos, envío de datos sensibles al exterior.¹³²

Disyuntor (circuit breaker): 3 bloqueos consecutivos o 20 totales en una sesión hacen que se vuelva a las solicitudes manuales.¹³²

# Enable at startup
claude --enable-auto-mode

# Or cycle into it during a session
Shift+Tab  # Cycles through: default → acceptEdits → auto → plan

Disponibilidad: primero para usuarios del plan Team, luego Enterprise y API. Requiere Sonnet 4.6 u Opus 4.6.¹³¹

Modo YOLO (v2.0.68+): para una operación totalmente autónoma sin ningún clasificador de seguridad, usa el flag --dangerously-skip-permissions. El flag dice sí a todo: ediciones de archivos, comandos de bash, todas las llamadas a herramientas. La palabra “dangerous” es intencional. El modo Auto es la alternativa recomendada para la mayoría de los casos de uso.⁶¹

claude --dangerously-skip-permissions

Establece el modo mediante CLI:

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

Alterna durante la sesión:

Shift+Tab  # Cycles through modes

En settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Sintaxis de las reglas de permisos

Las reglas granulares controlan operaciones específicas. Las reglas se evalúan en orden: gana la primera coincidencia.

Patrones de comandos Bash:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

El asterisco proporciona coincidencia por prefijo: Bash(npm run test:*) permite npm run test, npm run test:unit y npm run test:integration.

Limitación importante: los patrones Bash coinciden únicamente por prefijo, no son expresiones regulares. Un patrón como Bash(curl http:*) no coincidirá con curl -X GET http://... porque las opciones aparecen antes que la URL. Para un bloqueo fiable, deniega el comando por completo: Bash(curl:*).

Patrones de operaciones con archivos:

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Sintaxis de rutas: - Rutas relativas: Edit(src/**) - relativas al directorio de trabajo - Absolutas desde el archivo de configuración: Edit(/build/**) - relativas a la ubicación del archivo de settings - Verdaderamente absolutas: Edit(//tmp/**) - empiezan por // - Directorio home: Read(~/.zshrc)

Patrones de herramientas MCP:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

Usa la sintaxis con comodín mcp__server__* para permitir o denegar todas las herramientas de un servidor MCP específico.³⁹ La sintaxis con comodín es útil para habilitar rápidamente todas las herramientas de servidores de confianza o para bloquear servidores enteros provenientes de fuentes no confiables.

Patrones de WebFetch:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Directorios adicionales

Amplía el acceso de Claude más allá del proyecto actual:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Los directorios adicionales son esenciales para monorepos o cuando Claude necesita hacer referencia a código en directorios hermanos.

Modo sandbox

Habilita el aislamiento de sistema de archivos y red:

> /sandbox

O configúralo en settings:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

En modo sandbox: - El acceso al sistema de archivos queda restringido al directorio del proyecto - El acceso a la red está controlado - Ciertos comandos quedan excluidos de las restricciones del sandbox - Los comandos de Bash se aprueban automáticamente si autoAllowBashIfSandboxed está en true

Consejo de experto: el modo sandbox es excelente para ejecutar Claude sobre bases de código no confiables. Actívalo cuando explores proyectos desconocidos o cuando quieras una capa adicional de protección. Las pruebas internas de Anthropic encontraron que el sandboxing reduce las solicitudes de permisos en un 84%.⁴⁵ El sandbox utiliza primitivas a nivel del sistema operativo (seatbelt en macOS, bubblewrap en Linux) para el aislamiento del sistema de archivos y la red, de modo que incluso una inyección de prompts exitosa queda totalmente contenida. Anthropic ha publicado el runtime del sandbox como código abierto para los equipos que construyen sus propios agentes.⁸⁹

Notas de seguridad (v2.1.34+): los comandos excluidos del sandbox mediante sandbox.excludedCommands o dangerouslyDisableSandbox podían anteriormente eludir la regla de permiso de Bash cuando autoAllowBashIfSandboxed estaba habilitado; esto se corrigió en v2.1.34.⁹⁴ A partir de v2.1.38, las escrituras en .claude/skills están bloqueadas en modo sandbox, lo que impide que una inyección de prompts modifique las definiciones de skills.⁹⁵ v2.1.77 añade una configuración allowRead del sistema de archivos del sandbox para volver a permitir el acceso de lectura dentro de regiones denyRead, útil cuando quieres bloquear la mayor parte de un árbol de directorios pero incluir en la lista blanca subdirectorios específicos.¹²⁶

Exención de la configuración de agentes en .claude/ (v2.1.121+): --dangerously-skip-permissions ya no solicita confirmación para escrituras en .claude/skills/, .claude/agents/ y .claude/commands/.¹⁶¹

Endurecimiento de seguridad en v2.1.113:¹⁵⁷

• sandbox.network.deniedDomains bloquea hosts específicos incluso cuando un comodín más amplio en allowedDomains los permitiría. Usa la lista de bloqueo para cortar pastebins, servicios de subida de archivos o hosts conocidos como maliciosos sin reescribir toda tu política de permitidos.
• Reglas de denegación con comandos envoltorio. Las reglas de denegación de Bash ahora coinciden con comandos envueltos en env, sudo, watch, ionice, setsid y envoltorios de exec similares. Reglas como Bash(rm:*) ahora capturan env rm -rf, sudo rm -rf y patrones de bypass equivalentes.
• Las reglas allow Bash(find:*) ya no aprueban automáticamente find -exec ni find -delete. Esos flags ejecutan comandos y eliminan archivos, así que Claude Code los enruta por la vía normal de permisos.
• Protección contra eliminaciones en macOS. Las reglas allow Bash(rm:*) ahora tratan /private/etc, /private/var, /private/tmp y /private/home como objetivos de eliminación peligrosos. /var, /etc y /tmp son enlaces simbólicos a /private/, por lo que la forma anterior de la regla pasaba por alto los objetivos canónicos.

¿Cómo funcionan los hooks?

Los hooks ejecutan comandos de shell deterministas en puntos específicos del flujo de trabajo de Claude Code. A diferencia de pedirle a Claude que realice acciones mediante prompts, los hooks garantizan la ejecución sin importar el comportamiento del modelo. Son esenciales para hacer cumplir los estándares del equipo y automatizar tareas repetitivas. Consulta Marcos de decisión para ver el árbol de decisión “¿Qué tipo de hook?” que cubre los hooks de comando, prompt y agente.

Por qué hooks en lugar de prompts: Decirle a Claude “ejecuta siempre Prettier después de editar archivos” funciona algunas veces. Pero Claude podría olvidarlo, priorizar la velocidad o decidir que el cambio es “demasiado pequeño”. Los hooks garantizan la ejecución: cada Edit o Write activa tu formateador, todas las veces, sin excepciones. Para cumplimiento, seguridad y estándares de equipo, lo determinista le gana a lo probabilístico.⁷

Eventos disponibles

Configuración de hooks

Define los hooks en settings.json o en un hooks.json dedicado:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

El campo matcher determina qué herramientas activan un hook:

{"matcher": "*"}              // Coincide con todas las herramientas
{"matcher": "Bash"}           // Coincide solo con Bash
{"matcher": "Edit|Write"}     // Coincide con Edit o Write
{"matcher": "mcp__github"}    // Coincide con herramientas del servidor MCP
{"matcher": ""}               // Coincide para eventos sin herramientas (como UserPromptSubmit)

Protocolo de entrada/salida de hooks

Los hooks reciben JSON por stdin:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Enriquecimiento de eventos de hooks (v2.1.69+): Todos los eventos de hooks ahora incluyen los campos agent_id y agent_type cuando se activan desde un subagente o una sesión --agent, además de un campo worktree en los comandos de hooks de la línea de estado.¹¹⁷

Los hooks Stop/SubagentStop (v2.1.47+) reciben un campo adicional last_assistant_message que contiene el texto de la respuesta final de Claude, para que los hooks puedan inspeccionar la salida sin analizar archivos de transcripción:

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

Los códigos de salida controlan el comportamiento: - 0: Éxito: la operación continúa. Stdout se muestra en modo verboso (Ctrl+O). Para UserPromptSubmit y SessionStart, stdout se agrega al contexto. - 2: Error bloqueante: la operación se detiene. Stderr se convierte en el mensaje de error que se devuelve a Claude. - 1, 3, etc.: Error no bloqueante: la operación continúa. Stderr se muestra como advertencia en modo verboso.

Para un control avanzado, los hooks pueden generar JSON:

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

Control de decisión de PreToolUse (formato preferido): Los hooks de PreToolUse usan hookSpecificOutput para un control más rico: tres resultados (allow/deny/ask) más la capacidad de modificar la entrada de la herramienta e inyectar contexto:⁹⁶

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Nota: Los campos de nivel superior decision y reason están en desuso para PreToolUse. Usa en su lugar hookSpecificOutput.permissionDecision y hookSpecificOutput.permissionDecisionReason. Otros eventos (PostToolUse, Stop, etc.) todavía usan decision de nivel superior.⁹⁶

Título de sesión de UserPromptSubmit (v2.1.94+): Los hooks UserPromptSubmit pueden establecer el título de la sesión vía hookSpecificOutput.sessionTitle.¹⁴⁷

Hooks asíncronos (enero de 2026)

Los hooks ahora pueden ejecutarse en segundo plano sin bloquear la ejecución de Claude Code. Agrega async: true a la configuración de tu hook:⁸⁸

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Cuándo usar hooks asíncronos: - Notificaciones (Slack, email, Pushover) que no deberían ralentizar la sesión - Registro y telemetría que pueden ejecutarse en segundo plano - Posprocesamiento no crítico (analítica, copias de seguridad)

Cuándo NO usar hooks asíncronos: - Formateo (debe completarse antes de la siguiente edición) - Validación (debe bloquear ante un fallo) - Cualquier hook que necesite modificar la entrada/salida de la herramienta

Hooks basados en prompts y agentes (v2.1.32+)

Más allá de los hooks de comandos de shell (type: "command"), Claude Code admite dos tipos de hooks impulsados por LLM que evalúan condiciones usando razonamiento de IA en lugar de scripts.⁹⁶

Hooks de prompt (type: "prompt") envían un prompt de un solo turno a un modelo rápido de Claude. El modelo retorna { "ok": true } para permitir o { "ok": false, "reason": "..." } para bloquear:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hooks HTTP (type: "http") envían la entrada de JSON del evento como una solicitud POST a una URL y reciben JSON de vuelta. Úsalos para webhooks, servicios de notificación externos o validación basada en API (v2.1.63+):¹¹¹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

Los hooks HTTP usan el mismo formato de decisión que los hooks de comando (retornan JSON con decision y reason). Se enrutan a través del proxy de red del sandbox cuando el sandboxing está habilitado. No se admiten para los eventos SessionStart/Setup.

Hooks de agente (type: "agent") generan un subagente con acceso a herramientas (Read, Grep, Glob) para verificación de múltiples turnos. Úsalos cuando la verificación requiera inspeccionar archivos reales o salida de pruebas:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Usa $ARGUMENTS como un marcador de posición para la entrada de JSON del hook. Ambos tipos admiten los campos model (por defecto, modelo rápido) y timeout. Eventos admitidos: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle no admite hooks de prompt/agente.

Hooks de herramientas MCP (v2.1.118+)

Los hooks ahora pueden invocar una herramienta MCP directamente vía type: "mcp_tool", evitando la necesidad de envolver un subproceso de Bash que llame al servidor.¹⁵⁹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

Esto se combina bien con los servidores MCP que los usuarios ya tienen configurados: cualquier herramienta accesible desde /mcp se vuelve invocable por hooks.

duration_ms en hooks PostToolUse (v2.1.119+)

Las entradas de los hooks PostToolUse y PostToolUseFailure ahora incluyen duration_ms, el tiempo de ejecución de la herramienta excluyendo los prompts de permisos y los hooks PreToolUse.¹⁵⁹ Útil para detección de herramientas lentas, registros de auditoría y métricas de latencia por herramienta:

# Stderr-flagged warning when an Edit takes more than 10 seconds
DUR=$(jq -r '.duration_ms')
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $TOOL_INPUT_FILE_PATH" >&2
fi

updatedToolOutput para todas las herramientas (v2.1.121+)

En la v2.1.118, los hooks de herramientas MCP obtuvieron la capacidad de reemplazar la salida de la herramienta vía hookSpecificOutput.updatedToolOutput. A partir de la v2.1.121, el mismo campo funciona para cualquier hook PostToolUse: herramientas integradas (Bash, Read, Edit, Glob, Grep, etc.), herramientas de subagentes y herramientas MCP. Casos de uso: redactar contenido sensible de la salida de cualquier herramienta, normalizar la estructura para los consumidores posteriores, inyectar metadatos antes de que el agente lea el resultado.¹⁶¹

Variables de entorno de hooks

Los hooks tienen acceso a variables de entorno para resolver rutas:⁹⁶

Persistir variables de entorno desde SessionStart:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Seguridad de hooks HTTP (v2.1.51+): Los hooks HTTP que interpolan variables de entorno en cabeceras ahora requieren una lista explícita de allowedEnvVars. Esto evita la exfiltración arbitraria de variables de entorno a través de los valores de las cabeceras. Los hooks HTTP también se enrutan a través del proxy de red del sandbox cuando el sandboxing está habilitado, haciendo cumplir la lista de dominios permitidos. Los hooks HTTP no se admiten para los eventos SessionStart/Setup.¹⁰⁵

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Confianza del workspace de hooks (v2.1.51+): Los comandos de hooks statusLine y fileSuggestion ahora requieren la aceptación de la confianza del workspace antes de ejecutarse en modo interactivo, cerrando un posible vector de seguridad.¹⁰⁵

Ejemplos prácticos de hooks

Formatear automáticamente archivos TypeScript después de editar:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

Registrar todos los comandos bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

Bloquear el acceso a archivos sensibles:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0

Ejecutar pruebas después de cambios en el código:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Sistema de notificaciones personalizado:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

Inyectar contexto dinámico en los prompts:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Depuración de hooks

Habilita el modo de depuración para resolver problemas con los hooks:

claude --debug

El modo de depuración registra: - Tiempos de ejecución de los hooks - Datos de entrada/salida - Mensajes de error y stack traces - Resultados de decisiones (allow/reject/ask)

Visualización del origen del hook (v2.1.75+): Cuando un hook requiere confirmación del usuario, el prompt de permisos ahora muestra el origen del hook (settings, plugin o skill), facilitando la identificación de qué componente está solicitando acceso.¹²⁴

Hooks con alcance de componente (v2.1.0+)

Los hooks pueden definirse directamente en Skills, subagentes y comandos slash usando frontmatter. Estos hooks tienen un alcance limitado al ciclo de vida del componente y solo se ejecutan cuando ese componente está activo.⁴¹

Skill con hooks integrados:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

Eventos admitidos: PreToolUse, PostToolUse, Stop

La opción once (solo skills y comandos slash) garantiza que el hook se ejecute una sola vez por sesión, lo cual es útil para tareas de limpieza o finalización.

Estrategia para sesiones de larga duración

Para sesiones de Claude Code nocturnas o desatendidas, configura los hooks para mantener a Claude encarrilado sin intervención manual. La idea clave: usar hooks de linting y testing como guardarraíles que obliguen a Claude a corregir problemas antes de continuar.⁶⁴

El patrón “No te detengas hasta que pasen las pruebas”:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

Estrategia para sesiones nocturnas:

1. Verificación previa: Usa un hook Setup para verificar que el entorno esté listo
2. Validación continua: Los hooks PostToolUse ejecutan pruebas después de cada cambio
3. Puerta de finalización: Los hooks Stop verifican todos los criterios de aceptación antes de que Claude declare “listo”
4. Notificación: Los hooks Stop pueden notificarte vía Slack/Pushover cuando Claude termine o se atasque

Combínalo con --dangerously-skip-permissions en un contenedor en sandbox para ejecuciones nocturnas totalmente autónomas. Claude seguirá iterando hasta que las pruebas pasen o agote sus opciones.

¿Qué es MCP (Model Context Protocol)?

MCP extiende Claude Code con acceso a herramientas externas, bases de datos, APIs y servicios mediante un protocolo estandarizado. El ecosistema ha explotado: MCP ahora cuenta con 100 millones de descargas mensuales y más de 3.000 servidores indexados en MCP.so (enero de 2026), consolidando su posición como el estándar de la industria para conectar la IA a herramientas y datos.³⁵⁴ Comprender MCP es esencial para integrar Claude en tu cadena de herramientas existente.

Por qué MCP es importante para los desarrolladores: Sin MCP, Claude Code solo puede leer archivos y ejecutar comandos bash. Con MCP, Claude puede consultar tu base de datos de producción, crear tickets en Jira, revisar PRs de GitHub, comprobar errores en Sentry e interactuar con cualquier API que use tu equipo, todo desde solicitudes en lenguaje natural. El protocolo estandariza cómo se conectan las herramientas de IA a servicios externos, evitando el bloqueo por proveedor. Consulta Decision Frameworks para obtener orientación sobre cuándo usar MCP frente a otros mecanismos de extensión.

Soporte de MCP remoto (junio de 2025)

Claude Code ahora admite servidores MCP remotos con autenticación OAuth nativa.²⁸ Conéctate a herramientas y fuentes de datos sin gestionar servidores locales. Solo autentícate una vez y Claude Code se encarga automáticamente de actualizar el token.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

SDK mcp_authenticate redirectUri (v2.1.121+): El mcp_authenticate del Agent SDK acepta un parámetro redirectUri para completar OAuth en esquemas URI personalizados — necesario para apps de escritorio y flujos de conector de claude.ai que no pueden usar la redirección loopback predeterminada.¹⁶¹

Conectores MCP de claude.ai (v2.1.46+)

Claude Code ahora puede usar conectores MCP configurados en tu cuenta de claude.ai. Esto cierra la brecha entre la web y CLI: los servidores MCP que has configurado mediante la interfaz de claude.ai están disponibles automáticamente en Claude Code sin necesidad de reconfigurarlos localmente.¹⁰²

Desactivar: Establece ENABLE_CLAUDEAI_MCP_SERVERS=false en tu entorno o en el bloque env de settings.json para evitar que se carguen los servidores MCP de claude.ai.¹¹¹

MCP Tool Search (v2.1.7+)

A medida que los servidores MCP ganaban capacidad (algunos exponiendo más de 50 herramientas), las descripciones de herramientas comenzaron a consumir un contexto excesivo. MCP Tool Search resuelve esto cargando dinámicamente las descripciones de herramientas solo cuando se necesitan, una forma de carga diferida para herramientas de IA.⁵⁴

Impacto en el rendimiento: Las pruebas internas muestran mejoras drásticas en la precisión: - Opus 4: 49% → 74% en evaluaciones de MCP - Opus 4.5: 79,5% → 88,1% en evaluaciones de MCP - Reducción de la sobrecarga de tokens: 85%

Cómo funciona: Cuando las descripciones de herramientas MCP superan el 10% de la ventana de contexto (umbral predeterminado), Claude Code pospone la carga de descripciones completas hasta que realmente se necesitan. Claude ve los nombres de las herramientas, pero obtiene las descripciones bajo demanda.

Configuración:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

Valores: - true - Activar siempre la búsqueda de herramientas - false - Desactivar siempre (cargar todas las descripciones de herramientas por adelantado) - auto:N - Activar cuando las herramientas superen el N% del contexto (0-100)

Consejo de experto: Con Tool Search activado, puedes conectarte a muchos más servidores MCP sin preocuparte por los límites de contexto. La reducción del 95% del contexto significa que los servidores que antes competían por el contexto ahora coexisten en armonía.

Anulación de carga permanente de MCP (v2.1.121+)

Tool Search pospone la carga de descripciones completas hasta que se necesita una herramienta (umbral: mcpToolSearchAutoEnable, predeterminado auto:10). Para servidores de confianza cuyas herramientas esperas usar en cada turno, desactiva esta opción por servidor con alwaysLoad: true — todas las herramientas de ese servidor se cargan en el prompt al inicio de la sesión, sin viaje de ida y vuelta de ToolSearch:¹⁶¹

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

Reintento automático de inicio de MCP (v2.1.121+): Un servidor que produce errores durante el inicio ahora se reintenta hasta 3 veces antes de marcarse como desconectado — útil para servidores stdio que compiten con un proceso padre lento o servidores HTTP detrás de un backend con arranque en frío.¹⁶¹

Solicitud de información de MCP (v2.1.76+)

Los servidores MCP ahora pueden solicitar entradas estructuradas al usuario en mitad de una tarea mediante diálogos interactivos.¹²⁵ Cuando un servidor MCP necesita información adicional (por ejemplo, seleccionar una rama, introducir un nombre de proyecto, confirmar una acción), envía una solicitud de elicitación que Claude Code representa como campos de formulario o una URL de navegador.

Integración con hooks: Dos nuevos eventos de hook — Elicitation (antes de que aparezca el diálogo) y ElicitationResult (después de que el usuario responda) — te permiten interceptar, validar o anular las respuestas de elicitación de forma programática. Esto habilita flujos de trabajo empresariales en los que los prompts del servidor MCP se rellenan previamente o se restringen según una política.

Anulación del tamaño de los resultados de MCP (v2.1.91+)

Los resultados de las herramientas MCP se truncan de forma predeterminada. Los servidores pueden anular esto por resultado utilizando la anotación _meta["anthropic/maxResultSizeChars"], lo que permite hasta 500.000 caracteres.¹⁴³ Esto resulta útil para devolver cargas útiles grandes, como esquemas de bases de datos, respuestas de API o contenidos de archivos sin truncamiento.

Asistente interactivo de configuración de MCP

Ejecuta claude mcp add sin argumentos para abrir una interfaz paso a paso para añadir servidores MCP. El asistente te guía a través de la selección del tipo de transporte, la autenticación y la configuración.¹⁵

Tipos de transporte

HTTP (recomendado para servidores remotos):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (obsoleto pero funcional):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (servidores locales):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

Windows requiere un wrapper de cmd para stdio:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Gestión de ámbitos

Los servidores MCP existen en tres ámbitos con una precedencia clara (local anula proyecto, que anula usuario):

Especifica el ámbito durante la instalación:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

Formato del archivo de configuración

El archivo .mcp.json define los servidores a nivel de proyecto:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

Las variables de entorno se expanden usando la sintaxis ${VAR} con valores predeterminados opcionales: ${VAR:-default}.

Comandos de gestión de MCP

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

Autenticación OAuth

Para servidores que requieren OAuth:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

Uso de recursos y prompts de MCP

Recursos de referencia:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

Prompts de MCP como slash commands:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Límites de salida

Claude Code limita la salida de MCP para evitar el desbordamiento del contexto: - Umbral de advertencia: 10.000 tokens - Máximo predeterminado: 25.000 tokens

Auméntalo si es necesario:

export MAX_MCP_OUTPUT_TOKENS=50000

Servidores MCP populares

Patrones prácticos de MCP

Flujo de trabajo de GitHub:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

Consultas a base de datos:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

Monitoreo de errores:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?

Configuración empresarial de MCP

Los administradores de sistemas pueden aplicar políticas de MCP mediante managed-mcp.json: