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 206 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 de 60 segundos

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

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

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

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

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

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

Requisitos previos: Node 18+ solo para la ruta heredada de npm; el instalador nativo recomendado no depende de Node. macOS / Linux / Windows 10+ son compatibles. Una suscripción Claude Pro, Max, Team o Enterprise, o una clave Anthropic API de pago por token, cubre el uso. Consulta ¿Cómo instalo Claude Code? para ver detalles por plataforma, solución de problemas y la ruta del binario nativo (predeterminada desde v2.1.113). La evidencia de la versión más reciente en esta guía se verificó contra v2.1.154.²⁰⁶

Cómo funciona Claude Code: el modelo mental

Antes de profundizar en las funciones, entiende 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 principal: Tu conversación principal. Cada mensaje, lectura de archivo y salida de herramienta consume contexto de una ventana compartida (200K tokens estándar⁹¹, 1M tokens con Opus 4.6 o modelos de contexto extendido). Cuando el contexto se llena, Claude pierde el hilo de decisiones anteriores y la calidad se degrada. Esta capa cuesta dinero por token.

Capa de delegación: Los subagents se inician con contextos limpios, hacen trabajo enfocado y devuelven resúmenes. Los resultados de exploración no inflan tu conversación principal; solo regresan las conclusiones. Dirige los subagents a niveles de modelo más baratos para exploración, o usa tu modelo principal en todo el flujo 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 sin depender del comportamiento del modelo. Las skills codifican experiencia de dominio que Claude aplica automáticamente. Los plugins empaquetan todo esto para su distribución.

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

Tabla de contenidos

1. ¿Cómo instalo Claude Code?
2. Inicio rápido: tu primera sesión
3. Modos principales de interacción
4. Análisis profundo del sistema de configuración
5. ¿Qué modelo debería elegir?
6. ¿Cuánto cuesta Claude Code?
7. Marcos de decisión
8. ¿Cómo funciona el sistema de permisos?
9. ¿Cómo funcionan los hooks?
10. ¿Qué es MCP (Model Context Protocol)?
11. ¿Qué son los subagents?
12. ¿Qué es el modo Extended Thinking?
13. Estilos de salida
14. Slash Commands
15. ¿Cómo funcionan las skills?
16. Sistema de plugins
17. ¿Cómo funciona la memoria?
18. Entrada de imagen y multimodal
19. Modo de voz
20. ¿Cómo funciona la integración con Git?
21. ¿Cómo uso Claude Code en mi IDE?
22. Patrones de uso avanzado
23. Agentes remotos y en segundo plano [RESEARCH PREVIEW]
24. Claude en Chrome
25. Claude Code en Slack [RESEARCH PREVIEW]
26. Claude Code en la Web [RESEARCH PREVIEW]
27. Optimización del rendimiento
28. ¿Cómo depuro problemas?
29. Implementación empresarial
30. Referencia de atajos de teclado
31. Mejores prácticas
32. Recetas de workflow
33. Guía de migración
34. Guía por audiencia
35. Tarjeta de referencia rápida
36. Changelog
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 principales de interacción

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 consultas directamente, recibe respuestas y continúa hasta salir con /exit o Ctrl+D.

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

claude "explain the authentication flow in this project"

Consejo experto: El REPL conserva el estado durante los eventos de compactación. Cuando el contexto crece demasiado, Claude resume automáticamente la conversación anterior y conserva 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 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 una 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 stream-json solo contiene los eventos de la sesión principal; el trabajo realizado dentro de los subagents aparece como un resumen. La opción --forward-subagent-text (o CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1) también reenvía al flujo el texto y el razonamiento de los subagents, por lo que los sistemas de ejecución y los canales de registro pueden observar el trabajo delegado a medida que ocurre, en lugar de ver únicamente el informe final.¹⁸⁸

Los subagents anidados ahora también se reenvían (v2.1.219). Originalmente, solo aparecían los subagents de profundidad 1. Los subagents generados en la profundidad 2 y posteriores ahora también aparecen en el flujo reenviado, cada uno identificado mediante el id de tool_use de la llamada a Agent que lo generó. Así, un canal de procesamiento puede reconstruir el árbol de delegación en lugar de ver una lista plana de texto. Esto se complementa directamente con el restablecimiento, en la misma versión, de la generación anidada hasta una profundidad predeterminada de 3: sin este cambio, 2 de los 3 niveles habrían permanecido 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 la conversación para poder continuarla. Esta persistencia es esencial para el trabajo complejo que abarca 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+, ampliadas en v2.1.119+): Inicia una sesión vinculada a una solicitud de extracción o fusión específica. Desde la versión v2.1.119, --from-pr acepta URLs de MR de GitLab, PR de Bitbucket y PR de GitHub Enterprise, además de github.com:⁷⁴¹⁵²

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

Las sesiones también se vinculan automáticamente a 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 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 URLs de PR (v2.1.122+). Al pegar una URL de 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 de GitLab con alojamiento propio) y bitbucket.org.¹⁵⁴

Sesiones con nombre: Asigna nombres a las sesiones al iniciarlas o durante su ejecució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 a las sesiones nombres legibles para las personas, utiliza /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 tu sesión principal. El comportamiento anterior —bifurcar dentro de la sesión actual— se mantiene 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 era "resume"), lo que permite que los hooks que comparan el origen distingan 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.¹⁹²

Claude Code almacena las sesiones como transcripciones JSONL. La ejecución de agentes asigna valores agentId únicos y guarda 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 a Claude a una 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 planificación 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 mediante 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 el plan, solicitas cambios o lo rechazas

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 3 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 pedir aprobación para cada edición

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

Cuándo utilizar el modo de planificación: - Implementaciones de funciones nuevas que requieren decisiones de arquitectura - Refactorizaciones de varios archivos en las que quieres revisar primero el enfoque - Código fuente que no conoces y que conviene explorar antes de modificar - Cualquier tarea con varios enfoques válidos sobre los que quieras opinar

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

Modo de lector de pantalla (v2.1.208)

Claude Code incluye un modo específico para lectores de pantalla que adapta la interfaz de la terminal a las tecnologías de asistencia. Puedes activarlo de 3 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 profundo del sistema de configuración

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

Jerarquía de configuración

Consejo experto: 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 establece cualquier opción de configuración directamente desde el prompt —por ejemplo, /config thinking=false— sin abrir la interfaz interactiva de /config, y funciona en sesiones interactivas, -p y 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 y 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 biblioteca extensa de skills, pero quiere limitar más su exposición durante la ejecución. Usa off para ocultar una skill tanto del modelo como del selector de slash commands, user-invocable-only para que pueda seguir invocándose por su nombre, pero quede fuera de la selección del modelo, y name-only para que solo sea visible 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 restringe el modelo Default: si Default se resolviera como un modelo no permitido, se utilizaría el primer modelo permitido; además, la configuración del usuario o del proyecto ya no puede ampliar una lista availableModels administrada. Una corrección complementaria (v2.1.176) cierra la brecha que permitía que la selección de un alias redirigiera a un modelo bloqueado mediante ANTHROPIC_DEFAULT_*_MODEL, y /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 imponer restricciones de modelos directamente en el selector de /model, --model, /model y ANTHROPIC_MODEL; al seleccionar un modelo restringido, aparece el mensaje «restringido por la configuración de tu organización».¹⁷⁶
• language (mejora de v2.1.176): además de establecer el idioma de las respuestas, 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): establécelo en 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): activa de forma persistente el modo de lector de pantalla (consulta Modo de lector de pantalla).¹⁸⁶
• processWrapper (v2.1.208): canaliza mediante un ejecutable contenedor todos los procesos que Claude Code inicia para sí mismo; está diseñado para lanzadores corporativos (consulta Lanzador corporativo).¹⁸⁶
• Restricción de 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 cierra una vía por la que un repositorio clonado podía incluir una configuración de 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 ver sugerencias. Está activado de forma predeterminada; establécelo en false para desactivarlo.¹⁹⁴

Configuraciones más recientes (v2.1.219):

• sandbox.network.strictAllowlist (v2.1.219): rechaza los hosts que no estén en la lista de permitidos para los comandos en sandbox sin solicitar confirmación, en lugar de mostrar un diálogo de permisos. Consulta Modo sandbox.¹⁹⁶
• workflowSizeGuideline (v2.1.219): establece la recomendación orientativa sobre el tamaño de los flujos de trabajo Dynamic desde cualquier archivo de configuración —del usuario, del proyecto o administrado—, en lugar de hacerlo únicamente mediante /config. De forma predeterminada, los flujos de trabajo Dynamic utilizan una recomendación media («procura usar menos de 15 agentes»); la fila de /config se oculta mientras el valor se proporcione mediante un archivo de configuración. 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 de modelos:

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 de proveedores de 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; /clear resets the budget; v2.1.212+)[^206]
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               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_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 sensibles:²⁰⁷

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
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 por OTEL_LOG_USER_PROMPTS=1, ya que puede contener información de identificación personal (PII).¹⁵⁴

Cambios a nivel de evento 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 de texto); esto corrige los recopiladores de 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 de OTel, condicionado por 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 actualizar. Establece OTEL_LOG_ASSISTANT_RESPONSES=0 para que la telemetría continúe registrando únicamente los prompts.¹⁷⁹

Adiciones de telemetría en v2.1.214: los eventos de registro de OTel ahora incluyen los atributos message.uuid, client_request_id y tool_source para correlacionar los mensajes y determinar la procedencia de las herramientas; la carga útil de subagentStatusLine incluye el esfuerzo de razonamiento del subagent, de modo 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 de OTel.¹⁹⁰

Control de API / modelos:²⁰⁷

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 debería elegir?

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

Modelos disponibles

Dos cambios incompatibles que debes tener en cuenta al migrar un harness de Opus 4.8 a Opus 5:¹⁹⁷

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

En Claude Code específicamente: el valor predeterminado de effort es 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 nivel de esfuerzo max cuando la capacidad sea más importante 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 resultados 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 para consultas sobre ciberseguridad, bioquímica y destilación de modelos (Claude Mythos 5 es el mismo modelo sin esas medidas de protección para investigadores autorizados). Se incorporó como opción seleccionable en Claude Code con la versión v2.1.170 (9 de junio de 2026): ejecuta claude update y después /model fable (el alias corto; /model claude-fable-5 y el alias best también lo seleccionan). Su implementación progresiva en los planes de suscripción continuará 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 versión v2.1.173 (11 de junio de 2026), el nombre de modelo claude-fable-5[1m] se normaliza automáticamente eliminando el sufijo (que solo ha tenido relevancia en Opus/Sonnet, donde el acceso a 1M requiere [1m]); salida máxima 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 tareas de razonamiento realmente difíciles, no para modificaciones rutinarias. Comparte la interfaz de solicitudes de Opus 4.8 (solo razonamiento adaptativo; se eliminaron temperature/top_p/top_k y budget_tokens), pero añade una particularidad: especificar thinking: {type: "disabled"} devuelve un error 400, por lo que debes omitir por completo el parámetro thinking para ejecutarlo sin razonamiento.²⁰⁰

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 razonamiento no se puede desactivar en Fable 5: ni el selector de razonamiento de la sesión, ni la configuración alwaysThinkingEnabled, ni MAX_THINKING_TOKENS=0 tienen efecto; siempre utiliza razonamiento adaptativo. Una interfaz de configuración completa para la familia fable replica las opciones de Opus: ANTHROPIC_DEFAULT_FABLE_MODEL fija el modelo al que apunta el alias fable (útil en Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE excluye a Fable del almacenamiento en caché de prompts y la conmutación automática según el contenido se aplica en las puertas de enlace empresariales. /model opus ahora selecciona Opus 5 (con esfuerzo alto de forma predeterminada y /effort xhigh para las tareas más difíciles), mientras que Sonnet 5 es el modelo predeterminado inicial desde la versión v2.1.197; selecciona Fable 5 de manera deliberada mediante /model fable cuando necesites la máxima capacidad posible.²⁰⁰¹⁹⁷

Opus 4.7 (16 de abril de 2026): El modelo insignia de la generación anterior, que continúa plenamente disponible. Ventana de contexto de 1M de tokens con precio estándar, sin recargo por contexto largo. Salida máxima de 128K, solo razonamiento adaptativo (se eliminó el razonamiento 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 confiable: 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 $6.25 por MTok para escritura en caché durante 5 minutos, $10 para escritura en caché durante 1 hora y $0.50 para lectura de caché.¹⁴⁴ 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: espera aproximadamente entre 1 y 1,35 veces la cantidad de tokens para el mismo texto; aumenta el margen de max_tokens y los umbrales de compactación.¹⁴⁵ La función de 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 según el plan (Claude Code):¹⁴⁷

Cambios incompatibles de Opus 4.7 en la API Messages (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 al 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 visible (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 20K tokens.¹⁴⁵

Opus 4.6 (anterior): Sigue disponible como claude-opus-4-6, con un contexto de 1M y una salida máxima de 128K. 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.⁷⁹¹⁴⁴ Desde la versión 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 permanece en xhigh. Este cambio recuperó la inteligencia 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): El nivel Sonnet actual, presentado como «la mejor combinación de velocidad e inteligencia». Anthropic afirma que su rendimiento es cercano al de Opus 4.8, pero a precios más bajos, y que supone una mejora considerable respecto de Sonnet 4.6 en razonamiento agéntico, uso de herramientas, programación y trabajo intelectual, a la vez que presenta una tasa general más baja de comportamientos no deseados y una capacidad de ciberseguridad mucho menor que los modelos Opus (la concesión en materia de seguridad que permitió lanzarlo sin restricciones de control de exportaciones). ID del modelo: claude-sonnet-5 (instantánea fijada sin fecha). Ventana de contexto de 1M tokens, salida máxima de 128K (hasta 300K en Batches API con el encabezado beta output-300k-2026-03-24), únicamente pensamiento adaptativo. Fecha de corte de conocimiento confiable: enero de 2026. Precio: $3/$15 por MTok 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 usa high de forma predeterminada en Sonnet 5 (configúralo explícitamente para cambiarlo). Selecciónalo con /model sonnet (o /model claude-sonnet-5).¹⁸⁰ Desde la versión v2.1.197 (30 de junio de 2026), Sonnet 5 es el modelo predeterminado en Claude Code para las sesiones nuevas y reemplaza a 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 MTok). Mejoró el rendimiento de búsqueda agéntica y consume menos tokens. Admite pensamiento extendido, pensamiento adaptativo y una ventana de contexto de 1M tokens (beta). Salida máxima de 64K (límite superior de 128K en v2.1.77).¹¹⁹ Fecha de corte del 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 bajo Project Glasswing.¹³⁹ Disponible solo por invitación; no tiene disponibilidad general. Anthropic presenta a Opus 4.7 como deliberadamente menos capaz que Mythos en aspectos de ciberseguridad —una concesión en materia de seguridad— y abrió un Cyber Verification Program en https://claude.com/form/cyber-use-case para investigadores legítimos de seguridad que necesitan acceso ampliado.¹⁴⁶

Por qué importan estas diferencias de precio: Una sesión típica de programación consume entre 50K y 200K tokens de entrada y entre 10K y 50K 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, cinco veces más. Reserva Opus para problemas realmente difíciles.¹

Cuándo usar cada modelo

Haiku: Úsalo para subagents que realizan exploraciones, búsquedas sencillas de archivos y preguntas rápidas. Es alrededor de cinco veces más económico que Opus y responde más rápido. Resulta perfecto para tareas en segundo plano que no requieren un razonamiento profundo.

Sonnet: La herramienta 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 en comparación con Sonnet 4.5, además de admitir pensamiento adaptativo y una ventana de contexto de 1M al precio estándar.⁹³ Desde el lanzamiento de Opus 4.7 (16 de abril de 2026), Claude Code usa 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 económicos, menor latencia o costos más convenientes para subagents.

Opus: El nivel insignia desde el 16 de abril de 2026 y la opción predeterminada en los planes Max y Team Premium.¹⁴⁴¹⁴⁷ Reserva su razonamiento más costoso para los casos en los que valga la pena: decisiones de arquitectura, depuración compleja, comprensión de sistemas complejos, análisis de seguridad y trabajo agéntico de largo alcance. Opus 4.7 resuelve tres veces más tareas de producción que Opus 4.6 en SWE-Bench, obtiene un 70 % en CursorBench (frente al 58 %) y aumenta un 13 % la resolución en una evaluación comparativa interna de programación con 93 tareas.¹⁴⁴ Claude Code usa de forma predeterminada el esfuerzo xhigh en Opus 4.7, que puedes ajustar mediante /effort (v2.1.111+).¹⁴⁶¹⁴⁷ Auto Mode está disponible para suscriptores Max en Opus 4.7 mediante la Anthropic API, sin requerir --enable-auto-mode; la disponibilidad para otros planes y proveedores depende del plan y de los controles del administrador.¹⁴⁶ Contexto de 1M al precio estándar, sin recargo por contexto largo. Cambios de comportamiento que conviene conocer: Opus 4.7 sigue las instrucciones de forma 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 validar al usuario. Si tus prompts incluyen estructuras para forzar mensajes provisionales de progreso o verificaciones dobles, prueba eliminarlas.¹⁴⁵

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 al nivel de Opus para cada modificación individual.

Cambiar de modelo

Durante una 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 de respaldo (v2.1.166+): la configuración fallbackModel permite definir hasta tres modelos de respaldo, 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 la API devuelve un error inesperado que no admite reintentos, Claude Code ahora también vuelve a intentar el turno una vez con el modelo de respaldo antes de mostrar el fallo, por lo que un problema transitorio del modelo principal se resuelve de forma gradual en lugar de interrumpir el turno.²⁰²

Desde la versión v2.1.178, la compactación también respeta la cadena de respaldo: si el modelo principal está sobrecargado o no está disponible durante la compactación, ese paso recurre a la cadena fallbackModel/--fallback-model configurada en lugar de interrumpir el turno. En una ejecución autónoma prolongada, esto cierra la brecha por la que una compactación recuperable podía perder 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 1M 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 1M tokens al precio estándar, sin recargo por contexto largo.¹⁴⁸ Una solicitud de 900K tokens se factura con la misma tarifa por token que una de 9K tokens. 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 1M 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 1M mediante el uso adicional. Los usuarios de API y de pago por consumo tienen acceso completo a 1M con las tarifas estándar por token.¹⁴⁷

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

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 legibles (p. ej., «Sonnet 4.6») en lugar de los identificadores sin procesar de los modelos para las versiones fijadas, además de sugerencias de actualización cuando hay versiones más recientes disponibles.⁹⁸ v2.1.219 corrige la fila combinada de Opus, que se mostraba 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 lo que realmente se lanzó en vez de una parte arbitraria de la lista.¹⁹⁶

Fast Mode (v2.1.36+)

Fast mode proporciona una salida considerablemente más rápida 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): fast mode se aplica a Claude Opus 5 y Claude Opus 4.8. v2.1.219 eliminó Opus 4.7 de fast mode, 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 Claude API (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 (fast mode de Opus 5 / Opus 4.8):¹⁹⁸

La trampa de Opus 4.7 (v2.1.219). No todos los modelos incompatibles se comportan igual. 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 según las tarifas estándar e informa usage.speed: "standard". Si tu entorno fijaba la versión 4.7 y dependía de que las solicitudes de fast mode pasaran discretamente al modo estándar, ahora fallarán por completo; cambia la versión fijada a Opus 5 o 4.8.¹⁹⁸

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

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

Fast mode incluye la ventana de contexto completa de 1M (v2.1.50+). El precio aplica un multiplicador fijo a todo el contexto, incluidas las solicitudes que superan los 200K tokens de entrada, sin recargos adicionales por contexto largo, y se acumula con los multiplicadores de almacenamiento en caché de prompts y residencia de datos.⁹⁶¹⁹⁸

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

Consejo experto: Fast mode no puede combinarse con opusplan (opusplan ya mezcla Opus y Sonnet; fast mode solo afecta la parte ejecutada por 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 tengan que 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 de fast mode, y v2.1.219 corrigió los clientes de Remote Control que conservaban un estado obsoleto de fast mode después de cambiar de modelo, volver a conectarse o no superar una comprobación de la organización.^86149195196

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

Opus 4.7 incorpora un nuevo control 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 reemplazo más seguro para --dangerously-skip-permissions, está disponible para los suscriptores de Max en Opus 4.7 mediante la Anthropic API sin --enable-auto-mode.¹⁴⁶ Un clasificador de 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ó el indicador --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 Anthropic API. Bedrock/Vertex/Foundry (v2.1.158+): Auto Mode pasó a ser opcional en Opus 4.7 y Opus 4.8 en esas puertas de enlace 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 mediante la configuración administrada disableAutoMode. La misma versión establece Claude Opus 4.8 como modelo predeterminado en Bedrock, Vertex AI y Claude Platform on AWS, y deja de leer la configuración autoMode del archivo .claude/settings.local.json de un repositorio; configura las reglas de Auto Mode en ~/.claude/settings.json.¹⁸⁵

Reglas personalizadas sin perder las predeterminadas (v2.1.118+). En versiones anteriores, autoMode.allow, autoMode.soft_deny y autoMode.environment eran mutuamente excluyentes: si definías tu propia lista, perdías las reglas de seguridad integradas. El marcador $defaults resuelve este problema: se expande en línea a la lista integrada exactamente en la posición donde lo coloques, lo que te permite añadir reglas personalizadas alrededor de las predeterminadas:¹⁵²

// .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 ofrece la opción «No volver a preguntar», para que los usuarios frecuentes puedan ocultar la explicación sin tener que automatizar un indicador.¹⁵²

Protecciones 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 hayas pedido descartar el trabajo local; git commit --amend cuando el agente no haya creado 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 radio de impacto del clasificador precisamente para las operaciones que pueden provocar la pérdida silenciosa de trabajo o eliminar entornos. El agente aún puede ejecutarlas, pero solo si se lo indicas explícitamente, no por iniciativa propia.¹⁷⁴

Clasificar todos los comandos de shell (v2.1.193). De forma predeterminada, el clasificador de Auto Mode solo revisa los comandos de shell que coinciden con patrones de ejecución arbitraria de código; los comandos rutinarios se omiten. La nueva configuración autoMode.classifyAllShell hace que todos los comandos de Bash/PowerShell pasen por el clasificador, lo que sacrifica un poco de velocidad a cambio de una protección más estricta cuando quieres que se examine cada llamada al shell. La misma versión también muestra los motivos de rechazo de Auto Mode en la transcripción, la notificación de rechazo y los rechazos recientes de /permissions, de modo que ahora un comando bloqueado explica por qué se bloqueó.¹⁷⁹ Tres reglas más de protección (v2.1.205). El modo auto ahora bloquea la manipulación de los archivos de transcripción de la sesión: el registro de auditoría queda fuera del alcance del agente; pide 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 provocados por rm -rf $DIR cuando $DIR es desconocido; y las notificaciones de tareas en segundo plano ahora indican explícitamente que no hubo intervención humana, de modo que una línea inventada como «el usuario aprobó» dentro de una transcripción no pueda hacerse pasar por una aprobación válida y ejecutarse.¹⁸³ La tercera es una defensa contra la inyección de prompts que conviene tener muy presente: la aprobación debe llegar a través del canal de aprobación, y ahora el entorno de ejecución 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 $(...), comillas invertidas o una sustitución de procesos (<(...)), y la solicitud aparece incluso con --dangerously-skip-permissions y en modo auto. Envolver un comando destructivo en una sustitución ya no permite eludir la red de seguridad.¹⁸⁶

Restablece el estado del modo auto: claude auto-mode reset (v2.1.212). Un nuevo subcomando permite restablecer el estado del modo auto 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 auto 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 auto las evalúa, por lo que la revisión de seguridad sigue realizándose sin involucrarte ante cada detección. La misma versión extiende este comportamiento al modo de planificación con auto: los comandos Bash que el analizador estático no puede demostrar que son de solo lectura ya no solicitan confirmación; 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», Claude puede enviar notificaciones push al dispositivo móvil según su propio criterio mediante una nueva herramienta de notificaciones push. Esta función se combina 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 Windows PowerShell (v2.1.111+, implementación gradual)

Claude Code está implementando gradualmente una herramienta nativa de Windows PowerShell. En Linux/macOS, habilítala con CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (requiere pwsh en PATH). En Windows, la misma variable controla la activación o desactivación voluntaria 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, al igual que los comandos Bash. Las reglas de permisos como PowerShell(Get-*:*) y la sintaxis de patrones existente ahora omiten la solicitud de confirmación para las operaciones de solo lectura, lo que ofrece la misma facilidad de uso que los equipos ya tienen en Linux/macOS.¹⁵²

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

Los patrones Bash de solo lectura con argumentos glob (por ejemplo, ls *.ts y 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, esto reduce considerablemente las interrupciones en los flujos de trabajo cotidianos.

Seguimiento distribuido (v2.1.110+)

Las sesiones de SDK y headless 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 destinados a la depuración.¹⁴⁶

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

v2.1.113 cambia la forma en que se inicia CLI: ahora claude inicia un binario nativo de Claude Code mediante una dependencia opcional específica para 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 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 durante una transmisión ahora fallan con un error claro después de 10 minutos, en lugar de quedar suspendidos silenciosamente. Combínalo con CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para obtener una cobertura más amplia de los procesos bloqueados durante la transmisión de APIs.

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 compañero de Agent Teams 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 proporciona un control detallado sobre las operaciones que pueden ejecutarse. Comprenderlo es esencial 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 por patrón - 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 proporciona 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 (normalmente se instala con tu conjunto de herramientas)

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

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

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 extremadamente 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 denomina “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, y ahora --permission-mode manual / "defaultMode": "manual" se aceptan como alias. El comportamiento es idéntico —solicitar aprobación la primera vez que se usa cada herramienta—; simplemente se dejó de mostrar una etiqueta que podía interpretarse como «el modo que se obtiene de manera predeterminada», cuando en realidad se trata del modo de aprobación manual. En la misma versión, los cuadros de diálogo de AskUserQuestion ya no continúan automáticamente de manera predeterminada; cuando un subagent hace una pregunta, ahora espera tu respuesta en lugar de continuar al agotarse el tiempo, y puedes volver a habilitar un tiempo de espera por inactividad mediante /config.

Ahora se solicita aprobación para los archivos de configuración que permiten 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 aprobación antes de escribir archivos que puedan permitir la ejecución silenciosa de comandos: archivos de inicio del shell (.zshenv, .zlogin, .bash_login), ~/.config/git/ y archivos de configuración 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 del shell, instalación o commit en un vector de ejecución; por eso se aplica una verificación deliberada, incluso en un modo para proyectos de confianza que normalmente deja pasar las ediciones. Este es el mismo modelo de amenazas que las protecciones existentes contra escrituras 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+): Un reemplazo más seguro para --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 dentro del directorio de trabajo se aprueban automáticamente - Las reglas personalizadas de autorización o 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

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

Interruptor de seguridad: 3 bloqueos consecutivos o 20 bloqueos totales en una sesión hacen que se vuelva a las solicitudes de aprobació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.¹²⁴

Modo YOLO (v2.0.68+): Para un funcionamiento totalmente 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 buscar coincidencias 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 de la URL. Para bloquearlo de manera confiable, 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 absolutas reales: Edit(//tmp/**) - comienzan con // - Directorio personal: Read(~/.zshrc)

Las reglas de autorización 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 autorización como Edit(src/**) aprobaba automáticamente las escrituras en cualquier directorio llamado src 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 en cualquier nivel de profundidad, reescribe la regla como Edit(**/src/**). Las reglas deny y ask conservan la coincidencia a cualquier profundidad: el cambio limita lo que se aprueba automáticamente, nunca lo que se bloquea. Cuando una regla deja de coincidir silenciosamente, aparecen nuevas solicitudes de permisos después de actualizar, no un error; por eso debes revisar todas las reglas de autorización escritas con el formato de un solo segmento. Las condiciones if: de los hooks recibieron el mismo alcance relativo al directorio de trabajo en esta versión (consulta Comparadores).¹⁹⁰

Usa Edit(path)/Read(path), no Write(path)/NotebookEdit(path)/Glob(path) (v2.1.210). Claude Code ahora muestra una advertencia al iniciarse si las reglas de permisos están 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 de escritura de archivos (incluidas Write y NotebookEdit), mientras que Read(path) abarca las herramientas de lectura de archivos (incluida Glob). Migra las reglas antiguas 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 aprobación ahora se escriben en la raíz del repositorio, en lugar del worktree actual. De este modo, una aprobación que concedas en un worktree se mantiene entre sesiones y en todos los worktrees de ese repositorio; ya no tendrás que 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 autorizar o denegar todas las herramientas de un servidor MCP específico.³² Esta sintaxis resulta útil para habilitar rápidamente todas las herramientas de servidores de confianza o bloquear servidores completos provenientes 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 "*" por sí solo en esa posición deniega todas las herramientas, lo que permite bloquearlo todo y luego volver a autorizar un conjunto reducido. En cambio, las reglas de autorización rechazan los globs ajenos a MCP; no puedes autorizar todo de forma general del mismo modo, lo que mantiene una postura predeterminada restrictiva.²⁰²

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 que se intente iniciar 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 petición en el prompt. Se complementa con la configuración administrada enforceAvailableModels: la lista de autorización define qué niveles de modelos existen durante la sesión, y las reglas Tool(model:...) limitan cómo los usan 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 flujo de trabajo, --agents o un equipo de agentes), no solo a las creaciones anónimas de tipo 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 esenciales para los monorepos o cuando Claude necesita consultar código en directorios del mismo nivel.

Sandbox Mode

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 aporta una defensa en profundidad contra la extracción de secretos por parte de un comando aislado.¹⁷⁶

Desde la v2.1.216, la configuración sandbox.filesystem.disabled omite el aislamiento del sistema de archivos, pero mantiene el control del tráfico saliente de la red; resulta útil cuando el entorno aislado del sistema de archivos interfiere con una herramienta de compilación, pero aun así quieres aplicar la lista de dominios autorizados al tráfico saliente.¹⁹²

Desde la v2.1.219, la configuración sandbox.network.strictAllowlist deniega de inmediato los hosts que no estén en la lista de autorización, sin solicitar aprobación. De manera predeterminada, cuando un comando ejecutado en el sandbox intenta comunicarse con un host que no figura en allowedDomains, se muestra una solicitud de permisos; con strictAllowlist activado, la conexión simplemente se rechaza. Esta es la configuración indicada para ejecuciones desatendidas —CI, agentes en segundo plano y ciclos nocturnos—, en las que una solicitud que nadie responde paraliza el proceso y «pregúntame sobre cualquier tráfico saliente inesperado» no es una política adecuada. Completa la tríada de la red: allowedDomains indica qué está permitido, deniedDomains (más adelante) excluye excepciones de una autorización amplia y strictAllowlist determina si todo lo demás debe generar una solicitud o fallar.¹⁹⁶

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 - Determinados comandos quedan excluidos de las restricciones del sandbox - Los comandos Bash se autorizan automáticamente si autoAllowBashIfSandboxed es true

Consejo para expertos: Sandbox Mode es excelente para ejecutar Claude en código base que no sea de confianza. Habilítalo cuando explores proyectos desconocidos o quieras una capa adicional de protección. Las pruebas internas de Anthropic determinaron que el uso del sandbox reduce las solicitudes de permisos en un 84 %.³⁸ El sandbox utiliza primitivas 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 prompts exitosa queda totalmente contenida. Anthropic ha publicado el código fuente del entorno de ejecución del sandbox para los equipos que desarrollan sus propios agentes.⁸²

Notas de seguridad (v2.1.34+): Los comandos excluidos del sandbox mediante sandbox.excludedCommands o dangerouslyDisableSandbox podían eludir anteriormente 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 Sandbox Mode, lo que impide que una inyección de prompts modifique las definiciones de skills.⁸⁸ La v2.1.77 incorpora una configuración allowRead para el sistema de archivos del sandbox que permite volver a habilitar el acceso de lectura dentro de regiones denyRead; resulta útil cuando quieres bloquear la mayor parte de un árbol de directorios, pero incluir subdirectorios específicos en la lista de autorización.¹¹⁹

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

Resolución de .claude/ anidados (v2.1.178): Las skills ubicadas en directorios .claude/skills anidados ahora se cargan automáticamente cuando trabajas con archivos dentro de esos directorios, no solo desde la raíz del repositorio; si hay un conflicto de nombres, se puede acceder a la skill anidada como <dir>:<name>, de modo que ambas permanezcan disponibles. El resto de los elementos del proyecto se resuelve del mismo modo: cuando el nombre de un agente, flujo de trabajo o estilo de salida coincide entre directorios .claude/ anidados, prevalece el que esté más cerca del directorio de trabajo, y al guardar un flujo de trabajo con alcance de proyecto se usa el 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 según el contexto, en lugar de una única superficie global y plana.¹⁷³

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

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

• sandbox.network.deniedDomains bloquea hosts específicos, aunque un comodín más amplio en allowedDomains pudiera permitirlos. Usa la lista de bloqueo para impedir el acceso a pastebins, servicios de alojamiento de archivos o hosts maliciosos conocidos sin tener que reescribir toda tu política de autorización. Combínala con sandbox.network.strictAllowlist (v2.1.219, mencionada anteriormente) cuando quieras que todo lo ajeno a la lista de autorización se rechace silenciosamente en lugar de generar una solicitud.
• Reglas de denegación para comandos envolventes. Las reglas de denegación de Bash ahora coinciden con comandos envueltos en env, sudo, watch, ionice, setsid y otros envoltorios de ejecución similares. Reglas como Bash(rm:*) ahora detectan env rm -rf, sudo rm -rf y patrones de evasión relacionados.
• Las reglas de autorización Bash(find:*) ya no aprueban automáticamente find -exec ni find -delete. Esas opciones ejecutan comandos y eliminan archivos, por lo que Claude Code las dirige a través del proceso normal de permisos.
• Protección contra eliminaciones en macOS. Las reglas de autorización Bash(rm:*) ahora tratan /private/etc, /private/var, /private/tmp y /private/home como destinos de eliminación peligrosos. /var, /etc y /tmp son enlaces simbólicos hacia /private/, por lo que la forma anterior de la regla no detectaba los destinos canónicos.

Refuerzo de permisos con bloqueo seguro en la v2.1.214:¹⁹⁰

En una misma versión se cerró un conjunto de brechas en las comprobaciones de permisos, siempre en favor del bloqueo seguro: cuando el analizador no puede determinar con certeza si una operación es segura, solicita aprobació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 bloqueo seguro. Las formas de redirección que bash interpreta de manera diferente al analizador de permisos ahora solicitan aprobación en lugar de ejecutarse.
• Los comandos de más de 10.000 caracteres siempre solicitan aprobación. Anteriormente, los comandos muy largos podían evaluarse de forma incorrecta; ahora nunca se ejecutan automáticamente.
• Los subíndices y modificadores de zsh dentro de [[ ]] solicitan aprobació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. Algunas invocaciones podían ejecutar opciones inseguras, 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 en sesiones remotas ya no pueden continuar antes de que se responda el cuadro de confirmación local.
• Las opciones de redirección del daemon de docker solicitan aprobación. Los comandos de docker (incluido el shim docker de Podman) que contienen --url, --connection, --identity o el modo remoto de Podman antes se ejecutaban sin solicitar aprobación; esas opciones dirigen el comando a un daemon completamente distinto.
• file pierde su autorización automática de solo lectura cuando se le indica dónde escribir. file -m/--magic-file y -f/--files-from ahora requieren permisos en lugar 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"
          }
        ]
      }
    ]
  }
}

Bloquear el acceso a archivos confidenciales:

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

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