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

TL;DR: Claude Code es un CLI agéntico que lee tu base de código, ejecuta comandos y modifica archivos mediante un sistema por capas de permisos, hooks, integraciones MCP y subagents. Domina cinco sistemas centrales (configuración, permisos, hooks, MCP y subagents) y desbloquearás una productividad multiplicadora. Elige el nivel de modelo que se ajuste a cada tarea: Opus para razonamiento complejo, Sonnet para trabajo general, Haiku para exploración rápida, o estandariza en Opus si la calidad es tu única variable. Usa hooks (no prompts) para cualquier cosa que deba ejecutarse siempre. Desde v2.1.174–176 (12 de junio de 2026), la lista de permitidos availableModels ahora puede restringir el modelo Default mediante la nueva configuración administrada enforceAvailableModels (la configuración de usuario/proyecto no puede ampliar una lista administrada), los títulos de sesión se generan en el idioma de tu conversación (fija uno con la configuración language), y completan la versión las nuevas configuraciones footerLinksRegexes y wheelScrollAccelerationEnabled, un cuadro de diálogo de atribución de /usage en VSCode y una corrección que hace que las condiciones if de hooks coincidan con patrones de ruta de Read/Edit/Write.¹⁷² Desde v2.1.173 (11 de junio de 2026), un nombre de modelo Fable 5 con sufijo [1m] se normaliza/elimina automáticamente: Fable 5 ya incluye contexto de 1M de forma predeterminada, así que el sufijo es innecesario (solo tuvo sentido alguna vez en Opus/Sonnet). Desde v2.1.172 (10 de junio de 2026), los sub-agents pueden generar recursivamente sus propios sub-agents, hasta 5 niveles de profundidad, Bedrock lee su región desde ~/.aws cuando AWS_REGION no está definido (/status muestra la fuente), /plugin agrega una barra de búsqueda del marketplace, y la métrica OTEL claude_code.lines_of_code.count incorpora un atributo model. Desde v2.1.170 (9 de junio de 2026), Claude Fable 5, un nuevo nivel de modelo por encima de Opus, se puede seleccionar en Claude Code mediante /model fable después de claude update (admite toda la escala de esfuerzo low–max, pero no se le puede desactivar thinking); Opus 4.8 sigue siendo el valor predeterminado agéntico. Desde 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 troubleshooting, /cd mueve una sesión a un nuevo directorio de trabajo sin romper la caché del prompt, y disableBundledSkills oculta al modelo los skills y slash commands integrados. Desde 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 reglas de denegación de MCP, y MAX_THINKING_TOKENS=0 / --thinking disabled desactivan por completo thinking en modelos con think-by-default. Desde v2.1.154 (28 de mayo de 2026), Opus 4.8 es el nuevo valor predeterminado con esfuerzo alto por defecto y un nivel /effort xhigh, los dynamic workflows orquestan decenas o cientos de agents en segundo plano mediante /workflows, Fast mode en Opus 4.8 cuesta 2× la tarifa estándar para obtener 2,5× de velocidad, el lean system prompt ahora es el valor predeterminado para todos los modelos excepto Haiku/Sonnet/Opus 4.7 y anteriores, /simplify volvió a ser una revisión solo de 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 está siempre habilitada, y los servidores MCP stdio reciben CLAUDE_CODE_SESSION_ID más CLAUDECODE=1 en env. v2.1.153 agregó skipLfs a los marketplaces de plugins, hizo que /model se guardara como valor predeterminado (presiona s para que aplique solo a la sesión) y puso COLUMNS/LINES en el env de la línea de estado. v2.1.152 introdujo /code-review --fix (aplica hallazgos al working tree), disallowed-tools en el frontmatter de skills, /reload-skills, el nuevo evento de hook MessageDisplay, salidas reloadSkills/sessionTitle del hook SessionStart, la configuración administrada pluginSuggestionMarketplaces, cambio de --fallback-model a mitad de sesión, y eliminó el opt-in de auto-mode.^{162 163 164 165 166 167 168 169 170 181 171}

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

La diferencia entre usar Claude Code de forma casual y usarlo de forma efectiva se reduce a cinco sistemas centrales. Domínalos y Claude Code se convierte en un multiplicador de fuerza:

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

Puntos clave

• Cinco sistemas determinan tu efectividad: la jerarquía de configuración, los permisos, los hooks, MCP y los subagents controlan todo, desde el comportamiento hasta la automatización.
• Empuja el trabajo a la Delegation Layer: los subagents evitan la expansión del contexto al aislar la exploración en ventanas de contexto limpias y devolver solo resúmenes.
• Los hooks garantizan la ejecución; los prompts no: usa hooks para linting, formatting y verificaciones de seguridad que deben ejecutarse siempre, independientemente del comportamiento del modelo.
• La segmentación por niveles de modelo reduce costos sin sacrificar calidad: dirige la exploración de subagents a modelos más económicos y reserva Opus para razonamiento arquitectónico real, o estandariza en Opus si la calidad es tu única variable.
• MCP conecta Claude con tu toolchain: bases de datos, GitHub, Sentry y más de 3.000 integraciones amplían Claude más allá de la lectura de archivos y los comandos bash.

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

Elige tu ruta

Cómo usar esta guía

Esta es una referencia de más de 5.000 líneas; no necesitas leerla de principio a fin. Empieza donde encaje 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 al final ofrece un resumen fácil de escanear de todos los comandos principales.

Análisis relacionados

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

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. Navega a un proyecto:

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

3. Pídele a Claude que haga algo:

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

4. Usa atajos clave durante tu sesión:

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

5. Continúa más tarde:

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

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

Modos de interacción principales

REPL interactivo

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

cd your-project
claude

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

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

claude "explain the authentication flow in this project"

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

Modo no interactivo

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

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

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

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

Para una salida estructurada apta para analizar en scripts:

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

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

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

Para procesamiento en tiempo real de la salida en streaming:

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

Opciones de formato de salida:

Códigos de salida:

Controlar el comportamiento agéntico en modo -p:

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

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

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

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

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

Patrón de integración CI/CD:

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

Gestión de sesiones

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

# Continue most recent session
claude -c

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

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

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

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

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

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

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

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

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

# Name current session
> /rename auth-refactor

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

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

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

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

Modo de planificación

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

Entrar al modo de planificación:

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

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

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

Cómo funciona:

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

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

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

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

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

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

Análisis profundo del sistema de configuración

Claude Code usa un sistema de configuración por capas. Entender la jerarquía es esencial porque los niveles superiores anulan los inferiores, y la configuración empresarial no se puede eludir en absoluto.

Jerarquía de configuración

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

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

A partir de v2.1.181, /config key=value establece cualquier configuración en línea 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) enumera las claves abreviadas disponibles. v2.1.183 también cambió la interfaz interactiva de /config para que Enter y Space alternen la configuración seleccionada y Esc guarde y cierre (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/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "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 es útil cuando un equipo tiene una biblioteca grande de skills, pero quiere una exposición más estricta en tiempo de ejecución. Usa off para ocultar una skill tanto del modelo como del selector de slash, user-invocable-only para mantenerla invocable por nombre mientras se elimina de la selección del modelo, y name-only para mantener visible solo el nombre de la skill sin su descripción completa.¹⁵⁶

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

• availableModels / enforceAvailableModels (managed, v2.1.175+): la allowlist de availableModels restringe qué modelos puede seleccionar una sesión. Con enforceAvailableModels: true, la allowlist también limita el modelo Default: un Default que se resolvería a un modelo no permitido vuelve al primer modelo permitido, y la configuración de usuario/proyecto ya no puede ampliar una lista availableModels administrada. Una corrección complementaria (v2.1.176) cierra la brecha en la que una selección por alias podía redirigir a un modelo bloqueado mediante ANTHROPIC_DEFAULT_*_MODEL, y /fast ahora se niega a cambiar a un modelo fuera de la allowlist.¹⁷²
• language (ajuste de v2.1.176): además de configurar el idioma de respuesta, los títulos de sesión ahora se generan por defecto 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 regex en la fila del footer, configurables mediante configuración de usuario o administrada.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): establece en false para desactivar la aceleración del desplazamiento con rueda del mouse en modo fullscreen.¹⁷²

Referencia de variables de entorno

Autenticación y API:

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

Configuración del modelo:

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

Configuración del proveedor cloud:

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 de comportamiento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
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]

Configuración de herramientas:

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

Red y proxy:

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

UI y terminal:

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

Exportadores de OpenTelemetry + control de campos sensibles:¹⁸²

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

Atributos de spans de solicitud LLM en v2.1.121+: stop_reason, gen_ai.response.finish_reasons y user_system_prompt ahora se emiten en spans de solicitud LLM. user_system_prompt está protegido detrás de OTEL_LOG_USER_PROMPTS=1, ya que puede contener PII.¹⁵⁴

Cambios a nivel de evento en v2.1.122+: Los atributos numéricos en eventos de log api_request y api_error ahora se emiten como números (antes eran strings), lo que corrige colectores OTel posteriores que aplicaban tipado estricto al schema. El nuevo evento de log claude_code.at_mention se dispara cuando Claude Code resuelve una mención @.¹⁵⁴

Control de API / modelo:¹⁸²

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

Plugins / MCP:¹⁸²

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

Shell / IDE:¹⁸²

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

Empresarial / auth:¹⁸²

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

Variables de skills (v2.1.69+):

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

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

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

Depuración:

ANTHROPIC_LOG=debug                             # Enable API request logging

¿Qué modelo debería elegir?

Elegir el modelo adecuado para cada tarea tiene un impacto importante tanto en el costo como en la calidad. Claude Code ofrece cambio flexible de modelo en varios niveles.

Modelos disponibles

Claude Fable 5 (9 de junio de 2026): Un nuevo nivel de modelo por encima de Opus: el modelo más potente e inteligente de Anthropic, de última generación en casi todos los benchmarks en los que se ha probado, y construido para mantenerse coherente a través de millones de tokens de contexto. Fable 5 es el modelo frontier de clase “Mythos” hecho seguro para uso general: incluye clasificadores de seguridad que recurren a Opus 4.8 en consultas de ciberseguridad, bioquímica y destilación de modelos (Claude Mythos 5 es el mismo modelo con esas protecciones levantadas para investigadores autorizados). Pasó a estar disponible en Claude Code con v2.1.170 (9 de junio de 2026): ejecuta claude update, luego /model fable (el alias corto; /model claude-fable-5 y el alias best también lo seleccionan), y se está implementando en los planes de suscripción hasta el 22 de junio de 2026. Model ID: claude-fable-5. Fable 5 incluye una ventana de contexto de 1M por defecto, así que el sufijo [1m] no es necesario; además, desde v2.1.173 (11 de junio de 2026), un nombre de modelo claude-fable-5[1m] se normaliza o se elimina automáticamente a claude-fable-5 (el sufijo solo tuvo sentido en Opus/Sonnet, donde 1M está condicionado a [1m]); salida máxima de 128K. El precio es $10/MTok de entrada y $50/MTok de salida, aproximadamente 2× Opus 4.8, así que resérvalo para razonamiento realmente difícil, no para ediciones rutinarias. Comparte la superficie de solicitudes de Opus 4.8 (solo adaptive thinking; se eliminaron temperature/top_p/top_k y budget_tokens) con una novedad: un thinking: {type: "disabled"} explícito devuelve un 400, así que omite por completo el parámetro thinking para ejecutarlo sin thinking.¹⁷⁵

En Claude Code específicamente: Fable 5 admite toda la escala de esfuerzo (low/medium/high/xhigh/max, high por defecto), igual que Opus 4.8. El thinking no se puede desactivar en Fable 5: el interruptor de thinking de la sesión, la configuración alwaysThinkingEnabled y MAX_THINKING_TOKENS=0 no tienen efecto; siempre razona de forma adaptativa. Una superficie completa de configuración de la familia fable refleja los controles de Opus: ANTHROPIC_DEFAULT_FABLE_MODEL fija el modelo al que resuelve el alias fable (útil en Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE excluye a Fable del prompt caching, y el fallback automático basado en contenido aplica en los gateways empresariales. Opus 4.8 sigue siendo el predeterminado agentic de Claude Code (esfuerzo alto por defecto, /effort xhigh para las tareas más difíciles); elige Fable 5 deliberadamente con /model fable cuando quieras el techo absoluto.¹⁷⁵

Opus 4.7 (16 de abril de 2026): El buque insignia de la generación anterior, todavía completamente disponible. Ventana de contexto de 1M tokens con precio estándar, sin prima por contexto largo. Salida máxima de 128K, solo adaptive thinking (se eliminó extended thinking), y un nuevo nivel de esfuerzo xhigh recomendado como punto de partida para cargas de programación y agentic.¹⁴⁵ Corte de conocimiento confiable: enero de 2026. Corte de datos de entrenamiento: enero de 2026. Model ID: claude-opus-4-7. El precio coincide con Opus 4.6 a $5/$25 por MTok, con escritura de caché de 5 min a $6.25, escritura de caché de 1 h a $10 y lectura de caché a $0.50 por MTok.¹⁴⁴ Opus 4.7 resuelve 3× más tareas de producción en SWE-Bench que Opus 4.6, obtiene 70% en CursorBench (frente a 58% de 4.6) y aumenta la resolución 13% en el benchmark interno de programación de 93 tareas de Anthropic.¹⁴⁴ Usa un tokenizer nuevo: espera aproximadamente 1×–1.35× conteos de tokens para el mismo texto; aumenta el margen de max_tokens y los disparadores de compactación.¹⁴⁵ Vision admite imágenes de hasta 2.576 px / 3,75 MP con coordenadas de píxel 1:1.¹⁴⁵

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

Opus 4.7 lidera SWE-bench Verified por 12.7 puntos sobre la baseline ampliamente citada de GPT-5-Codex y SWE-bench Pro por 6.6 sobre GPT-5.4 (57.7%). En Terminal-Bench 2.0, GPT-5.3-Codex todavía supera por poco a GPT-5.4 (77.3% frente a 75.1%) y ambos superan a Opus 4.7 (69.4%). El liderazgo en benchmarks cambia rápido; revisa las páginas de los proveedores antes de comprometerte con una elección de varios trimestres.

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

Opus 4.7 requiere Claude Code v2.1.111 o posterior; ejecuta claude update para actualizar.¹⁴⁷ Bedrock, Vertex y Foundry exponen Opus 4.7 mediante nombres completos de modelo explícitos o pins ANTHROPIC_DEFAULT_OPUS_MODEL, no mediante el alias opus por defecto.¹⁴⁷

Cambios incompatibles de Messages API en Opus 4.7 (visibles para quien llama):¹⁴⁵

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

Los presupuestos de tarea (beta header task-budgets-2026-03-13) te permiten indicar al modelo un objetivo de tokens a lo largo de un ciclo agentic completo mediante output_config.task_budget; mínimo 20K tokens.¹⁴⁵

Opus 4.6 (legacy): Sigue disponible en claude-opus-4-6 con contexto de 1M y salida máxima de 128K. Considera migrar a Opus 4.7 para una mejor programación agentic. Opus 4.6 se lanzó originalmente el 5 de febrero de 2026.⁷⁹¹⁴⁴ Desde v2.1.117 (22 de abril de 2026), los suscriptores Pro y Max usan esfuerzo high por defecto en Opus 4.6 y Sonnet 4.6 (antes medium); Opus 4.7 se mantiene en xhigh. Este cambio restauró inteligencia después de la degradación de esfuerzo del 4 de marzo al 7 de abril documentada en el postmortem del 23 de abril.¹⁵²¹⁵³

Sonnet 4.6 (17 de febrero de 2026): Modelo equilibrado; reemplazó a Sonnet 4.5 como predeterminado en claude.ai y Claude Cowork.⁹³ Mismo precio que Sonnet 4.5 ($3/$15 por MTok). Mejora el rendimiento de búsqueda agentic mientras consume menos tokens. Admite extended thinking, adaptive thinking y una ventana de contexto de 1M tokens (beta). Salida máxima de 64K (límite superior de 128K en v2.1.77).¹¹⁹ Corte de conocimiento: agosto de 2025 (confiable), enero de 2026 (datos de entrenamiento). Model ID: claude-sonnet-4-6.

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

Por qué importan estas diferencias de 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, eso cuesta $0.10-$0.45 por sesión. Con Opus, la misma sesión cuesta $0.50-$2.25, 5x más. Reserva Opus para problemas realmente difíciles.¹

Cuándo usar cada modelo

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

Sonnet: El caballo de batalla para el desarrollo diario cuando el costo importa. Maneja la mayoría de las tareas de programación: implementar funciones, corregir bugs, escribir tests, hacer code review. Sonnet 4.6 ofrece mejor búsqueda agentic y mayor eficiencia de tokens en comparación con Sonnet 4.5, con soporte para adaptive thinking y una ventana de contexto de 1M a precio estándar.⁹³ Desde Opus 4.7 (16 de abril de 2026), Claude Code usa Opus por defecto solo en los planes Max y Team Premium; las cuentas Pro, Team Standard, Enterprise y API mantienen Sonnet 4.6 como predeterminado hasta que Enterprise y API cambien a Opus 4.7 el 23 de abril de 2026.¹⁴⁷ Usa Sonnet cuando necesites tokens más baratos, menor latencia o una economía viable para subagents.

Opus: El nivel insignia desde el 16 de abril de 2026, y el predeterminado en los planes Max y Team Premium.¹⁴⁴¹⁴⁷ Reserva el razonamiento de mayor costo para donde rinde: decisiones de arquitectura, debugging difícil, comprender sistemas complejos, análisis de seguridad y trabajo agentic de largo alcance. Opus 4.7 resuelve 3× más tareas de producción en SWE-Bench que Opus 4.6, obtiene 70% en CursorBench (frente a 58%) y aumenta la resolución 13% en un benchmark interno de programación de 93 tareas.¹⁴⁴ Claude Code usa esfuerzo xhigh por defecto en Opus 4.7, ajustable mediante /effort (v2.1.111+).¹⁴⁶¹⁴⁷ Auto Mode está disponible para suscriptores Max en Opus 4.7 mediante Anthropic API sin requerir --enable-auto-mode; otros planes/proveedores tienen disponibilidad específica del plan y controlada por administradores.¹⁴⁶ Contexto de 1M a precio estándar, sin prima por contexto largo. Cambios de comportamiento que conviene conocer: Opus 4.7 sigue las instrucciones de forma más literal, calibra la longitud de la respuesta según la complejidad de la tarea, ejecuta menos subagents por defecto y adopta un tono más directo, con menos frases centradas en validar. Si tus prompts contienen andamiaje para forzar mensajes intermedios de progreso o comportamiento de doble verificación, prueba quitarlo.¹⁴⁵

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

Cambiar de modelo

Durante la sesión:

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

Al iniciar:

claude --model opus

Mediante el entorno:

export ANTHROPIC_MODEL=opus

En settings.json:

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

Para subagents específicamente:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Cadena de modelo de fallback (v2.1.166+): la configuración fallbackModel permite configurar hasta tres modelos de fallback, que se prueban en orden cuando el modelo principal está sobrecargado o no está disponible. El flag --fallback-model (antes solo un cambio a mitad de sesión) ahora también aplica a sesiones interactivas desde el inicio.¹⁷⁷

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

Cuando API devuelve un error inesperado no reintentable, Claude Code ahora también reintenta el turno una vez en el modelo de fallback antes de mostrar la falla, de modo que un problema transitorio del modelo principal se degrada con gracia en lugar de perder el turno.¹⁷⁷

Desde v2.1.178, la compactación también respeta la cadena de fallback: si el modelo principal está sobrecargado o no está disponible durante la compactación, el paso de compactación recurre a la cadena fallbackModel/--fallback-model configurada en vez de fallar el turno. Para una ejecución autónoma larga, esto cierra la brecha donde una compactación que de otro modo sería recuperable podía perder la sesión por un error transitorio del modelo.¹⁷³

Contexto extendido

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

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

O dentro de una sesión:

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

Opus 4.7, Opus 4.6 y Sonnet 4.6 incluyen la ventana completa de contexto de 1M tokens a precio estándar, sin prima por contexto largo.¹⁴⁸ Una solicitud de 900K tokens se factura con la misma tarifa por token que una solicitud de 9K tokens. Los descuentos por prompt caching y procesamiento por lotes aplican a tarifas estándar en toda la ventana de contexto.

En suscripciones Max, Team y Enterprise, Opus con contexto de 1M se incluye automáticamente, sin necesidad del sufijo [1m] (habilitado por defecto desde v2.1.75, 13 de marzo de 2026).¹¹⁷¹⁴⁷ En Pro, el contexto de 1M está disponible mediante extra usage. Los usuarios de API y pay-as-you-go tienen acceso completo a 1M con tarifas estándar por token.¹⁴⁷

Para desactivar variantes de contexto de 1M en el selector de modelo, define CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Verificar el modelo actual

> /status

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

Etiquetas del selector de modelo (v2.1.51+): El selector /model ahora muestra etiquetas legibles para humanos (por ejemplo, “Sonnet 4.6”) en lugar de IDs de modelo sin procesar para versiones fijadas, con sugerencias de actualización cuando hay versiones más recientes disponibles.⁹⁸

Fast Mode (v2.1.36+)

Fast mode ofrece una salida considerablemente más rápida desde el mismo modelo; no cambia a un modelo más barato. Actívalo o desactívalo durante una sesión con /fast.⁸⁶

> /fast            # Toggle fast mode on/off

Precios (fast mode de Opus 4.6):

Fast mode es una vista previa de investigación, solo para Opus 4.6, y ofrece una salida ~2.5× más rápida a 6× el precio base.¹⁴⁹ Habilitar /fast cambia automáticamente la sesión a Opus 4.6 si estabas en otro modelo; deshabilitar /fast te deja en Opus 4.6 hasta que cambies mediante /model. Fast mode no está disponible en Opus 4.7, Sonnet, Haiku ni mediante Bedrock/Vertex/Foundry. Requiere que extra usage esté habilitado y, para Team/Enterprise, habilitación del administrador.

Cuándo usar fast mode: - Iterar rápido sobre cambios pequeños cuando la latencia es el cuello de botella - Generar tests, boilerplate o código repetitivo donde la velocidad importa más que el costo - Trabajar secuencialmente con una lista de tareas similares

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

El fast mode de Opus 4.6 incluye la ventana completa de contexto de 1M (v2.1.50+). El precio de fast mode es plano en todo el contexto de 1M, sin recargo adicional por contexto largo.⁹⁶¹⁴⁹

Consejo experto: Fast mode no se combina con opusplan (opusplan ya mezcla Opus y Sonnet; fast mode solo afecta a Opus 4.6). Usa fast mode directamente cuando la latencia importe más que el costo, y desactívalo para trabajo autónomo o por lotes. /fast requiere extra usage; los administradores de Team/Enterprise quizá deban habilitarlo primero (corrección de v2.1.37).⁸⁶¹⁴⁹

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

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

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

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

Auto Mode en Max (v2.1.111+)

Auto Mode, un reemplazo más seguro para --dangerously-skip-permissions, está disponible para suscriptores Max en Opus 4.7 mediante Anthropic API sin --enable-auto-mode.¹⁴⁶ Un clasificador Sonnet 4.6 revisa cada acción antes de ejecutarla, verificando coincidencia de intención y seguridad. Nota (v2.1.111+): se eliminó el flag --enable-auto-mode; inicia una sesión en Auto Mode con --permission-mode auto en su lugar. Auto Mode no está disponible en Pro; según la documentación de modos de permiso de Anthropic, está directo en Anthropic API por defecto. Bedrock/Vertex/Foundry (v2.1.158+): Auto Mode ahora es opt-in en Opus 4.7 y Opus 4.8 en esos gateways con CLAUDE_CODE_ENABLE_AUTO_MODE=1.¹⁸⁰

Reglas personalizadas sin perder los valores predeterminados (v2.1.118+). Las versiones anteriores hacían que autoMode.allow, autoMode.soft_deny y autoMode.environment fueran una cosa u otra: definías tu propia lista y perdías las reglas de seguridad incorporadas. El sentinel $defaults resuelve esto: se expande en línea a la lista incorporada justo en la posición donde lo colocas, para que puedas superponer reglas personalizadas alrededor de ellas:¹⁵²

// .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
    ]
  }
}

Opt-in de “Don’t ask again” (v2.1.118+). El prompt de opt-in de Auto Mode ahora ofrece una opción “Don’t ask again”, para que los usuarios frecuentes puedan suprimir la explicación sin escribir scripts con un flag.¹⁵²

Guardrails para comandos destructivos (v2.1.183). Auto mode ahora bloquea de forma estricta un conjunto de comandos irreversibles salvo que los hayas pedido explícitamente en la sesión: operaciones destructivas de git (git reset --hard, git checkout -- ., git clean -fd, git stash drop) cuando no pediste descartar trabajo local; git commit --amend cuando el commit no fue hecho por el agente en esta sesión; y eliminación de infraestructura (terraform destroy, pulumi destroy, cdk destroy) salvo que hayas nombrado el stack específico. Esto reduce el radio de impacto del clasificador justo para las operaciones que pueden perder trabajo en silencio o derribar entornos: el agente todavía puede ejecutarlas, pero solo con tu instrucción explícita, no por iniciativa propia.¹⁷⁴

Comandos nuevos en v2.1.105–v2.1.114¹⁴⁶¹⁵⁰

Session Recap (v2.1.108+)

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

Notificaciones push (v2.1.110+)

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

Herramienta Windows PowerShell (v2.1.111+, despliegue)

Claude Code está desplegando 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 opt-in/opt-out durante el despliegue.¹⁴⁶

Autoaprobación en modo de permisos (v2.1.119+). Los comandos de la herramienta PowerShell ahora pueden recibir autoaprobación en permission mode del mismo modo que los comandos Bash. Reglas allow como PowerShell(Get-*:*) y la sintaxis de patrones existente ahora omiten el prompt para operaciones read-only, igualando la ergonomía operativa que los equipos ya tienen en Linux/macOS.¹⁵²

Reducción de permisos: Bash read-only (v2.1.111+)

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

Distributed Tracing (v2.1.110+)

SDK y las sesiones headless ahora leen TRACEPARENT y TRACESTATE desde el entorno, enlazando ejecuciones de Claude Code con trazas distribuidas. Combínalo con OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+) para emitir cuerpos completos de solicitud/respuesta de API como eventos de log de OpenTelemetry para debugging.¹⁴⁶

Distribución binaria nativa (v2.1.113+)¹⁵⁰

v2.1.113 cambia cómo se inicia CLI: claude ahora genera un binario nativo de Claude Code mediante una dependencia opcional por plataforma en lugar de ejecutar JavaScript empaquetado. Los comandos de instalación y actualización se mantienen iguales, y los equipos no necesitan cambiar scripts de despliegue.

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

El editor de prompts gana navegación estilo readline en entradas multilínea, además de desplazamiento de viewport en fullscreen:

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

Timeout por bloqueo de subagent (v2.1.113+)¹⁵⁰

Los subagents que se bloquean a mitad del stream ahora fallan con un error claro después de 10 minutos en lugar de quedarse colgados en silencio. Combínalo con CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) para una cobertura más amplia de procesos atascados en APIs de streaming.

Corrección de estabilidad v2.1.114¹⁵⁰

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

¿Cuánto cuesta Claude Code?

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

Visualizar costos

> /cost

Salida:

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

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

Planes de suscripción

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

Duplicación de límites de tasa (6 de mayo de 2026): Durante el evento Code with Claude SF, Anthropic duplicó los límites de tasa de cinco horas de Claude Code en los planes Pro, Max, Team y Enterprise por asiento, eliminó la reducción en horas pico en las cuentas Pro y Max, y “considerablemente” elevó los límites de tasa 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 NVIDIA GPUs) dentro del mes.”¹⁵⁷

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

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

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

Precios por residencia de datos: Especificar inferencia solo en EE. UU. mediante inference_geo añade un multiplicador de 1,1× sobre todos los precios de tokens, incluidas las lecturas y escrituras de caché (modelos Opus 4.6+).¹⁴⁸

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

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

Política de múltiples cuentas⁵²

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

Lo que está permitido:

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

Lo que está prohibido (según la Política de uso): - Crear cuentas para evadir suspensiones después de haber sido suspendido - Coordinar actividad maliciosa entre cuentas para evitar la detección - Usar varias cuentas para eludir los límites de tasa o los créditos del nivel gratuito

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

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

Factores de costo

Ejemplos reales de costos

Insight para ahorrar costos: Usar Haiku para subagentes de exploración y Sonnet para implementación reduce típicamente los costos entre un 40 y un 50 % en comparación con usar Sonnet para todo.

Gestión de costos en equipos

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

Tarifas ocultas de herramientas

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

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

Estrategias para ahorrar costos

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

Monitorear el uso

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

Uso de tokens en segundo plano

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

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

Claude Code Analytics API (Team/Enterprise)⁴⁶

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

Endpoint: GET /v1/organizations/usage_report/claude_code

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

Métricas disponibles:

Solicitud de ejemplo:

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

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

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

Marcos de decisión

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

¿Qué modelo debo usar?

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

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

¿Comando vs Skill vs Subagent vs equipo de agentes?

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

¿Hook vs prompt?

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

¿Cuándo usar extended thinking?

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

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

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

¿Qué superficie de ejecución?

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

Equipos de agentes vs subagents vs sesiones paralelas

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

¿Qué tipo de hook?

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

¿Cuándo usar /fast?

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

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

¿Cómo funciona el sistema de permisos?

El sistema de permisos de Claude Code ofrece control detallado sobre qué operaciones pueden ejecutarse. Entenderlo es esencial tanto para la seguridad como para la eficiencia del flujo de trabajo. Consulta también Implementación empresarial para ver 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 dentro del contenido de archivos - WebSearch - Buscar en la web - LSP - Inteligencia de código (ir a definición, buscar referencias, documentación al pasar el cursor)¹⁸

Capacidades de la herramienta LSP (v2.0.74+): La herramienta LSP ofrece inteligencia de código similar a la de un IDE: - Ir a definición: Saltar al lugar donde se define un símbolo - Buscar referencias: Listar todos los usos de un símbolo en todo el codebase - 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 con soporte para LSP - Requiere que el language server esté disponible (normalmente instalado con tu toolchain)

Herramientas de modificación (requieren aprobación): - Edit - Modificar archivos existentes - Write - Crear archivos nuevos - Bash - Ejecutar comandos de shell - WebFetch - Obtener 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 persisten durante la sesión, salvo que se configure explícitamente lo contrario.

Modos de permisos

Los archivos de configuración que permiten ejecución de código ahora solicitan confirmación incluso con acceptEdits (v2.1.160). acceptEdits aprueba automáticamente las ediciones ordinarias, pero desde v2.1.160 se detiene y solicita confirmación antes de escribir archivos que pueden conceder ejecución silenciosa de comandos: archivos de inicio de shell (.zshenv, .zlogin, .bash_login), ~/.config/git/ y configuraciones de herramientas de build (.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/ y similares). La razón es que una edición en cualquiera de estos convierte el siguiente shell, instalación o commit en un vector de ejecución, por lo que reciben una barrera deliberada incluso en un modo de proyecto de confianza que, por lo demás, deja pasar las ediciones. Es el mismo modelo de amenaza que las protecciones de escritura existentes para .claude/, .git/ y .vscode/, extendido a la clase más amplia de archivos donde “editar se convierte en ejecutar”.¹⁷⁹

Auto Mode (v2.1.85+): Un reemplazo más seguro para --dangerously-skip-permissions. Un modelo clasificador separado (Sonnet 4.6) revisa cada acción antes de la ejecución y verifica que coincida con la intención del usuario y sea segura.¹²⁴

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

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

Interruptor de seguridad: 3 bloqueos consecutivos o 20 en total dentro de una sesión pausan y vuelven a las solicitudes manuales.¹²⁵

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

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

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

Modo YOLO (v2.0.68+): Para una operación completamente autónoma sin ningún clasificador de seguridad, usa el flag --dangerously-skip-permissions. El flag dice sí a todo: ediciones de archivos, comandos bash, 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

Configura el modo mediante CLI:

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

Alterna durante la sesión:

Shift+Tab  # Cycles through modes

En settings.json:

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

Sintaxis de reglas de permisos

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

Patrones de comandos Bash:

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

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

Limitación importante: Los patrones de Bash solo coinciden con prefijos, no con regex. Un patrón como Bash(curl http:*) no coincidirá con curl -X GET http://... porque las opciones aparecen antes de la URL. Para un bloqueo confiable, deniega el comando completo: Bash(curl:*).

Patrones de operaciones con archivos:

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

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

Patrones de herramientas MCP:

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

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

Desde v2.1.166, las reglas de denegación también aceptan un glob en la posición del nombre de herramienta: un "*" sin más en el espacio del nombre de herramienta deniega todas las herramientas, de modo que puedes bloquear todo y luego volver a permitir un conjunto reducido. Las reglas de permitir, en cambio, rechazan globs que no sean de MCP: no puedes permitir todo de forma amplia del mismo modo, lo que mantiene una postura predeterminada restrictiva.¹⁷⁷

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

Más allá del nombre de la herramienta, una regla puede coincidir con los parámetros de entrada de una herramienta, con * como comodín en el valor:

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

Agent(model:opus) bloquea cualquier subagent generado en el nivel Opus: se deniega la generación en sí, no solo se pide en el prompt que se evite. Esto extiende el control de permisos desde “qué herramienta” hasta “cómo se llama”, como una regla determinista en lugar de una solicitud a nivel de prompt. Se combina con la configuración administrada enforceAvailableModels: la lista de permitidos define qué niveles de modelo existen para la sesión, y las reglas Tool(model:...) limitan cómo los subagents los usan.¹⁷³

Patrones de WebFetch:

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

Directorios adicionales

Extiende el acceso de Claude más allá del proyecto actual:

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

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

Modo sandbox

Habilita el aislamiento del sistema de archivos y la red:

> /sandbox

O configúralo en settings:

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

Cuando está en sandbox: - Acceso al sistema de archivos restringido al directorio del proyecto - Acceso de red controlado - Ciertos comandos excluidos de las restricciones del sandbox - Los comandos Bash se permiten automáticamente si autoAllowBashIfSandboxed es true

Consejo experto: El modo sandbox es excelente para ejecutar Claude en codebases no confiables. Habilítalo al explorar proyectos desconocidos o cuando quieras una capa adicional de protección. Pruebas internas de Anthropic encontraron que el sandbox reduce las solicitudes de permisos en un 84 %.³⁸ El sandbox usa primitivas a nivel del sistema operativo (macOS seatbelt, Linux bubblewrap) para aislar el sistema de archivos y la red, por lo que incluso una inyección de prompt exitosa queda completamente contenida. Anthropic ha publicado como open source el runtime de sandbox para equipos que construyen sus propios agentes.⁸²

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

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

Resolución de .claude/ anidado (v2.1.178): Las skills en directorios .claude/skills anidados ahora se cargan automáticamente cuando trabajas en archivos dentro de ese directorio, no solo desde la raíz del repo; si hay un conflicto de nombres, la skill anidada se puede invocar como <dir>:<name>, de modo que ambas siguen disponibles. El resto de la superficie del proyecto se resuelve de la misma forma: cuando el nombre de un agente, workflow o estilo de salida entra en conflicto entre directorios .claude/ anidados, gana el que esté más cerca del directorio de trabajo, y un guardado de workflow con alcance de proyecto apunta al .claude/workflows/ existente más cercano. Para un monorepo o repo de repos, esto ofrece herramientas por paquete que se activan en contexto en lugar de una sola superficie global plana.¹⁷³

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

Refuerzo de seguridad en v2.1.113:¹⁵⁰

• sandbox.network.deniedDomains bloquea hosts específicos incluso cuando un comodín más amplio de allowedDomains los permitiría. Usa la lista de bloqueo para cortar el acceso a pastebins, servicios de subida de archivos o hosts conocidos como maliciosos sin reescribir toda tu política de permisos.
• Reglas de denegación para comandos envoltorio. Las reglas de denegación de Bash ahora coinciden con comandos envueltos en env, sudo, watch, ionice, setsid y wrappers 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 permiso Bash(find:*) ya no aprueban automáticamente find -exec ni find -delete. Esos flags ejecutan comandos y eliminan archivos, así que Claude Code los enruta por la ruta normal de permisos.
• Protección contra eliminación en macOS. Las reglas de permiso Bash(rm:*) ahora tratan /private/etc, /private/var, /private/tmp y /private/home como destinos de eliminación peligrosos. /var, /etc y /tmp son symlinks hacia /private/, por lo que la forma anterior de la regla no detectaba los destinos canónicos.

¿Cómo funcionan los hooks?

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

Por qué usar hooks en lugar de prompts: Decirle a Claude “ejecuta siempre Prettier después de editar archivos” funciona a 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 cumplimiento, seguridad y estándares de equipo, lo determinista supera a lo probabilístico.⁴

Eventos disponibles

Configuración de hooks

Define 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)

Protocolo de entrada/salida de hooks

Los hooks reciben JSON en stdin:

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

Enriquecimiento de eventos de hook (v2.1.69+): Todos los eventos de hook 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 de hook de la línea de estado.¹¹⁰

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

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

Retroalimentación suave sin bloqueo (v2.1.163+): Los hooks Stop y SubagentStop pueden devolver hookSpecificOutput.additionalContext en su salida JSON para pasarle retroalimentación a Claude y mantener el turno en marcha, sin que la respuesta se etiquete como error de hook. Antes, la única palanca real de un hook Stop era el bloqueo con exit-2 (que se lee como error y cuenta para el límite de bloqueos consecutivos); additionalContext agrega un canal de dirección para guías del tipo “esto te faltó, continúa” que no pelea contra el bucle.¹⁷⁸

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

Para control avanzado, los hooks pueden generar JSON:

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

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

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

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

Título de sesión de UserPromptSubmit (v2.1.94+): Los hooks UserPromptSubmit pueden definir 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 tu configuración de hook:⁸¹

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

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

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

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

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

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

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

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

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

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

Los agent hooks (type: "agent") inician un subagent con acceso a herramientas (Read, Grep, Glob) para verificación de varios turnos. Úsalos cuando la comprobación requiere inspeccionar archivos reales o salida de pruebas:

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

Usa $ARGUMENTS como placeholder para la entrada JSON del hook. Ambos tipos admiten los campos model (predeterminado: modelo rápido) y timeout. Eventos compatibles: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle no admite prompt/agent hooks.

Hooks de herramienta MCP (v2.1.118+)

Los hooks ahora pueden invocar directamente una herramienta MCP mediante type: "mcp_tool", evitando la necesidad de envolver 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 encaja bien con los servidores MCP que los usuarios ya tienen configurados: cualquier herramienta alcanzable desde /mcp puede llamarse desde un hook.

duration_ms en hooks PostToolUse (v2.1.119+)

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

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

updatedToolOutput para todas las herramientas (v2.1.121+)

En v2.1.118, los MCP Tool Hooks obtuvieron la capacidad de reemplazar la salida de herramientas mediante hookSpecificOutput.updatedToolOutput. A partir de v2.1.121, el mismo campo funciona para cualquier hook PostToolUse: herramientas integradas (Bash, Read, Edit, Glob, Grep, etc.), herramientas de subagent y herramientas MCP. Casos de uso: redactar contenido sensible de la salida de cualquier herramienta, normalizar la estructura para consumidores posteriores, inyectar metadatos antes de que el agent lea el resultado.¹⁵⁴

Variables de entorno de hooks

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

Persistir variables de entorno desde SessionStart:

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

Seguridad de HTTP hooks (v2.1.51+): Los HTTP hooks que interpolan variables de entorno en headers ahora requieren una lista explícita allowedEnvVars. Esto evita la exfiltración arbitraria de variables de entorno mediante valores de header. Los HTTP hooks también se enrutan a través del proxy de red del sandbox cuando el sandboxing está habilitado, lo que aplica la allowlist de dominios. Los HTTP hooks no son compatibles con eventos SessionStart/Setup.⁹⁸

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

Confianza del workspace para hooks (v2.1.51+): Los comandos de hook statusLine y fileSuggestion ahora requieren aceptar la confianza del workspace antes de ejecutarse en modo interactivo, lo que cierra un posible vector de seguridad.⁹⁸

Ejemplos prácticos de hooks

Autoformatear 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 sensibles:

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

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

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

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

Sistema de notificaciones personalizado:

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

Inyectar contexto dinámico en prompts:

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

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

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

Depuración de hooks

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

claude --debug

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

Visualización de la fuente del hook (v2.1.75+): Cuando un hook requiere confirmación del usuario, el prompt de permiso ahora muestra la fuente del hook (settings, plugin o skill), lo que facilita identificar qué componente solicita acceso.¹¹⁷

Hooks con alcance de componente (v2.1.0+)

Los hooks pueden definirse directamente en Skills, subagents y slash commands usando frontmatter. Estos hooks se limitan al ciclo de vida del componente y solo se ejecutan cuando ese componente está activo.³⁴

Skill con hooks integrados:

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

Eventos compatibles: PreToolUse, PostToolUse, Stop

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

Estrategia para sesiones de larga duración

Para sesiones nocturnas o desatendidas de Claude Code, configura hooks que mantengan a Claude encaminado sin intervención manual. La idea clave: usa hooks de linting y pruebas como guardrails que obligan a Claude a corregir problemas antes de continuar.⁵⁷

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

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

Estrategia para sesiones nocturnas:

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

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

¿Qué es MCP (Model Context Protocol)?

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

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

Soporte de MCP remoto (junio de 2025)

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

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

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

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

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

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

MCP Tool Search (v2.1.7+)

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

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

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

Configuración:

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

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

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

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

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

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

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

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

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

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

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

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

Asistente interactivo de configuración de MCP

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

Tipos de transporte

HTTP (recomendado para servidores remotos):

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

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

SSE (obsoleto pero funcional):

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

Stdio (servidores locales):

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

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

Windows requiere un wrapper de cmd para stdio:

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

Gestión de ámbitos

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

Especifica el ámbito durante la instalación:

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