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

TL;DR: Claude Code es una CLI agéntica que lee tu base de código, ejecuta comandos y modifica archivos mediante un sistema por capas de permisos, hooks, integraciones de MCP y subagents. Domina cinco sistemas fundamentales (configuración, permisos, hooks, MCP y subagents) y multiplicarás tu productividad. Elige el nivel de modelo adecuado para cada tarea —Opus para razonamiento complejo, Sonnet para trabajo general y Haiku para exploración rápida— o estandariza el uso de Opus si la calidad es tu única variable. Usa hooks (no prompts) para todo lo que deba ejecutarse siempre. Desde la v2.1.197 (30 de junio de 2026), Claude Sonnet 5 es el modelo predeterminado de Claude Code —contexto nativo de 1M y precio promocional de $2/$10 hasta el 31 de agosto—, mientras que puedes acceder a Opus con /model opus (desde la v2.1.219, ese alias selecciona Claude Opus 5); la v2.1.198 (1 de julio) hace que los subagents se ejecuten en segundo plano de forma predeterminada, lleva Claude en Chrome a disponibilidad general, permite que los agentes en segundo plano hagan commit, push y abran un borrador de PR al terminar el código de un worktree, y activa el hook Notification (agent_needs_input/agent_completed) para las sesiones en segundo plano; la v2.1.199 (2 de julio) carga hasta 5 invocaciones apiladas de slash-skills y reintenta automáticamente los errores 429 transitorios para suscriptores; la v2.1.200 (3 de julio) cambia el nombre del modo de permisos default a «Manual» en toda la CLI, --help, VS Code y JetBrains (el valor de configuración no cambia y se acepta manual como alias), además de impedir que los cuadros de diálogo de AskUserQuestion continúen automáticamente de forma predeterminada; la v2.1.202 (6 de julio) añade un control «Dynamic workflow size» a /config y devuelve /review <pr> a una revisión rápida de una sola pasada, mientras que el proceso multiagente pasa a /code-review <level> <pr#>; las v2.1.203–205 (del 7 al 9 de julio) refuerzan el modo automático —se bloquea la manipulación de los archivos de transcripción, rm -rf solicita confirmación cuando usa una variable que no puede resolverse y las notificaciones de tareas en segundo plano indican que no hubo intervención humana (para impedir que se actúe sobre aprobaciones inventadas dentro de la transcripción)—, además de convertir /doctor en una revisión completa de diagnóstico y corrección (con el alias /checkup).^181182183 La v2.1.217 (21 de julio) revirtió el comportamiento de los subagents anidados: los subagents dejaron de generar sus propios subagents de forma predeterminada (una decisión que la v2.1.219 volvió a revertir otra vez tres días después, con una profundidad de 3; consulta más abajo), se ejecutan como máximo 20 subagents simultáneamente de forma predeterminada (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) y --max-budget-usd ahora sí detiene los subagents en segundo plano cuando se alcanza el límite.¹⁹⁴ La v2.1.218 (22 de julio) traslada /code-review a un subagent en segundo plano —el trabajo de revisión ya no ocupa tu conversación—, ejecuta de forma predeterminada en segundo plano los skills con context: fork (puedes desactivarlo en cada skill con background: false), hace que /deep-research solo se inicie mediante una invocación explícita, delega las comprobaciones de rm peligroso, & en segundo plano y rutas sospechosas de Windows al clasificador del modo automático en lugar de los cuadros de diálogo de permisos, e impide que los hooks del frontmatter de los agentes se ejecuten desde carpetas no confiables.¹⁹⁵ La v2.1.219 (24 de julio) convierte a Claude Opus 5 (claude-opus-5) en el modelo Opus predeterminado —contexto de 1M, salida máxima de 128K, $5/$25 por MTok (igual que Opus 4.8), pensamiento activado de forma predeterminada, effort establecido en high de forma predeterminada y conocimiento hasta mayo de 2026—, además de corregir dos comportamientos introducidos por versiones anteriores: el modo rápido ahora se aplica a Opus 5 y Opus 4.8 por $10/$50 por MTok (2 veces la tarifa base, mientras que Opus 4.7 se elimina por completo del modo rápido) y los subagents anidados vuelven a estar activados de forma predeterminada, con una profundidad de 3 (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 desactiva el anidamiento). La misma versión añade el evento de hook DirectoryAdded, la configuración sandbox.network.strictAllowlist, una clave de configuración workflowSizeGuideline —los flujos de trabajo dinámicos adoptan ahora de forma predeterminada una directriz de tamaño mediano (procura usar menos de 15 agentes)— y el reenvío de subagents anidados en stream-json. La v2.1.220 (25 de julio) solo incluye correcciones de errores y mejoras de confiabilidad.^196197198 Desde las v2.1.174–176 (12 de junio de 2026), la lista de permitidos availableModels puede restringir ahora el modelo Default mediante la nueva configuración administrada enforceAvailableModels (la configuración del usuario o del proyecto no puede ampliar una lista administrada), los títulos de las sesiones se generan en el idioma de tu conversación (puedes fijarlo con la configuración language) y completan la versión las nuevas opciones footerLinksRegexes y wheelScrollAccelerationEnabled, un cuadro de diálogo de atribución de /usage en VSCode y una corrección que permite que las condiciones if de los hooks coincidan con patrones de rutas de Read/Edit/Write.¹⁷² Desde la v2.1.173 (11 de junio de 2026), el sufijo [1m] del nombre de un modelo Fable 5 se normaliza y elimina automáticamente: Fable 5 ya incluye un contexto de 1M de forma predeterminada, por lo que el sufijo es innecesario (solo tuvo sentido para Opus/Sonnet). Desde la v2.1.172 (10 de junio de 2026), los sub-agents podían generar recursivamente sus propios sub-agents hasta una profundidad de 5 niveles —un comportamiento predeterminado que se mantuvo hasta la v2.1.216 y se desactivó en la v2.1.217 (consulta más arriba)—, Bedrock lee su región desde ~/.aws cuando AWS_REGION no está definido (/status muestra el origen), /plugin añade una barra de búsqueda de marketplaces y la métrica OTEL claude_code.lines_of_code.count incorpora un atributo model. Desde la v2.1.170 (9 de junio de 2026), Claude Fable 5 —un nuevo nivel de modelo superior a Opus— puede seleccionarse en Claude Code mediante /model fable después de ejecutar claude update (admite toda la escala de esfuerzo, de low a max, pero no permite desactivar el pensamiento); Opus 4.8 sigue siendo el modelo agéntico predeterminado. Desde la v2.1.169 (8 de junio de 2026), --safe-mode (y CLAUDE_CODE_SAFE_MODE) inicia una sesión limpia con todas las personalizaciones desactivadas para facilitar la resolución de problemas, /cd traslada una sesión a un nuevo directorio de trabajo sin romper la caché de prompts y disableBundledSkills oculta al modelo los skills y slash commands integrados. Desde la v2.1.166 (6 de junio de 2026), una configuración fallbackModel encadena hasta tres modelos de respaldo cuando el principal está sobrecargado, el glob "*" funciona en las reglas de denegación de MCP, y MAX_THINKING_TOKENS=0 / --thinking disabled desactivan por completo el pensamiento en los modelos que lo activan de forma predeterminada. Desde la v2.1.154 (28 de mayo de 2026), Opus 4.8 es el nuevo modelo predeterminado, con esfuerzo alto por defecto y un nivel /effort xhigh, los flujos de trabajo dinámicos coordinan decenas o cientos de agentes en segundo plano mediante /workflows, el modo rápido de Opus 4.8 cuesta 2 veces la tarifa estándar y ofrece 2,5 veces más velocidad, el prompt de sistema reducido es ahora el predeterminado para todos los modelos excepto Haiku/Sonnet/Opus 4.7 y anteriores, /simplify volvió a ser una revisión dedicada únicamente a la limpieza (separada de /code-review --fix), claude agents acepta ! <command> para generar sesiones de shell en segundo plano, los plugins pueden declarar defaultEnabled: false, la ejecución de herramientas en streaming siempre está activada y los servidores MCP stdio reciben CLAUDE_CODE_SESSION_ID junto con CLAUDECODE=1 en sus variables de entorno. La v2.1.153 añadió skipLfs a los marketplaces de plugins, hizo que /model se guardara como opción predeterminada (presiona s para aplicarlo solo a la sesión) e incorporó COLUMNS/LINES al entorno de la línea de estado. La v2.1.152 introdujo /code-review --fix (aplica los hallazgos al árbol de trabajo), disallowed-tools en el frontmatter de los skills, /reload-skills, el nuevo evento de hook MessageDisplay, las salidas reloadSkills/sessionTitle del hook SessionStart, la configuración administrada pluginSuggestionMarketplaces, el cambio de --fallback-model durante una sesión y la eliminación de la activación voluntaria del modo automático.^{162 163 164 165 166 167 168 169 170 210 171}

Claude Code funciona como un sistema agéntico, no como una interfaz de chat con conocimientos de programación. La CLI lee tu base de código, ejecuta comandos, modifica archivos, administra flujos de trabajo de git, se conecta con servicios externos mediante MCP y delega tareas complejas a subagents especializados. Todo se realiza mediante una interfaz de línea de comandos integrada en la forma en que los desarrolladores trabajan realmente. En febrero de 2026, el 4 % de los commits públicos de GitHub (alrededor de 135.000 al día) eran obra de Claude Code, lo que supone un crecimiento de 42.896 veces en los 13 meses transcurridos desde la versión preliminar de investigación; además, el 90 % del código de Anthropic está escrito por IA.¹⁰³

La diferencia entre un uso ocasional y uno eficaz de Claude Code se reduce a cinco sistemas fundamentales. Domínalos y Claude Code se convertirá en un multiplicador de fuerza:

1. Jerarquía de configuración: controla el comportamiento
2. Sistema de permisos: restringe las operaciones
3. Sistema de hooks: permite una automatización determinista
4. Protocolo MCP: amplía las capacidades
5. Sistema de subagents: se encarga de tareas complejas de varios pasos

Puntos clave

• Cinco sistemas determinan tu eficacia: la jerarquía de configuración, los permisos, los hooks, MCP y los subagents controlan todo, desde el comportamiento hasta la automatización.
• Traslada trabajo a la capa de delegación: los subagents evitan que el contexto se sature al aislar la exploración en ventanas de contexto limpias y devolver únicamente resúmenes.
• Los hooks garantizan la ejecución; los prompts no: usa hooks para el linting, el formateo y las comprobaciones de seguridad que deban ejecutarse siempre, independientemente del comportamiento del modelo.
• La selección del nivel de modelo reduce costos sin sacrificar calidad: dirige la exploración de los subagents hacia modelos más económicos y reserva Opus para el razonamiento arquitectónico que realmente lo requiera, o estandariza el uso de Opus si la calidad es tu única variable.
• MCP conecta Claude con tu cadena de herramientas: las bases de datos, GitHub, Sentry y más de 3.000 integraciones amplían las capacidades de 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 de producción, pipelines de CI/CD e implementaciones empresariales. Esta guía condensa esa experiencia en la referencia completa que me habría gustado tener cuando comencé. Cada función incluye la sintaxis real, ejemplos auténticos de configuración y los casos límite que causan problemas incluso a usuarios experimentados.

Elige tu ruta

Cómo usar esta guía

Esta referencia tiene más de 5.000 líneas; no necesitas leerla de principio a fin. Comienza por la sección adecuada para tu nivel de experiencia:

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

Análisis detallados relacionados

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

Inicio rápido en 60 segundos

Si solo quieres ejecutar Claude Code y ver el resultado, sigue estos pasos 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. El resto de esta guía amplía las opciones de instalación, explica cómo configurar permisos y hooks, conectar servidores MCP y realizar implementaciones empresariales, pero nada de ello es necesario para comenzar.

Requisitos previos: Node 22+ solo para el método heredado mediante npm (se aumentó desde la versión 18 con v2.1.198; la documentación de instalación vigente indica «Node.js 22 o posterior», verificado el 7 de agosto de 2026); el instalador nativo recomendado no depende de Node. Se admiten macOS / Linux / Windows 10+. El uso está cubierto por una suscripción Claude Pro, Max, Team o Enterprise, o por una clave API de Anthropic con pago por token. Consulta ¿Cómo instalo Claude Code? para conocer los detalles específicos de cada plataforma, solucionar problemas y usar el binario nativo (la opción predeterminada desde v2.1.113). La evidencia sobre la versión más reciente incluida en esta guía se verificó con v2.1.154.²¹⁰

Cómo funciona Claude Code: el modelo mental

Antes de profundizar en sus funciones, conviene entender cómo la arquitectura de Claude Code determina todo lo que haces con él. El sistema funciona 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 central: Tu conversación principal. Cada mensaje, archivo leído y resultado de una herramienta consume espacio de una ventana de contexto compartida (200K tokens de manera estándar⁹¹ y 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 disminuye. Esta capa tiene un costo por token.

Capa de delegación: Los subagents se inician con contextos limpios, realizan tareas específicas y devuelven resúmenes. Los resultados de la exploración no saturan la conversación principal; solo regresan las conclusiones. Asigna los subagents a modelos de niveles más económicos para explorar, 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. Las skills codifican conocimientos especializados que Claude aplica automáticamente. Los plugins agrupan todo esto para distribuirlo.

La idea clave: La mayoría de los usuarios trabaja exclusivamente en la capa central y ve cómo aumentan el contexto y los costos. Los usuarios avanzados trasladan la exploración y el trabajo especializado a la capa de delegación, mantienen la capa de extensión configurada según su flujo de trabajo y reservan la capa central únicamente para la orquestación y las decisiones finales.

Tabla de contenido

1. ¿Cómo instalo Claude Code?
2. Inicio rápido: tu primera sesión
3. Modos principales de interacción
4. Análisis detallado del sistema de configuración
5. ¿Qué modelo debería elegir?
6. ¿Cuánto cuesta Claude Code?
7. Marcos para la toma de decisiones
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 razonamiento extendido?
13. Estilos de salida
14. Comandos slash
15. ¿Cómo funcionan las skills?
16. Sistema de plugins
17. ¿Cómo funciona la memoria?
18. Imágenes y entrada 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 avanzado
23. Agentes remotos y en segundo plano [AVANCE DE INVESTIGACIÓN]
24. Claude en Chrome
25. Claude Code en Slack [AVANCE DE INVESTIGACIÓN]
26. Claude Code en la web [AVANCE DE INVESTIGACIÓN]
27. Optimización del rendimiento
28. ¿Cómo diagnostico problemas?
29. Implementación empresarial
30. Referencia de atajos de teclado
31. Prácticas recomendadas
32. Recetas para flujos de trabajo
33. Guía de migración
34. Orientación para públicos específicos
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. Ve 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 de teclado durante la 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. Retoma la sesión más adelante:

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 los comandos de compilación, las convenciones de código y las notas de arquitectura. Claude lo lee en cada sesión; es lo que más puede mejorar la calidad con el menor esfuerzo.

Modos de interacción principales

REPL interactivo

Inicia Claude Code sin argumentos para entrar en el bucle interactivo de lectura, evaluación e impresión:

cd your-project
claude

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

Comienza con una instrucción 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 partes anteriores de la conversación, a la vez que preserva las decisiones clave y los fragmentos de código. Puedes activar este proceso manualmente con /compact o agregar instrucciones personalizadas sobre qué debe conservarse.

Modo no interactivo

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

# 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 obtener una salida estructurada que pueda analizarse mediante scripts:

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

La salida de JSON incluye todo lo necesario para la 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 procesar en tiempo real la salida transmitida:

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:

Texto de subagents en stream-json (v2.1.211+): De forma predeterminada, la salida de stream-json solo contiene los eventos de la sesión principal; el trabajo realizado dentro de subagents aparece como un resumen. El indicador --forward-subagent-text (o CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1) también reenvía al flujo el texto y el razonamiento de los subagents, de modo que los sistemas de ejecución y las canalizaciones de registros puedan observar el trabajo delegado mientras sucede, en lugar de ver únicamente el informe final.¹⁸⁸

Ahora también se reenvían los subagents anidados (v2.1.219). Originalmente, solo aparecían los subagents de profundidad 1. Ahora los subagents generados en la profundidad 2 y posteriores también aparecen en el flujo reenviado, cada uno identificado mediante el id tool_use de la llamada a Agent que lo generó. De esta manera, una canalización puede reconstruir el árbol de delegación en vez de ver una lista plana de texto. Esto se complementa directamente con la restauración, en la misma versión, de la generación anidada hasta la profundidad 3 de forma predeterminada: sin ella, 2 de los 3 niveles habrían sido invisibles.¹⁹⁶

Códigos de salida:

Control del comportamiento autónomo en el 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 con 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'

Administración de sesiones

Las sesiones conservan el historial de conversaciones para poder continuarlas. La persistencia de las sesiones 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 solicitud de incorporación o fusión específica. Desde la versión v2.1.119, --from-pr acepta URL 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 con los PR cuando los creas mediante gh pr create durante una sesión. Esto facilita retomar más adelante el trabajo en un PR específico. La insignia del PR en el pie de página puede dirigir a una URL personalizada de revisión de código mediante la configuración prUrlTemplate (v2.1.119+), lo que resulta útil cuando tu equipo enlaza los PR con una herramienta de revisión independiente.¹⁵²

/resume acepta URL de PR (v2.1.122+). Al pegar la URL de un PR en el cuadro de búsqueda de /resume, ahora se encuentra la sesión que creó originalmente ese PR. Funciona con github.com, GitHub Enterprise, gitlab.com (incluidas las instalaciones autohospedadas de GitLab) y bitbucket.org.¹⁵⁴

Sesiones con nombre: Asigna nombres 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 asignar nombres legibles a las sesiones, usa /rename y --resume.

/fork genera una sesión en segundo plano; /subtask es la bifurcación dentro de la sesión (v2.1.212). El comando /fork ahora copia la conversación actual en una nueva sesión en segundo plano. Esta obtiene su propia fila en claude agents, por lo que puedes enviar la copia a explorar una alternativa mientras continúa la sesión principal. El comportamiento anterior, que bifurcaba dentro de la sesión actual, se conserva con el nuevo nombre /subtask.¹⁸⁹ Desde la versión v2.1.214, una sesión que comienza como bifurcación informa "fork" como origen del hook SessionStart (antes informaba "resume"), de modo que los hooks que comparan el origen pueden distinguir ambos casos.¹⁹⁰ La versión v2.1.216 reduce la confirmación de /fork a una sola línea que muestra el nombre de la nueva sesión y su id de claude attach.¹⁹² Desde la v2.1.221, una sesión bifurcada crea su propio worktree en lugar de trabajar en el checkout de la sesión original. Así, la bifurcación que explora una alternativa ya no puede entrar en conflicto con los archivos sin confirmar de la sesión principal, que era el principal riesgo de enviar una copia a experimentar.¹⁹⁹

Claude Code almacena las sesiones como transcripciones JSONL. La ejecución de agentes asigna valores agentId únicos y almacena las transcripciones como agent-{agentId}.jsonl. Al reanudar una sesión, se conserva todo el contexto de las conversaciones anteriores.

Modo de planificación

El modo de planificación restringe Claude a la exploración de solo lectura: no permite editar archivos, ejecutar Bash ni realizar 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 cualquier acción.

Cómo entrar en el 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 en el modo de planificación (automáticamente para tareas complejas o mediante Shift+Tab)
2. Explora el código fuente con 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 mediante ExitPlanMode y presenta el plan para que lo revises
5. Apruebas, solicitas cambios o rechazas el plan

Herramientas disponibles en el 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í, borrar el contexto y aceptar automáticamente las ediciones» (Shift+Tab): comienza desde cero con todo el contexto disponible para el plan - «Sí, y aprobar manualmente las ediciones»: conserva el contexto y tú apruebas cada cambio - «Sí, aceptar automáticamente las ediciones»: conserva el contexto y Claude ejecuta el plan sin solicitar aprobación para cada edición

Borrar automáticamente el contexto al aprobar es el flujo de trabajo recomendado. Le proporciona al plan una nueva ventana de contexto, lo que mejora considerablemente su cumplimiento: Claude mantiene el rumbo durante más tiempo sin que interfiera la conversación anterior.

Cuándo usar el modo de planificación: - Implementaciones de funciones nuevas que requieren decisiones arquitectónicas - Refactorizaciones de varios archivos en las que quieres revisar primero el enfoque - Bases de código desconocidas en las que la exploración debe preceder a las modificaciones - Cualquier tarea con varios enfoques válidos sobre los que quieras aportar tu opinión

Consejo experto: Cuanto más tiempo dediques al modo de planificación, mayores serán las probabilidades de que Claude implemente correctamente el plan. Este modo ofrece una exploración prácticamente gratuita: no hay llamadas arriesgadas a herramientas ni ediciones desperdiciadas. Úsalo con libertad.

Modo de lector de pantalla (v2.1.208)

Claude Code incluye un modo específico de lector de pantalla que adapta la interfaz de la terminal para las tecnologías de asistencia. Actívalo de cualquiera de estas tres maneras:¹⁸⁶

# Flag at launch
claude --ax-screen-reader

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

# Or persistently in settings.json
{ "axScreenReader": true }

Anthropic documenta el modo y sus patrones de interacción en una nueva página de accesibilidad de la documentación oficial.¹⁸⁶

Análisis detallado del sistema de configuración

Claude Code utiliza un sistema de configuración por capas. Comprender la jerarquía es fundamental porque los niveles superiores prevalecen sobre los inferiores y la configuración empresarial no se puede eludir bajo ninguna circunstancia.

Jerarquía de configuración

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

Configurar desde el prompt: /config key=value (v2.1.181)

A partir de la versión v2.1.181, /config key=value permite establecer cualquier opción directamente desde el prompt —por ejemplo, /config thinking=false— sin abrir la interfaz interactiva de /config, y funciona en sesiones interactivas, con -p y de Remote Control. /config --help (v2.1.183) muestra las claves abreviadas disponibles. La versión v2.1.183 también modificó la interfaz interactiva de /config: ahora, tanto Enter como Space alternan la opción seleccionada, mientras que Esc guarda y cierra (antes revertía los cambios).¹⁷⁴

Referencia completa de settings.json

Una configuración completa que muestra 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/**)",
      "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
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "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
  }
}

skillOverrides resulta útil cuando un equipo tiene una gran biblioteca de skills, pero quiere controlar con mayor precisión cuáles están disponibles durante la ejecución. Usa off para ocultar una skill tanto del modelo como del selector de comandos slash, user-invocable-only para permitir que se siga invocando por nombre, pero eliminarla de la selección del modelo, y name-only para mostrar únicamente el nombre de la skill sin su descripción completa.¹⁵⁶

Configuraciones más recientes (v2.1.174–176):

• availableModels / enforceAvailableModels (administrada, v2.1.175+): la lista de permitidos availableModels restringe los modelos que puede seleccionar una sesión. Con enforceAvailableModels: true, la lista también limita el modelo Default: si un modelo Default se resolviera como uno no permitido, se utiliza el primer modelo autorizado, y la configuración del usuario o del proyecto ya no puede ampliar una lista availableModels administrada. Una corrección complementaria (v2.1.176) elimina la brecha por la que la elección de un alias podía redirigir a un modelo bloqueado mediante ANTHROPIC_DEFAULT_*_MODEL; además, /fast ahora se niega a cambiar a un modelo que no figure en la lista de permitidos.¹⁷² A partir de la versión v2.1.187, las organizaciones pueden aplicar restricciones de modelos directamente en el selector de /model, --model, /model y ANTHROPIC_MODEL; al seleccionar un modelo restringido, se muestra el mensaje “restringido por la configuración de tu organización”.¹⁷⁶
• language (mejora de v2.1.176): además de definir el idioma de respuesta, ahora los títulos de las sesiones se generan de forma predeterminada en el idioma de tu conversación; establece language para fijar un idioma específico para los títulos.¹⁷²
• footerLinksRegexes (v2.1.176): insignias de enlaces que coinciden con expresiones regulares en la fila del pie de página, configurables mediante la configuración del usuario o la administrada.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): establece false para desactivar la aceleración del desplazamiento con la rueda del mouse en el modo de pantalla completa.¹⁷²

Configuraciones más recientes (v2.1.207–v2.1.212):

• vimInsertModeRemaps (v2.1.208): reasignaciones de teclas personalizadas para el modo de inserción de vim; el ejemplo clásico consiste en asignar jj a Escape (consulta Modo Vim).¹⁸⁶
• axScreenReader (v2.1.208): habilita el modo de lector de pantalla de forma persistente (consulta Modo de lector de pantalla).¹⁸⁶
• processWrapper (v2.1.208): dirige cada proceso que Claude Code inicia para sí mismo a través de un ejecutable contenedor; está diseñado para iniciadores corporativos (consulta Iniciador corporativo).¹⁸⁶
• Restricción del origen de autoMode (v2.1.207): la configuración autoMode ya no se lee desde el archivo .claude/settings.local.json de un repositorio; configúrala en ~/.claude/settings.json. Esto elimina una vía por la que un repositorio clonado podía incluir una configuración del modo automático.¹⁸⁵

Configuraciones más recientes (v2.1.217):

• emojiCompletionEnabled (v2.1.217): autocompletado de códigos abreviados de emojis en la entrada del prompt; escribe :heart: para insertar ❤️ o una parte, como :hea, para recibir sugerencias. Está activado de forma predeterminada; establece false para desactivarlo.¹⁹⁴

Configuraciones más recientes (v2.1.219):

• sandbox.network.strictAllowlist (v2.1.219): rechaza los hosts que no figuren en la lista de permitidos para los comandos ejecutados en el sandbox sin solicitar confirmación, en lugar de mostrar un cuadro de diálogo de permisos. Consulta Modo sandbox.¹⁹⁶
• workflowSizeGuideline (v2.1.219): establece la recomendación orientativa de tamaño para flujos de trabajo Dynamic desde cualquier archivo de configuración —del usuario, del proyecto o administrado— y no solo mediante /config. Los flujos de trabajo Dynamic utilizan de forma predeterminada una recomendación medium (“procura usar menos de 15 agentes”); la fila de /config se oculta cuando un archivo de configuración proporciona el valor. Es una recomendación, no un límite obligatorio. Consulta Subagents.¹⁹⁶

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 del 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
CLAUDE_CODE_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
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 del proveedor de servicios 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
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]

Control del 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]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
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]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+)[^206]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

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
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
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

Interfaz de usuario 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               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope)[^103][^217]
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # Let unrecognized model IDs exceed the assumed context window (v2.1.223)[^217]
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_DISABLE_MOUSE_CLICKS=1           # Disable mouse click/drag/hover in fullscreen mode; wheel scroll still works (v2.1.195+)[^196]
CLAUDE_ENABLE_STREAM_WATCHDOG=0              # Disable the streaming idle watchdog (on by default for all providers since v2.1.196: aborts+retries after 5 min of silence)[^198]
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 # Turn off automatic memory-pressure reaping of idle background shell commands (v2.1.193+)[^196]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
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 y control de campos confidenciales:²¹¹

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)
OTEL_LOG_ASSISTANT_RESPONSES=0                # Gate the claude_code.assistant_response log event holding the model's response text (v2.1.193+)
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH=60000     # Truncation limit for OTel content attributes (default 60 KB; v2.1.214+)[^207]
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 spans de solicitudes de LLM en v2.1.121+: ahora se emiten stop_reason, gen_ai.response.finish_reasons y user_system_prompt en los spans de solicitudes de LLM. user_system_prompt está condicionado a OTEL_LOG_USER_PROMPTS=1, ya que puede contener información de identificación personal.¹⁵⁴

Cambios en los eventos en v2.1.122+: los atributos numéricos de los eventos de registro api_request y api_error ahora se emiten como números (antes eran cadenas), lo que corrige los recopiladores OTel posteriores que aplicaban tipos estrictos al esquema. El nuevo evento de registro claude_code.at_mention se activa cuando Claude Code resuelve una mención con @.¹⁵⁴

Evento de registro claude_code.assistant_response en v2.1.193+: Claude Code puede emitir el texto completo de la respuesta del modelo como un evento de registro OTel, sujeto a OTEL_LOG_ASSISTANT_RESPONSES. Este control tiene una particularidad importante al actualizar: cuando OTEL_LOG_ASSISTANT_RESPONSES no está definido, sigue el valor de OTEL_LOG_USER_PROMPTS, por lo que cualquier implementación que ya registre el contenido de los prompts comenzará a recibir también el contenido de las respuestas del asistente después de actualizarse. Establece OTEL_LOG_ASSISTANT_RESPONSES=0 para que la telemetría continúe registrando únicamente los prompts.¹⁷⁹

Incorporaciones de telemetría en v2.1.214: los eventos de registro OTel ahora incluyen los atributos message.uuid, client_request_id y tool_source para correlacionar mensajes e identificar la procedencia de las herramientas; la carga útil de subagentStatusLine incluye el nivel de esfuerzo de razonamiento del subagent, por lo que las filas personalizadas de la línea de estado pueden mostrar juntos el modelo y el esfuerzo; además, la nueva variable de entorno CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH configura el límite de truncamiento de 60 KB para los atributos de contenido OTel.¹⁹⁰

API / Control del 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+)

Entorno empresarial / 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)
CLAUDE_CODE_PROCESS_WRAPPER=/path/to/wrapper  # Route all Claude Code self-spawned processes through a wrapper executable; same as the processWrapper setting (v2.1.208+)[^203]

Variables de skills (v2.1.69+):

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

Identidad del invocador de SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=user@example.com        # 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 debo elegir?

Elegir el modelo adecuado para cada tarea influye considerablemente tanto en el costo como en la calidad. Claude Code permite cambiar de modelo con flexibilidad en varios niveles.

Modelos disponibles

Dos cambios incompatibles al migrar un entorno de Opus 4.8 a Opus 5:¹⁹⁷

1. El pensamiento está activado de forma predeterminada. En Opus 4.8, una solicitud sin el campo thinking se ejecutaba sin pensamiento; en Opus 5, esa misma solicitud se ejecuta con pensamiento adaptativo. max_tokens sigue siendo un límite estricto para la salida total —el pensamiento más el texto de la respuesta—, así que vuelve a comprobar el margen de cualquier carga de trabajo que antes se ejecutara sin pensamiento. Pasa thinking: {type: "disabled"} para recuperar el comportamiento anterior, con la salvedad del siguiente punto.
2. Al desactivar el pensamiento, el esfuerzo queda limitado a high. Combinar thinking: {type: "disabled"} con el esfuerzo xhigh o max devuelve un 400. La comprobación se aplica en cada solicitud: aumentar el esfuerzo a xhigh mientras el pensamiento está desactivado se rechaza, aunque se hayan aceptado turnos anteriores de la misma conversación.

En Claude Code específicamente, effort tiene como valor predeterminado high en Opus 5 (al igual que en la API de Claude) y está disponible toda la escala: low, medium, high, xhigh, max. La propia guía de migración de Anthropic recomienda probar el esfuerzo max cuando la capacidad importe más que el consumo de tokens. El modo rápido incluye Opus 5 a $10/$50 por MTok (consulta Modo rápido).¹⁹⁷¹⁹⁸

Claude Fable 5 (9 de junio de 2026): Un nuevo nivel de modelo superior a Opus: el modelo más potente e inteligente de Anthropic, con tecnología de vanguardia en casi todas las pruebas comparativas en las que se ha evaluado y diseñado para mantener la coherencia a lo largo de millones de tokens de contexto. Fable 5 es el modelo de frontera de «clase Mythos» adaptado para un uso general seguro: incluye clasificadores de seguridad que recurren a Opus 4.8 ante consultas sobre ciberseguridad, biología y química, y destilación de modelos (Claude Mythos 5 es el mismo modelo sin esas salvaguardas para investigadores autorizados). Se pudo seleccionar en Claude Code a partir de la v2.1.170 (9 de junio de 2026): ejecuta claude update y luego /model fable (el alias corto; /model claude-fable-5 y el alias best también lo seleccionan). Su disponibilidad se extenderá gradualmente a los planes de suscripción hasta el 22 de junio de 2026. ID del modelo: claude-fable-5. Fable 5 incluye una ventana de contexto de 1M de forma predeterminada, por lo que el sufijo [1m] es innecesario; además, desde la v2.1.173 (11 de junio de 2026), el nombre de modelo claude-fable-5[1m] se normaliza automáticamente a claude-fable-5 eliminando el sufijo (este solo tuvo sentido para Opus/Sonnet, donde el acceso a 1M depende de [1m]). Su salida máxima es de 128K. El precio es de $10/MTok de entrada y $50/MTok de salida —aproximadamente el doble que Opus 4.8—, así que resérvalo para problemas de razonamiento realmente difíciles, no para ediciones rutinarias. Comparte la interfaz de solicitudes de Opus 4.8 (solo pensamiento adaptativo; se eliminaron temperature/top_p/top_k y budget_tokens), con una diferencia nueva: usar explícitamente thinking: {type: "disabled"} devuelve un 400, por lo que debes omitir por completo el parámetro thinking para ejecutar el modelo sin pensamiento.²⁰⁴

En Claude Code específicamente, Fable 5 admite toda la escala de esfuerzo (low/medium/high/xhigh/max, con high como valor predeterminado), al igual que Opus 5. El pensamiento no se puede desactivar en Fable 5: ni el control de pensamiento de la sesión, ni la configuración alwaysThinkingEnabled, ni MAX_THINKING_TOKENS=0 tienen efecto; siempre razona de forma adaptativa. Una interfaz de configuración completa para la familia fable reproduce las opciones de Opus: ANTHROPIC_DEFAULT_FABLE_MODEL fija el modelo al que se resuelve el alias fable (útil en Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE excluye a Fable del almacenamiento en caché de prompts y, en las puertas de enlace empresariales, se aplica la conmutación automática por error según el contenido. /model opus ahora selecciona Opus 5 (esfuerzo alto de forma predeterminada; /effort xhigh para las tareas más difíciles), mientras que Sonnet 5 es el modelo predeterminado listo para usar desde la v2.1.197. Selecciona Fable 5 deliberadamente mediante /model fable cuando necesites la capacidad máxima.²⁰⁴¹⁹⁷

Opus 4.7 (16 de abril de 2026): El modelo insignia de la generación anterior, que sigue totalmente disponible. Ventana de contexto de 1M de tokens con 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 programación y basadas en agentes.¹⁴⁵ Fecha límite de conocimiento fiable: enero de 2026. Fecha límite de los datos de entrenamiento: enero de 2026. ID del modelo: claude-opus-4-7. El precio coincide con el de Opus 4.6: $5/$25 por MTok, con escritura en caché de 5 minutos a $6.25, escritura en caché de 1 hora a $10 y lectura de caché a $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 la versión 4.6) y mejora un 13 % la resolución en la prueba comparativa interna de programación de 93 tareas de Anthropic.¹⁴⁴ Utiliza un nuevo tokenizador: para el mismo texto, espera entre 1 y 1,35 veces la cantidad de tokens; aumenta el margen de max_tokens y los umbrales de compactación.¹⁴⁵ La visión admite imágenes de hasta 2.576 px / 3,75 MP con coordenadas de píxeles 1:1.¹⁴⁵

Pruebas comparativas de programación de Opus 4.7 (abril de 2026):¹⁵¹

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

Cambios incompatibles de la API de Messages en Opus 4.7 (visibles para quien realiza la llamada):¹⁴⁵ - Se eliminó budget_tokens del pensamiento extendido. Usa thinking: {type: "adaptive"} en su lugar. El pensamiento adaptativo está desactivado de forma predeterminada; las solicitudes sin el campo thinking se ejecutan sin pensamiento. - Configurar temperature, top_p o top_k con un valor distinto del predeterminado devuelve un error HTTP 400. Omite estos parámetros y orienta el modelo mediante el prompt. - El contenido del pensamiento se omite de las respuestas de forma predeterminada. Configura thinking.display: "summarized" para volver a mostrar el razonamiento (es obligatorio si tu producto transmite el pensamiento a los usuarios).

Los presupuestos de tareas (encabezado beta task-budgets-2026-03-13) te permiten indicar al modelo un objetivo de tokens para un ciclo agéntico completo mediante output_config.task_budget; el mínimo es de 20.000 tokens.¹⁴⁵

Opus 4.6 (heredado): Sigue disponible en claude-opus-4-6, con un contexto de 1 millón y una salida máxima de 128.000 tokens. Considera migrar a Opus 4.7 para obtener una mejor programació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 de forma predeterminada el esfuerzo high en Opus 4.6 y Sonnet 4.6 (antes era medium); Opus 4.7 se mantiene en xhigh. Este cambio recuperó la capacidad del modelo tras la reducción de esfuerzo del 4 de marzo al 7 de abril, documentada en el análisis retrospectivo del 23 de abril.¹⁵²¹⁵³

Sonnet 5 (30 de junio de 2026): La versión actual de la gama Sonnet, presentada como «la mejor combinación de velocidad e inteligencia». Anthropic afirma que su rendimiento es cercano al de Opus 4.8, pero con precios más bajos, y que supone una mejora considerable frente a Sonnet 4.6 en razonamiento agéntico, uso de herramientas, programación y trabajo intelectual; al mismo tiempo, presenta una tasa general más baja de comportamientos indeseables y una capacidad de ciberseguridad mucho menor que los modelos Opus (la concesión en materia de seguridad que permitió lanzarlo sin bloqueos por controles de exportación). ID del modelo: claude-sonnet-5 (instantánea fija sin fecha). Ventana de contexto de 1 millón de tokens, salida máxima de 128.000 tokens (hasta 300.000 en API Batches con el encabezado beta output-300k-2026-03-24) y únicamente pensamiento adaptativo. Fecha límite de conocimiento confiable: enero de 2026. Precio: $3/$15 por millón de tokens de entrada/salida, con un precio introductorio de $2/$10 hasta el 31 de agosto de 2026, aproximadamente un 40 % menos que los $5/$25 de Opus 4.8. En Claude Code, el parámetro effort se establece de forma predeterminada en high para Sonnet 5 (configúralo explícitamente si quieres cambiarlo). Selecciónalo con /model sonnet (o /model claude-sonnet-5).¹⁸⁰ A partir de v2.1.197 (30 de junio de 2026), Sonnet 5 es el modelo predeterminado en Claude Code para las sesiones nuevas, en sustitución de Opus 4.8 como opción inicial; Opus sigue estando disponible para seleccionarlo.¹⁸¹

Sonnet 4.6 (17 de febrero de 2026, ahora reemplazado por Sonnet 5): Modelo equilibrado; sustituyó a Sonnet 4.5 como opción predeterminada en claude.ai y Claude Cowork.⁹³ Tiene el mismo precio que Sonnet 4.5 ($3/$15 por millón de tokens). Mejoró el rendimiento de búsqueda agéntica y consume menos tokens. Admite pensamiento extendido, pensamiento adaptativo y una ventana de contexto de 1 millón de tokens (beta). Salida máxima de 64.000 tokens (límite superior de 128.000 en v2.1.77).¹¹⁹ Fecha límite 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 de vanguardia en versión preliminar de investigación para trabajos de ciberseguridad defensiva, ofrecido mediante Project Glasswing.¹³⁹ Solo está disponible por invitación, no para el público general. Anthropic presenta Opus 4.7 como deliberadamente menos capaz que Mythos en aspectos relacionados con la ciberseguridad —una concesión en materia de seguridad— y abrió un Cyber Verification Program en https://claude.com/form/cyber-use-case para investigadores de seguridad legítimos que necesiten acceso ampliado.¹⁴⁶

Por qué importan estas diferencias de precio: Una sesión típica de programación consume entre 50.000 y 200.000 tokens de entrada y entre 10.000 y 50.000 tokens de salida. Con Haiku, cuesta entre $0,10 y $0,45 por sesión. Con Opus, la misma sesión cuesta entre $0,50 y $2,25, es decir, 5 veces más. Reserva Opus para problemas realmente difíciles.¹

Cuándo usar cada modelo

Haiku: Úsalo para subagents que realicen exploración, búsquedas sencillas de archivos y consultas rápidas. Es aproximadamente 5 veces más barato que Opus y responde con mayor rapidez. Resulta perfecto para tareas en segundo plano que no requieren un razonamiento profundo.

Sonnet: La opción principal para el desarrollo cotidiano cuando el costo es importante. Resuelve la mayoría de las tareas de programación: implementar funciones, corregir errores, escribir pruebas y revisar código. Sonnet 4.6 ofrece una búsqueda agéntica mejorada y una mayor eficiencia de tokens que Sonnet 4.5, además de admitir pensamiento adaptativo y una ventana de contexto de 1 millón de tokens con el precio estándar.⁹³ Desde Opus 4.7 (16 de abril de 2026), Claude Code utiliza Opus de forma predeterminada solo en los planes Max y Team Premium; las cuentas Pro, Team Standard, Enterprise y API mantienen Sonnet 4.6 como opción predeterminada hasta que Enterprise y API cambien a Opus 4.7 el 23 de abril de 2026.¹⁴⁷ Usa Sonnet cuando necesites tokens más baratos, menor latencia o una mejor relación costo-beneficio para los subagents.

Opus: La gama insignia desde el 16 de abril de 2026 y la opción predeterminada en los planes Max y Team Premium.¹⁴⁴¹⁴⁷ Reserva su razonamiento de mayor costo para cuando realmente marque la diferencia: decisiones arquitectónicas, depuración compleja, comprensión de sistemas complejos, análisis de seguridad y trabajo agéntico de largo alcance. 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 %) y aumenta un 13 % la resolución en una evaluación interna de programación con 93 tareas.¹⁴⁴ Claude Code utiliza de forma predeterminada el esfuerzo xhigh en Opus 4.7, que puedes ajustar mediante /effort (v2.1.111+).¹⁴⁶¹⁴⁷ Auto Mode está disponible para los suscriptores Max en Opus 4.7 mediante Anthropic API, sin necesidad de --enable-auto-mode; en otros planes y proveedores, la disponibilidad depende del plan y de los controles del administrador.¹⁴⁶ Contexto de 1 millón de tokens al precio estándar, sin recargo por contexto extenso. Cambios de comportamiento que conviene conocer: Opus 4.7 sigue las instrucciones de manera más literal, ajusta la extensión de sus respuestas a la complejidad de la tarea, ejecuta menos subagents de forma predeterminada y adopta un tono más directo, con menos expresiones centradas en la validación. Si tus prompts incluyen estructuras para forzar mensajes provisionales de progreso o comprobaciones adicionales, prueba quitarlas.¹⁴⁵

Opusplan: Un modo híbrido que usa Opus para la planificación (donde más importa la calidad del razonamiento) y Sonnet para la ejecución (donde importa la velocidad). Es excelente para refactorizaciones complejas en las que quieres el mejor plan, pero no necesitas razonamiento del nivel de 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 el entorno:

export ANTHROPIC_MODEL=opus

En settings.json:

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

Específicamente para subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Cadena de modelos alternativos (v2.1.166+): La configuración fallbackModel permite definir hasta tres modelos alternativos, que se prueban en orden cuando el modelo principal está sobrecargado o no está disponible. La opción --fallback-model (que antes solo permitía cambiar durante una sesión) ahora también se aplica a las sesiones interactivas desde el inicio.²⁰⁶

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Cuando API devuelve un error inesperado que no admite reintentos, Claude Code ahora también vuelve a intentar el turno una vez con el modelo alternativo antes de mostrar el fallo, de modo que un problema transitorio del modelo principal se resuelve con elegancia en lugar de interrumpir el turno.²⁰⁶

A partir de v2.1.178, la compactación también respeta la cadena de modelos alternativos: si el modelo principal está sobrecargado o no está disponible durante la compactación, este paso recurre a la cadena configurada mediante fallbackModel/--fallback-model en lugar de interrumpir el turno. En una ejecución autónoma prolongada, esto corrige el caso en el que una compactación recuperable podía interrumpir la sesión debido a un error transitorio del modelo.¹⁷³

Contexto extendido

Para bases de código grandes o sesiones prolongadas, habilita el contexto de 1 millón de tokens:

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 with 1M context

O durante una sesión:

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

Opus 4.7, Opus 4.6 y Sonnet 4.6 incluyen la ventana de contexto completa de 1 millón de tokens con el precio estándar, sin recargo por contexto extenso.¹⁴⁸ Una solicitud de 900.000 tokens se factura con la misma tarifa por token que una de 9.000. Los descuentos por almacenamiento en caché de prompts y procesamiento por lotes se aplican con las tarifas estándar en toda la ventana de contexto.

En las suscripciones Max, Team y Enterprise, Opus con contexto de 1 millón de tokens se incluye automáticamente, sin necesidad del sufijo [1m] (habilitado de forma predeterminada desde v2.1.75, el 13 de marzo de 2026).¹¹⁷¹⁴⁷ En Pro, puedes acceder al contexto de 1 millón mediante el uso adicional. Los usuarios de API y de pago por uso tienen acceso completo al contexto de 1 millón con las tarifas estándar por token.¹⁴⁷ Para desactivar las variantes con contexto de 1M en el selector de modelos, configura CLAUDE_CODE_DISABLE_1M_CONTEXT=1. A partir de v2.1.223, cambió el alcance de la variable: limita a 200K mediante compactación automática todos los modelos con una ventana nativa de 1M, no solo una lista fija de variantes conocidas, y aparece una advertencia al iniciar cuando la compactación automática no mantiene realmente la sesión en 200K. Si configuras esta variable para obtener costos predecibles en una familia de modelos, ahora también se aplicará a los nuevos modelos de 1M desde el día de su lanzamiento, en lugar de dejar de funcionar silenciosamente. La misma versión hace que la compactación automática mantenga las sesiones con ID de modelos no reconocidos dentro de la ventana de contexto estimada, en vez de permitir que la superen; CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 restaura el comportamiento anterior para gateways que registran ID personalizados con ventanas reales más grandes.²⁰⁰

Consultar el modelo actual

> /status

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

Etiquetas del selector de modelos (v2.1.51+): El selector /model ahora muestra etiquetas fáciles de interpretar (por ejemplo, «Sonnet 4.6») en lugar de los ID sin procesar de las versiones fijadas, junto con sugerencias de actualización cuando hay versiones más recientes disponibles.⁹⁸ v2.1.219 corrige la visualización de la fila combinada de Opus para que aparezca simplemente como «Opus» en lugar de «Opus (contexto de 1M)» y limita el resaltado de nuevos lanzamientos únicamente al nombre del modelo más reciente, de modo que indique qué se lanzó realmente y no un segmento arbitrario de la lista.¹⁹⁶

Modo rápido (v2.1.36+)

El modo rápido ofrece una salida considerablemente más veloz con el mismo modelo; no cambia a un modelo más económico. Actívalo o desactívalo durante una sesión con /fast.⁸⁶

> /fast            # Toggle fast mode on/off

Modelos compatibles (a partir de v2.1.219): el modo rápido se aplica a Claude Opus 5 y Claude Opus 4.8. v2.1.219 eliminó Opus 4.7 del modo rápido, y la función nunca estuvo disponible en Sonnet, Haiku ni Fable. Sigue siendo una versión preliminar de investigación disponible únicamente en la API de Claude (incluido Claude Managed Agents), no en Amazon Bedrock, Google Cloud, Microsoft Foundry ni Claude Platform on AWS. El acceso está restringido: comunícate con tu gerente de cuenta o inscríbete en la lista de espera.¹⁹⁶¹⁹⁸

Precios (modo rápido de Opus 5 / Opus 4.8):¹⁹⁸

La trampa de Opus 4.7 (v2.1.219). Los modelos no compatibles no se comportan de la misma manera. Una solicitud a claude-opus-4-7 con speed: "fast" ahora devuelve un error; no recurre silenciosamente a la velocidad estándar. Opus 4.6 es la excepción que hace importante conocer este detalle: acepta speed: "fast", pero se ejecuta a velocidad estándar, se factura con las tarifas estándar e informa usage.speed: "standard". Si tu harness tenía fijada la versión 4.7 y dependía de que las solicitudes en modo rápido pasaran discretamente al modo estándar, ahora fallarán de forma directa; cambia la versión fijada a Opus 5 o 4.8.¹⁹⁸

Cuándo usar el modo rápido: - Al iterar rápidamente sobre cambios pequeños cuando la latencia es el cuello de botella - Al generar pruebas, código repetitivo o estructuras base donde la velocidad importa más que el costo - Al completar secuencialmente una lista de tareas similares

Cuándo NO usar el modo rápido: - En tareas agénticas de larga duración (el costo sigue duplicándose durante toda la ejecución) - En el trabajo de subagents en segundo plano (nadie está esperando la salida) - En sesiones con un presupuesto limitado

El modo rápido incluye la ventana de contexto completa de 1M (v2.1.50+). El precio consiste en un multiplicador fijo para todo el contexto, incluidas las solicitudes con más de 200K tokens de entrada, sin recargos adicionales por contexto extenso, y se acumula con los multiplicadores del almacenamiento en caché de prompts y la residencia de datos.⁹⁶¹⁹⁸

Notas operativas. El modo rápido tiene su propio límite de uso, independiente de los límites estándar de Opus; al superarlo, devuelve un 429 con retry-after (los encabezados de respuesta anthropic-fast-*-tokens-* informan la capacidad restante). Cambiar entre el modo rápido y el estándar invalida la caché de prompts: las solicitudes a distintas velocidades no comparten los prefijos almacenados en caché, por lo que activar o desactivar /fast durante una sesión provoca un fallo de caché. El modo rápido no está disponible con la API Batch ni con un compromiso de Priority Tier.¹⁹⁸

Consejo experto: El modo rápido no funciona junto con opusplan (opusplan ya combina Opus y Sonnet; el modo rápido solo afecta la parte de Opus). Úsalo cuando la latencia sea más importante que el costo y desactívalo para el trabajo autónomo o por lotes. /fast requiere uso adicional; es posible que los administradores de Team/Enterprise deban habilitarlo primero (corrección de v2.1.37). Desactívalo por completo con CLAUDE_CODE_DISABLE_FAST_MODE=1. A partir de v2.1.218, Claude Code avisa cuando un cambio de modelo mediante /config model=<x> o Remote Control modifica el estado del modo rápido; además, v2.1.219 corrigió un problema que hacía que los clientes de Remote Control conservaran un estado obsoleto del modo rápido después de cambiar de modelo, volver a conectarse o fallar una comprobación de la organización.^86149195196

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

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

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

Auto Mode en Max (v2.1.111+)

Auto Mode, un sustituto más seguro de --dangerously-skip-permissions, está disponible para los suscriptores de Max con Opus 4.7 mediante la API de Anthropic, sin --enable-auto-mode.¹⁴⁶ Un clasificador Sonnet 4.6 revisa cada acción antes de ejecutarla y comprueba que coincida con la intención y sea segura. Nota (v2.1.111+): se eliminó la opción --enable-auto-mode; para iniciar una sesión en Auto Mode, usa --permission-mode auto. Auto Mode no está disponible en Pro; según la documentación de modos de permisos de Anthropic, está disponible directamente y de forma predeterminada en la API de Anthropic. Bedrock/Vertex/Foundry (v2.1.158+): Auto Mode pasó a ser opcional en Opus 4.7 y Opus 4.8 en esos gateways mediante CLAUDE_CODE_ENABLE_AUTO_MODE=1.²⁰⁹ A partir de v2.1.207, ya no es necesario habilitarlo: Auto Mode funciona en AWS Bedrock, Google Vertex AI y Microsoft Foundry sin CLAUDE_CODE_ENABLE_AUTO_MODE; los administradores que quieran desactivarlo pueden hacerlo con la configuración administrada disableAutoMode. La misma versión hace que Bedrock, Vertex AI y Claude Platform on AWS utilicen Claude Opus 4.8 de forma predeterminada y deja de leer la configuración autoMode del archivo .claude/settings.local.json de un repositorio; en su lugar, configura las reglas de Auto Mode en ~/.claude/settings.json.¹⁸⁵

Reglas personalizadas sin perder las predeterminadas (v2.1.118+). En las versiones anteriores, autoMode.allow, autoMode.soft_deny y autoMode.environment funcionaban de manera excluyente: si definías tu propia lista, perdías las reglas de seguridad integradas. El centinela $defaults resuelve este problema: se expande en línea como la lista integrada exactamente en la posición donde lo colocas, lo que permite disponer tus reglas personalizadas alrededor de ella:¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

Opción «No volver a preguntar» (v2.1.118+). El mensaje para habilitar Auto Mode ahora incluye la opción «No volver a preguntar», de modo que los usuarios frecuentes pueden ocultar la explicación sin automatizar una opción mediante scripts.¹⁵²

Medidas de protección contra comandos destructivos (v2.1.183). Auto Mode ahora bloquea por completo un conjunto de comandos irreversibles, salvo que los hayas solicitado explícitamente durante la sesión: operaciones destructivas de git (git reset --hard, git checkout -- ., git clean -fd, git stash drop) cuando no pediste descartar el trabajo local; git commit --amend cuando el agente no creó el commit durante esta sesión; y la eliminación de infraestructura (terraform destroy, pulumi destroy, cdk destroy), a menos que hayas indicado la pila específica. Esto reduce el alcance potencial del clasificador precisamente en las operaciones que pueden eliminar silenciosamente el trabajo o desmantelar entornos. El agente todavía puede ejecutarlas, pero solo si se lo indicas de forma explícita, no por iniciativa propia.¹⁷⁴ Clasifica todos los comandos de shell (v2.1.193). De forma predeterminada, el clasificador del modo automático solo revisa los comandos de shell que coinciden con patrones de ejecución de código arbitrario; los comandos rutinarios lo omiten. La nueva configuración autoMode.classifyAllShell hace que, en cambio, todos los comandos de Bash/PowerShell pasen por el clasificador, sacrificando un poco de latencia a cambio de una red de seguridad más estricta cuando quieres que se examine cada llamada al shell. La misma versión también muestra los motivos de rechazo del modo automático en la transcripción, la notificación emergente del rechazo y los rechazos recientes de /permissions, de modo que un comando bloqueado ahora explica por qué se bloqueó.¹⁷⁹

Tres reglas de protección adicionales (v2.1.205). Ahora, el modo automático impide la manipulación de los archivos de transcripción de la sesión —el registro de auditoría queda fuera del alcance del agente—; solicita confirmación antes de ejecutar rm -rf sobre una variable que no puede resolver a partir del contexto —lo que evita la clase de accidentes de rm -rf $DIR con un $DIR desconocido—; y las notificaciones de tareas en segundo plano ahora indican explícitamente que no hubo intervención humana, por lo que una línea falsa como «el usuario aprobó» dentro de una transcripción no puede hacerse pasar por una aprobación válida y ejecutable.¹⁸³ Vale la pena interiorizar la tercera como defensa contra la inyección de prompts: la aprobación debe llegar mediante el canal de aprobación, y el entorno de ejecución ahora hace explícita esa condición.

La sustitución de comandos no puede ocultar una catástrofe (v2.1.208). Las eliminaciones catastróficas, como rm -rf ~, ahora solicitan confirmación incluso cuando están ocultas dentro de $(...), acentos graves o una sustitución de procesos (<(...)), y la solicitud aparece incluso en --dangerously-skip-permissions y en el modo automático. Envolver un comando destructivo en una sustitución ya no permite eludir la red de seguridad.¹⁸⁶

Restablece el estado del modo automático: claude auto-mode reset (v2.1.212). Un nuevo subcomando permite restablecer el estado del modo automático desde la terminal; pasa --yes para omitir la solicitud de confirmación:¹⁸⁹

claude auto-mode reset          # Confirmation prompt
claude auto-mode reset --yes    # Skip confirmation (scripts)

Menos cuadros de diálogo, el mismo nivel de escrutinio (v2.1.218). Tres comprobaciones que antes interrumpían el modo automático con un cuadro de diálogo de permisos —rm peligroso, & en segundo plano y rutas sospechosas de Windows— ya no lo hacen; ahora el clasificador del modo automático las evalúa, de modo que la revisión de seguridad sigue realizándose sin involucrarte cada vez que se detecta una coincidencia. La misma versión extiende este comportamiento al modo de planificación con el modo automático: los comandos de Bash que el analizador estático no puede confirmar como de solo lectura ya no solicitan permiso; el clasificador los evalúa en lugar de recurrir a un cuadro de diálogo.¹⁹⁵

Nuevos comandos en v2.1.105–v2.1.114¹⁴⁶¹⁵⁰

Notificaciones push (v2.1.110+)

Cuando Remote Control está configurado con la opción «Enviar cuando Claude lo decida» habilitada, Claude ahora puede enviar notificaciones push a dispositivos móviles según su propio criterio mediante una nueva herramienta de notificaciones push. Se complementa con la interfaz móvil/web existente de Remote Control.¹⁴⁶ /context, /exit y /reload-plugins ahora también funcionan desde clientes de Remote Control.

Herramienta nativa de Windows PowerShell (v2.1.111+, implementación gradual)

Claude Code está implementando gradualmente una herramienta nativa de Windows PowerShell. En Linux/macOS, actívala con CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (requiere pwsh en PATH). En Windows, la misma variable controla la activación o desactivación durante la implementación gradual.¹⁴⁶

Aprobación automática en el modo de permisos (v2.1.119+). Los comandos de la herramienta PowerShell ahora pueden recibir aprobación automática en el modo de permisos, de la misma forma que los comandos de Bash. Las reglas de permiso como PowerShell(Get-*:*) y la sintaxis de patrones existente ahora omiten la solicitud para las operaciones de solo lectura, lo que ofrece la misma facilidad operativa de la que ya disponen los equipos en Linux/macOS.¹⁵²

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

Los patrones de Bash de solo lectura con argumentos glob (p. ej., ls *.ts, cat src/*.md) y los comandos que comienzan con cd <project-dir> && ya no activan una solicitud de permisos.¹⁴⁶ En combinación con /less-permission-prompts, puedes esperar muchas menos interrupciones en los flujos de trabajo cotidianos.

Seguimiento distribuido (v2.1.110+)

Las sesiones de SDK y sin interfaz ahora leen TRACEPARENT y TRACESTATE del entorno, lo que vincula las ejecuciones de Claude Code con seguimientos distribuidos. Combínalo con OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) para emitir los cuerpos completos de las solicitudes y respuestas de API como eventos de registro de OpenTelemetry con fines de depuración.¹⁴⁶

Distribución de binarios nativos (v2.1.113+)¹⁵⁰

v2.1.113 cambia la forma en que se inicia CLI: ahora claude genera un binario nativo de Claude Code mediante una dependencia opcional específica de cada plataforma, en lugar de ejecutar el JavaScript incluido. Los comandos de instalación y actualización no cambian, y los equipos no necesitan modificar sus scripts de implementación.

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

El editor de prompts incorpora navegación al estilo de readline en entradas multilínea, además de desplazamiento por el área visible en pantalla completa:

Tiempo de espera por bloqueo de subagents (v2.1.113+)¹⁵⁰

Los subagents que se bloquean a mitad de una transmisión ahora fallan con un error claro después de 10 minutos, en lugar de quedar suspendidos en silencio. Combínalo con CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para ampliar la cobertura de procesos bloqueados en API con transmisión.

Corrección de estabilidad de v2.1.114¹⁵⁰

v2.1.114 (18 de abril de 2026) incluye una única corrección: el cuadro de diálogo de permisos podía cerrarse inesperadamente cuando un integrante de un equipo de agentes solicitaba permiso para usar una herramienta. Actualiza si utilizas Agent Teams.

¿Cuánto cuesta Claude Code?

Comprender y controlar los costos es esencial para usar Claude Code de manera sostenible. Consulta también Selección de modelos para conocer las capacidades de cada modelo y Marcos de decisión para elegir el modelo adecuado para cada tarea.

Consulta de costos

> /cost

Resultado:

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 en /cost un desglose por modelo y aciertos de caché, que muestra exactamente qué modelos consumieron tokens y cuánto contenido se sirvió desde la caché (v2.1.92+).¹³⁷

Planes de suscripción

Límites de uso (agosto de 2025): Anthropic introdujo límites semanales para los suscriptores de pago. Los suscriptores de Max pueden comprar uso adicional una vez alcanzado el límite, según las tarifas estándar de API.¹⁴

Duplicación de los límites de uso (6 de mayo de 2026): Durante el evento Code with Claude SF, Anthropic duplicó los límites de uso de cinco horas de Claude Code en los planes Pro, Max, Team y Enterprise por puesto, eliminó la reducción en horas pico de las cuentas Pro y Max y aumentó «considerablemente» los límites de API para los modelos Claude Opus. El respaldo de capacidad es el acuerdo SpaceX Colossus 1: «más de 300 megavatios de nueva capacidad (más de 220.000 GPU) durante el mes».¹⁵⁷

Precios por token de API (abril de 2026)¹¹⁴⁴

Para los usuarios con facturación mediante API, estos son los precios por millón de tokens:

Precio del contexto de 1M (abril de 2026): Opus 4.7, Opus 4.6, Sonnet 4.6 y Mythos Preview incluyen 1M a las tarifas estándar por MTok, sin recargo por contexto largo.¹⁴⁸ Esta es una consolidación reciente; las indicaciones anteriores según las cuales Opus 4.6 o Sonnet 4.6 costaban 2 veces más por entrada y 1,5 veces más por salida al superar los 200K tokens de entrada ya no están vigentes. Opus 4.5 y los modelos anteriores conservan sus estructuras de precios originales.

Precio por residencia de datos: Especificar que la inferencia se realice exclusivamente en EE. UU. mediante inference_geo aplica un multiplicador de 1,1 a todos los precios por token, incluidas las lecturas y escrituras de caché (modelos Opus 4.6 y posteriores).¹⁴⁸

El almacenamiento en caché de prompts reduce considerablemente los costos de las entradas repetidas: escribir en la caché cuesta 1,25 veces la tarifa base (caché de 5 minutos) o 2 veces (caché de 1 hora), pero leer de ella cuesta apenas 0,1 veces esa tarifa, lo que supone un ahorro del 90%. En sistemas RAG y asistentes de programación que reutilizan el contexto, el almacenamiento en caché puede reducir los costos entre un 88% y un 95%.

Batch API ofrece descuentos del 50% y entrega en un plazo de 24 horas para tareas no urgentes, como conjuntos de pruebas ejecutados durante la noche.

Política sobre varias cuentas⁵²

¿Puedes tener varias cuentas de Claude? Sí, cuando existen motivos legítimos. Anthropic permite explícitamente varias cuentas si tienen finalidades distintas.

Qué está permitido:

Límites técnicos: - Se pueden verificar hasta 3 cuentas con el mismo número telefónico - Se admiten explícitamente varias suscripciones de pago desde la misma dirección IP o red - Las cuentas están completamente separadas; no es posible transferir chats ni proyectos entre ellas

Qué está prohibido (según la Política de uso): - Crear cuentas para evadir bloqueos después de recibir uno - Coordinar actividades maliciosas entre varias cuentas para evitar su detección - Usar varias cuentas para eludir los límites de uso o los créditos del nivel gratuito

Nota basada en un caso real: En enero de 2026, las 22 cuentas Max del usuario avanzado Jeffrey Emanuel (@doodlestein) fueron marcadas automáticamente y bloqueadas de forma temporal. Thariq (@trq212), empleado de Anthropic, resolvió el caso en menos de 4 horas tras confirmar que se trataba de un uso legítimo. Si utilizas Claude Code de forma intensiva para proyectos laborales y personales distribuidos entre varias cuentas, eso es precisamente lo que permite el servicio; pero no intentes manipular el sistema.

Si tienes dudas: Comunícate con el soporte de Anthropic para obtener una confirmación por escrito sobre tu configuración específica.

Factores de costo

Ejemplos de costos reales

Consejo para ahorrar: Usar Haiku para los subagents de exploración y Sonnet para la implementación suele reducir los costos entre un 40% y un 50% frente a usar Sonnet para todo.

Gestión de costos de equipos

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

Cargos ocultos de las herramientas

Además del precio por token, algunas herramientas aplican cargos independientes:⁹

Estos costos se acumulan en los ciclos de agentes. Un ciclo de depuración de 100 iteraciones con Bash consume aproximadamente 24.500 tokens de entrada adicionales solo en sobrecostos.

Estrategias para ahorrar costos

1. Usa Haiku para los subagents: La mayoría de las tareas de exploración no necesitan Sonnet
2. Activa el almacenamiento en caché de prompts: Está activado de forma predeterminada, pero verifica que no se haya deshabilitado
3. Establece un máximo de turnos: claude --max-turns 5 evita que las conversaciones se prolonguen sin control
4. Establece un límite en dólares: claude --max-budget-usd 5 detiene por completo la sesión cuando se alcanza el límite de gasto. Desde la versión v2.1.217, el límite también controla los subagents en segundo plano: una vez alcanzado, se impide iniciar otros nuevos y se detienen los que estén ejecutándose en segundo plano (antes, estos agentes no estaban sujetos al presupuesto)¹⁹⁴
5. Usa el modo de planificación para explorar: Sin ejecución, no hay operaciones costosas accidentales
6. Compacta de forma proactiva: Menos contexto = menos tokens
7. Limita la salida: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. Usa Batch API para trabajos no urgentes: 50% de descuento en los tokens de entrada y salida

Supervisión del uso

• Consola de Claude: platform.claude.com (requiere el rol Admin o Billing)
• Límites del espacio de trabajo: Establece límites de gasto por espacio de trabajo
• Bedrock/Vertex: Usa las herramientas nativas de supervisión de costos de la nube
• LiteLLM: Para obtener un 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

Por lo general, cuestan menos de $0.04 por sesión.

API de analítica de Claude Code (Team/Enterprise)⁴⁶

Accede mediante programación a las estadísticas de uso y las métricas de productividad de Claude Code de tu organización a través de la API de administración.

Endpoint: GET /v1/organizations/usage_report/claude_code

Requisitos: - Clave de API de administración (sk-ant-admin...) - Plan Team o Enterprise - Rol 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 la productividad de los desarrolladores (sesiones, commits y PR) - Métricas de uso de herramientas (tasas de aceptación y rechazo de Edit, Write, etc.) - Seguimiento y asignación de costos entre equipos - Justificación de ROI para herramientas de programación con IA

Nota: Los datos aparecen durante la hora posterior a la finalización de la actividad. Para mantener la coherencia, las respuestas solo incluyen datos con más de 1 hora de antigüedad.

Marcos de decisión

No basta con saber que las funciones existen. Necesitas saber cuándo usar cada una. Estos árboles de decisión convierten el conocimiento en acción.

¿Qué modelo debería 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 modelo predeterminado para Max y Team Premium. En Pro/Team Standard/Enterprise/API, Sonnet 4.6 es el modelo predeterminado (Enterprise + Anthropic API cambiarán a Opus 4.7 el 23 de abril de 2026).¹⁴⁷ Usa Haiku para los subagents. Cambia a Opus cuando la respuesta de Sonnet parezca superficial. Con agent teams (v2.1.32+), Opus puede coordinar varios agentes que trabajan en paralelo en distintas subtareas.⁷⁹

¿Command, skill, subagent o agent team?

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 o 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

Actívalo o desactívalo con Alt+T durante la sesión. Los presupuestos de razonamiento más altos cuestan más; comienza con el mínimo y auméntalo únicamente si las respuestas parecen apresuradas.

Razonamiento adaptativo de Opus 4.6: Opus 4.6 ajusta automáticamente la profundidad del razonamiento según la complejidad del problema. Para la mayoría de las tareas, no es necesario controlar explícitamente el presupuesto de razonamiento: Opus lo aumenta ante problemas difíciles y mantiene la rapidez en los sencillos. Activar o desactivar manualmente el razonamiento resulta más útil con Sonnet cuando quieres forzar un análisis más profundo.

¿Qué superficie de ejecución usar?

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

Agent teams, subagents o 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 usar?

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   (Opus 5 or Opus 4.8 only, v2.1.219+)
│         Same model, ~2.5× output speed at 2× price
│         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 o desactiva el modo rápido para la sesión actual. Usa el mismo modelo —Opus 5 u Opus 4.8, los únicos 2 modelos compatibles con el modo rápido a partir de la versión v2.1.219— con una velocidad de salida optimizada. NO cambia a un modelo más barato y, a $10/$50 por MTok, tampoco cuesta menos.¹⁹⁶¹⁹⁸

¿Cómo funciona el sistema de permisos?

El sistema de permisos de Claude Code ofrece un control detallado sobre las operaciones que pueden ejecutarse. Comprenderlo es fundamental tanto para la seguridad como para la eficiencia del flujo de trabajo. Consulta también Implementación empresarial para conocer la configuración administrada 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 mediante patrones - Grep - Buscar en el contenido de archivos - WebSearch - Buscar en la web - LSP - Inteligencia de código (ir a la 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 la definición: Saltar al lugar donde se define un símbolo - Buscar referencias: Enumerar todos los usos de un símbolo en el código base - Documentación al pasar el cursor: Obtener información de tipos y documentación de cualquier símbolo - Funciona con TypeScript, Python, Go, Rust y otros lenguajes compatibles con LSP - Requiere que el servidor de lenguaje esté disponible (por lo general, se instala junto 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 una URL - NotebookEdit - Modificar cuadernos 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.

Herramienta EndConversation (v2.1.214). Claude Code ahora cuenta con la misma capacidad para finalizar conversaciones que Claude tiene en claude.ai desde 2025: en casos poco frecuentes de contenido sumamente abusivo o intentos persistentes de jailbreak, Claude puede finalizar la sesión de inmediato mediante la herramienta integrada EndConversation. Es una medida de resistencia al abuso y de bienestar del modelo, no una función del flujo de trabajo; nunca se activa en sesiones normales de desarrollo.¹⁹⁰¹⁹³

Modos de permisos

El modo default se etiqueta como “Manual” desde la v2.1.200. El cambio de nombre abarca CLI, --help, VS Code y JetBrains; el valor de configuración no cambió, por lo que "defaultMode": "default" sigue funcionando, mientras que --permission-mode manual y "defaultMode": "manual" ahora se aceptan como alias. El comportamiento es idéntico —solicita confirmación la primera vez que se usa cada herramienta—; la etiqueta simplemente dejó de sugerir que se trata del «modo que recibes de forma predeterminada», cuando en realidad es el modo de aprobación manual. En la misma versión, los cuadros de diálogo de AskUserQuestion ya no continúan automáticamente de forma predeterminada; cuando un subagent hace una pregunta, ahora espera tu respuesta en vez de continuar tras agotarse el tiempo de espera. Puedes volver a activar un tiempo de espera por inactividad mediante /config.

Ahora se solicita confirmación para los archivos de configuración que pueden ejecutar código, incluso con acceptEdits (v2.1.160). acceptEdits aprueba automáticamente las ediciones comunes, pero, desde la v2.1.160, se detiene y solicita confirmación antes de escribir en archivos capaces de autorizar la ejecución silenciosa de comandos: archivos de inicio del shell (.zshenv, .zlogin, .bash_login), ~/.config/git/ y configuraciones de herramientas de compilación (.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/ y similares). La razón es que editar cualquiera de ellos convierte el siguiente inicio de shell, instalación o commit en un vector de ejecución, por lo que reciben una barrera deliberada incluso en un modo para proyectos de confianza que normalmente permite las ediciones sin intervención. Este es el mismo modelo de amenazas que sustenta las protecciones existentes contra escritura en .claude/, .git/ y .vscode/, ampliado a la categoría más extensa de archivos donde «editar equivale a ejecutar».²⁰⁸

Auto Mode (v2.1.85+): Una alternativa más segura a --dangerously-skip-permissions. Un modelo clasificador independiente (Sonnet 4.6) revisa cada acción antes de ejecutarla y comprueba que coincida con la intención del usuario y 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 permiso y denegación se resuelven primero - Todo lo demás se envía al clasificador para su evaluación - Si se bloquea una acción, Claude intenta automáticamente un enfoque alternativo

Bloqueado automáticamente de forma predeterminada: curl | bash, force-push a main, implementaciones o migraciones en producción, eliminaciones masivas en la nube, cambios en IAM o permisos y envío externo de datos confidenciales.¹²⁵

Disyuntor: tras 3 bloqueos consecutivos o 20 en total durante una sesión, se vuelve a las solicitudes de confirmación manuales.¹²⁵

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

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

Disponibilidad: primero para usuarios del plan Team; Enterprise y API estarán disponibles después. Requiere Sonnet 4.6 u Opus 4.6.¹²⁴

YOLO Mode (v2.0.68+): Para un funcionamiento completamente autónomo sin ningún clasificador de seguridad, usa la opción --dangerously-skip-permissions. Esta opción acepta todo: ediciones de archivos, comandos bash y todas las llamadas a herramientas. La palabra «dangerous» es intencional. Auto Mode 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

Cámbialo durante la sesión:

Shift+Tab  # Cycles through modes

En settings.json:

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

Sintaxis de las reglas de permisos

Las reglas detalladas controlan operaciones específicas. Se evalúan en orden: se aplica 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 permite la 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 de Bash solo buscan coincidencias por prefijo, no mediante 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 garantizar el bloqueo, deniega el comando completo: Bash(curl:*).

Patrones de operaciones con archivos:

{
  "allow": [
    "Edit(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 - Rutas absolutas desde el archivo de configuración: Edit(/build/**) - relativas a la ubicación del archivo de configuración - Rutas realmente absolutas: Edit(//tmp/**) - comienzan con // - Directorio de inicio: Read(~/.zshrc)

Las reglas de permiso dir/** de un solo segmento ahora solo coinciden con <cwd>/dir (v2.1.214); audita tus reglas existentes. Antes de la v2.1.214, una regla de permiso como Edit(src/**) aprobaba automáticamente las escrituras en cualquier directorio llamado src situado en cualquier parte del árbol: vendor/src/, packages/foo/src/, todos ellos. Ahora solo coincide con el directorio src ubicado directamente bajo el directorio de trabajo. Si dependías del comportamiento anterior de coincidencia a cualquier profundidad, reescribe la regla como Edit(**/src/**). Las reglas deny y ask conservan la coincidencia a cualquier profundidad: el cambio restringe lo que se aprueba automáticamente, nunca lo que se bloquea. Una regla que dejó de coincidir silenciosamente se manifiesta como nuevas solicitudes de permisos después de actualizar, no como un error; por lo tanto, revisa todas las reglas de permiso escritas con el formato de un solo segmento. Las condiciones if: de los hooks recibieron el mismo alcance basado en el directorio de trabajo en esta versión (consulta Coincidencias).¹⁹⁰

Usa Edit(path)/Read(path), no Write(path)/NotebookEdit(path)/Glob(path) (v2.1.210). Claude Code ahora muestra una advertencia al iniciar cuando encuentra reglas de permisos escritas para Write(path), NotebookEdit(path) o Glob(path). Las formas canónicas son las 2 familias de reglas que realmente controlan el acceso a archivos: Edit(path) abarca todas las herramientas que escriben archivos (incluidas Write y NotebookEdit), mientras que Read(path) abarca las herramientas que leen archivos (incluida Glob). Migra las reglas heredadas para eliminar la advertencia y mantener explícita su intención.¹⁸⁷

“Always allow” guarda las reglas en la raíz del repositorio (v2.1.211). Las reglas de permisos creadas mediante la opción “Always allow” de la solicitud de confirmación ahora se escriben en la raíz del repositorio en lugar del worktree actual. De este modo, una aprobación concedida en un worktree se conserva entre sesiones y en todos los worktrees de ese repositorio, sin necesidad de volver a aprobar el mismo comando en cada checkout paralelo.¹⁸⁸

Patrones de herramientas de 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 comodines resulta útil para habilitar rápidamente todas las herramientas de servidores de confianza o bloquear servidores completos procedentes de fuentes no confiables.

Desde la v2.1.166, las reglas de denegación también aceptan un glob en la posición del nombre de la herramienta: un "*" independiente en ese lugar deniega todas las herramientas, lo que permite bloquearlas por completo y después volver a permitir un conjunto limitado. En cambio, las reglas de permiso rechazan los globs que no pertenezcan a MCP; no puedes permitirlo todo de manera general del mismo modo, lo que mantiene una postura restrictiva de forma predeterminada.²⁰⁶

Coincidencia a nivel de parámetros: Tool(param:value) (v2.1.178):

Además del nombre de la herramienta, una regla puede buscar coincidencias en sus parámetros de entrada, usando * como comodín en el valor:

{
  "deny": [
    "Agent(model:opus)"
  ]
}

Agent(model:opus) bloquea cualquier subagent iniciado en el nivel Opus: se deniega la propia creación, no se limita a pedir en el prompt que se evite. Esto amplía el control de permisos desde «qué herramienta» hasta «cómo se invoca», mediante una regla determinista en lugar de una solicitud incluida en el prompt. Se complementa con la configuración administrada enforceAvailableModels: la lista de permitidos define qué niveles de modelos existen durante la sesión y las reglas Tool(model:...) restringen cómo los utilizan los subagents.¹⁷³

Desde la v2.1.186, estas reglas Agent(...) también se aplican a la creación de subagents con nombre: las reglas de denegación Agent(agent_type) y las restricciones de tipos permitidos Agent(x,y) ahora se aplican cuando se inicia un agente específico con nombre (mediante un workflow, --agents o un equipo de agentes), no solo al crear agentes anónimos al estilo Task. La creación se bloquea al iniciarse, lo que cierra una brecha por la que un agente con nombre podía eludir una regla destinada a restringirlo.¹⁷⁵

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 fundamentales para los monorepos o cuando Claude necesita consultar código en directorios adyacentes.

Modo sandbox

Habilita el aislamiento del sistema de archivos y de la red:

> /sandbox

O configúralo en los ajustes:

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

Desde la v2.1.187, la configuración sandbox.credentials impide que los comandos ejecutados en el sandbox lean archivos de credenciales y variables de entorno secretas, lo que proporciona defensa en profundidad frente a comandos confinados que intenten extraer secretos.¹⁷⁶

Desde la v2.1.221, los archivos de credenciales cuentan con un tercer modo además de permitir y denegar: mode: "mask" (Linux y WSL). Cuando un comando del sandbox lee el archivo, recibe una copia con valores centinela —ya sea de todo el archivo o solo de los fragmentos capturados mediante una expresión regular extract—, y el proxy del sandbox sustituye esos valores por los reales al salir. El comando funciona (puede autenticarse a través del proxy) sin que el secreto esté presente en ningún momento en su entorno, precisamente la propiedad que buscas cuando un comando afectado por una inyección de prompt intenta encontrar tokens. En macOS, donde el mecanismo de sustitución del proxy no está disponible, mask recurre a deny; así, una configuración escrita para CI en Linux reduce sus privilegios de forma segura en vez de exponer silenciosamente el archivo.¹⁹⁹

La v2.1.224 extiende el enmascaramiento más allá del contenido estático de los archivos. extract y onExtractNoMatch gestionan valores de entorno estructurados; decode: "jwt" con maskClaims oculta campos específicos dentro de un JWT en lugar del token completo, por lo que un comando aún puede leer los metadatos de enrutamiento del token mientras los campos confidenciales permanecen sustituidos por valores centinela; además, awsPairs/sigv4 vuelve a firmar las solicitudes AWS SigV4 en el proxy, lo que permite usar el enmascaramiento con las CLIs de AWS, ya que una clave enmascarada no superaría la verificación de firma. Todas estas funciones requieren network.tlsTerminate y solo se respetan cuando proceden de ámbitos de usuario, administrados o --settings; un repositorio no puede incluir una configuración de enmascaramiento que redirija silenciosamente tus credenciales.²⁰¹

Desde la v2.1.216, la configuración sandbox.filesystem.disabled omite el aislamiento del sistema de archivos, pero conserva el control del tráfico saliente de la red. Es útil cuando la jaula del sistema de archivos impide que una herramienta de compilación funcione, pero aún quieres aplicar la lista de dominios permitidos al tráfico saliente.¹⁹²

Desde la v2.1.219, la configuración sandbox.network.strictAllowlist deniega por completo los hosts que no están en la lista de permitidos, sin solicitar confirmación. De forma predeterminada, cuando un comando del sandbox intenta comunicarse con un host que no figura en allowedDomains, se muestra una solicitud de permiso; con strictAllowlist activado, la conexión simplemente se rechaza. Esta es la configuración indicada para ejecuciones sin supervisión —CI, agentes en segundo plano y ciclos nocturnos—, donde una solicitud que nadie responde provoca un bloqueo y donde «preguntarme sobre tráfico saliente inesperado» tampoco es la política adecuada. Completa la tríada de red: allowedDomains establece qué está permitido, deniedDomains (más abajo) añade excepciones a una regla de permiso amplia y strictAllowlist determina si todo lo demás pregunta o falla.¹⁹⁶

Cuando se ejecuta en el sandbox: - El acceso al sistema de archivos se restringe al directorio del proyecto - El acceso a la red está controlado - Ciertos comandos quedan excluidos de las restricciones del sandbox - Los comandos Bash se permiten automáticamente si autoAllowBashIfSandboxed es true

Consejo experto: El modo sandbox es excelente para ejecutar Claude en códigos base que no sean de confianza. Actívalo cuando explores proyectos desconocidos o quieras una capa adicional de protección. Las pruebas internas de Anthropic determinaron que el sandbox reduce las solicitudes de permisos en un 84 %.³⁸ El sandbox utiliza mecanismos del sistema operativo (seatbelt de macOS y bubblewrap de Linux) para aislar el sistema de archivos y la red, por lo que incluso una inyección de prompt exitosa queda totalmente contenida. Anthropic publicó como código abierto el entorno de ejecución del sandbox para los equipos que crean sus propios agentes.⁸²

Notas de seguridad (v2.1.34+): Anteriormente, los comandos excluidos del sandbox mediante sandbox.excludedCommands o dangerouslyDisableSandbox podían eludir la regla de solicitud de permisos de Bash cuando autoAllowBashIfSandboxed estaba habilitado; esto se corrigió en la v2.1.34.⁸⁷ Desde la v2.1.38, las escrituras en .claude/skills se bloquean en el modo sandbox, lo que evita que una inyección de prompt modifique las definiciones de skills.⁸⁸ La v2.1.77 añade la configuración allowRead al sistema de archivos del sandbox para volver a permitir el acceso de lectura dentro de regiones denyRead; resulta útil cuando quieres bloquear la mayor parte del árbol de un directorio, pero incluir subdirectorios específicos en la lista de permitidos.¹¹⁹

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

Resolución de directorios .claude/ anidados (v2.1.178): Las skills de directorios .claude/skills anidados ahora se cargan automáticamente cuando trabajas con archivos ubicados bajo ese directorio, no solo desde la raíz del repositorio. Si hay nombres duplicados, puedes acceder a la skill anidada como <dir>:<name>, por lo que ambas siguen disponibles. El resto de la superficie del proyecto se resuelve de la misma manera: cuando el nombre de un agente, workflow o estilo de salida coincide entre varios directorios .claude/ anidados, prevalece el más cercano al directorio de trabajo, mientras que un workflow guardado en el ámbito del proyecto se dirige al directorio .claude/workflows/ existente más cercano. En un monorepo o repositorio de repositorios, esto proporciona herramientas específicas para cada paquete que se activan en contexto, en vez de una única superficie global plana.¹⁷³

Rutas personalizadas de bubblewrap y socat (v2.1.133+): Las configuraciones administradas sandbox.bwrapPath y sandbox.socatPath permiten a los administradores dirigir las implementaciones de Linux/WSL a ubicaciones no estándar de los binarios bubblewrap y socat. Resulta útil cuando las distribuciones instalan estas herramientas fuera de $PATH o cuando la organización distribuye compilaciones reforzadas propias.¹⁶⁰

Refuerzo de seguridad en la v2.1.113:¹⁵⁰

• sandbox.network.deniedDomains bloquea hosts específicos incluso cuando un comodín más amplio de allowedDomains los permitiría. Usa la lista de bloqueo para impedir el acceso a pastebins, servicios de intercambio de archivos o hosts maliciosos conocidos sin tener que reescribir toda tu política de permisos. Combínala con sandbox.network.strictAllowlist (v2.1.219, mencionada anteriormente) cuando quieras que todo lo que quede fuera de la lista de permitidos se rechace silenciosamente en lugar de solicitar confirmación.
• Reglas de denegación para comandos envoltorio. Ahora las reglas de denegación de Bash coinciden con comandos envueltos en env, sudo, watch, ionice, setsid y otros envoltorios de ejecución similares. Las reglas como Bash(rm:*) ahora detectan env rm -rf, sudo rm -rf y patrones de evasión relacionados.
• Las reglas de permiso Bash(find:*) ya no aprueban automáticamente find -exec ni find -delete. Estas opciones ejecutan comandos y eliminan archivos, por lo que Claude Code las dirige por el flujo normal de permisos.
• Protección contra eliminaciones en macOS. Las reglas de permiso Bash(rm:*) ahora consideran /private/etc, /private/var, /private/tmp y /private/home destinos de eliminación peligrosos. /var, /etc y /tmp son enlaces simbólicos que apuntan a /private/, por lo que la estructura anterior de las reglas no detectaba los destinos canónicos.

Refuerzo de permisos con denegación segura en la v2.1.214:¹⁹⁰

En una sola versión se cerró un conjunto de brechas en la comprobación de permisos, siempre bajo el principio de denegación segura: cuando el analizador no puede estar seguro, solicita confirmación.

• Se corrigió la evasión mediante Windows PowerShell 5.1. Anteriormente, los comandos ejecutados en sesiones de PowerShell 5.1 podían eludir la comprobación de permisos.
• Las redirecciones de descriptores de archivos de Bash aplican la denegación segura. Las formas de redirección que bash interpreta de manera diferente al analizador de permisos ahora solicitan confirmación en vez de ejecutarse.
• Los comandos de más de 10.000 caracteres siempre solicitan confirmación. Antes, los comandos muy largos podían evaluarse incorrectamente; ahora nunca se ejecutan de forma automática.
• Los subíndices y modificadores de zsh dentro de [[ ]] solicitan confirmación. Los subíndices y modificadores de variables dentro de comparaciones [[ ]] se trataban como texto inerte; como pueden ejecutar código, ahora requieren aprobación.
• Las variantes inseguras de help/man ya no se aprueban automáticamente. Ciertas invocaciones podían ejecutar opciones no seguras, sustituciones de comandos o rutas con barras invertidas bajo la apariencia de consultar documentación.
• Orden de las solicitudes en sesiones remotas. Las solicitudes de permisos de las sesiones remotas ya no pueden continuar antes que el cuadro de diálogo de confirmación local.
• Las opciones de docker que redirigen al daemon solicitan confirmación. Los comandos docker —incluido el shim docker de Podman— que contienen --url, --connection, --identity o el modo remoto de Podman antes se ejecutaban sin solicitar confirmación; esas opciones dirigen el comando a un daemon completamente diferente.
• file pierde su acceso libre de solo lectura cuando se le indica dónde escribir. file -m/--magic-file y -f/--files-from ahora requieren permiso en vez de aprobarse automáticamente como operaciones de solo lectura.

¿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, los hooks garantizan su ejecución independientemente del 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 abarca hooks de comando, prompt y agente.

Por qué usar 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, siempre, sin excepciones. Para el cumplimiento normativo, la seguridad y los estándares del equipo, lo determinista supera a lo probabilístico.⁴

Eventos disponibles

Valores de source de SessionStart. La entrada del hook SessionStart incluye un campo source que indica cómo comenzó la sesión: "startup", "resume", "clear" o "compact". A partir de v2.1.214, una sesión que comienza como una bifurcación informa source: "fork" en lugar de "resume": la contraparte del lado del hook al cambio de /fork a segundo plano de v2.1.212. Si un hook SessionStart se ramifica según source (por ejemplo, para volver a inyectar contexto solo con "resume"), actualiza su lista de coincidencias para incluir también "fork".¹⁹⁰

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": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Usa | para hacer coincidir varias herramientas (Edit|Write). A partir de v2.1.191, los matchers separados por comas (por ejemplo, Bash,PowerShell) también se activan correctamente; las versiones anteriores los descartaban silenciosamente, por lo que un hook con un matcher que contenía una coma nunca se ejecutaba.¹⁷⁸ A partir de v2.1.195, los matchers con identificadores que contienen guiones (por ejemplo, code-reviewer, mcp__brave-search) realizan una coincidencia exacta en lugar de coincidir accidentalmente con una subcadena. De este modo, un matcher ya no se activa con herramientas no deseadas que simplemente contienen esa cadena. Para hacer coincidir todas las herramientas de un servidor MCP cuyo identificador contiene guiones, usa un patrón explícito como mcp__brave-search__.*.¹⁷⁹

A partir de v2.1.214, las condiciones de ruta if: de los hooks se limitan al cwd. El mismo cambio de alcance de un solo segmento que afectó las reglas de permisos allow (consulta Sintaxis de las reglas de permisos) se aplica a las condiciones if: de los hooks: una condición como dir/** ahora solo coincide con <cwd>/dir, no con todos los directorios dir/ del árbol. Escribe **/dir/** cuando quieras recuperar la coincidencia a cualquier profundidad.¹⁹⁰

Protocolo de entrada y salida de hooks

Los hooks reciben JSON mediante stdin:

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

Datos adicionales en 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 subagent o una sesión --agent, además de un campo worktree en los comandos del hook de la línea de estado.¹¹⁰

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

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

Comentarios no bloqueantes (v2.1.163+): Los hooks Stop y SubagentStop pueden devolver hookSpecificOutput.additionalContext en su salida JSON para proporcionar comentarios a Claude y mantener el turno en curso, sin que la respuesta se etiquete como un error del hook. Antes, la única herramienta real de un hook Stop era el bloqueo con salida 2 (que aparece como un error y cuenta para el límite de bloqueos consecutivos); additionalContext agrega un canal de orientación para indicaciones del tipo «esto es lo que te faltó, continúa», sin interferir con el ciclo.²⁰⁷

Los códigos de salida controlan el comportamiento: - 0: Éxito: la operación continúa. Stdout se muestra en el modo detallado (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 el modo detallado.

Para tener un control avanzado, los hooks pueden generar JSON:

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

Control de decisiones de PreToolUse (formato recomendado): Los hooks PreToolUse usan hookSpecificOutput para ofrecer un control más completo: tres resultados (allow/deny/ask), además de la posibilidad 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 obsoletos para PreToolUse. Usa hookSpecificOutput.permissionDecision y hookSpecificOutput.permissionDecisionReason en su lugar. Los demás eventos (PostToolUse, Stop, etc.) siguen usando decision en el nivel superior.⁸⁹

Título de sesión de UserPromptSubmit (v2.1.94+): Los hooks UserPromptSubmit pueden establecer el título de la sesión mediante 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, correo electrónico, Pushover) que no deberían ralentizar la sesión - Registro y telemetría que pueden ejecutarse en segundo plano - Procesamiento posterior no esencial (analítica, copias de seguridad)

Cuándo NO usar hooks asíncronos: - Formateo (debe finalizar antes de la siguiente edición) - Validación (debe bloquear en caso de fallo) - Cualquier hook que necesite modificar la entrada o salida de una herramienta

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

Además de los hooks de comandos de shell (type: "command"), Claude Code admite 2 tipos de hooks basados en LLM que evalúan condiciones mediante razonamiento de IA en lugar de scripts.⁸⁹

Los hooks de prompt (type: "prompt") envían un prompt de un solo turno a un modelo rápido de Claude. El modelo devuelve { "ok": true } para permitir la acción o { "ok": false, "reason": "..." } para bloquearla:

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

Los hooks HTTP (type: "http") envían la entrada JSON del evento como una solicitud POST a una URL y reciben JSON como respuesta. Úsalos para webhooks, servicios externos de notificaciones o validaciones basadas 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 (devuelven JSON con decision y reason). Cuando el aislamiento está habilitado, se enrutan a través del proxy de red del sandbox. No son compatibles con los eventos SessionStart/Setup.

Los hooks de agente (type: "agent") crean un subagent con acceso a herramientas (Read, Grep, Glob) para realizar verificaciones de varios turnos. Úsalos cuando una comprobación requiera inspeccionar archivos reales o resultados 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 marcador de posición para la entrada JSON del hook. Ambos tipos admiten los campos model (cuyo valor predeterminado es un modelo rápido) y timeout. Eventos compatibles: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle no admite hooks de prompt/agente.

Hooks de herramientas MCP (v2.1.118+)

Ahora los hooks pueden invocar directamente una herramienta MCP mediante type: "mcp_tool", sin necesidad de envolverla en un subproceso 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 funciona bien con los servidores MCP que los usuarios ya tienen configurados: cualquier herramienta accesible desde /mcp puede invocarse mediante un hook.

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 sin contar las solicitudes de permisos ni los hooks PreToolUse.¹⁵² Resulta útil para detectar herramientas lentas, crear registros de auditoría y obtener 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 v2.1.118, los hooks de herramientas MCP incorporaron la capacidad de reemplazar la salida de una herramienta mediante hookSpecificOutput.updatedToolOutput. A partir de v2.1.121, el mismo campo funciona con cualquier hook PostToolUse: herramientas integradas (Bash, Read, Edit, Glob, Grep, etc.), herramientas de subagents y herramientas MCP. Casos de uso: ocultar contenido confidencial de la salida de cualquier herramienta, normalizar su estructura para consumidores posteriores e inyectar metadatos antes de que el agente lea el resultado.¹⁵⁴

Variables de entorno de los hooks

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

Conservar 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 los hooks HTTP (v2.1.51+): Los hooks HTTP que interpolan variables de entorno en los encabezados ahora requieren una lista explícita allowedEnvVars. Esto evita la filtración de variables de entorno arbitrarias mediante los valores de los encabezados. Los hooks HTTP también se enrutan a través del proxy de red del sandbox cuando el aislamiento está habilitado, lo que aplica la lista de dominios permitidos. Los hooks HTTP no son compatibles con 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 en el espacio de trabajo para hooks (v2.1.51+): Los comandos de hooks statusLine y fileSuggestion ahora requieren que se acepte la confianza en el espacio de trabajo antes de ejecutarse en modo interactivo, lo que elimina un posible vector de seguridad.⁹⁸

Ejemplos prácticos de hooks

Formatear automáticamente los archivos TypeScript después de editarlos:

{
  "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"
          }
        ]
      }
    ]
  }
}