Claude Code CLI: La Guía Completa

TL;DR: Claude Code es un CLI agéntico que lee su código fuente, ejecuta comandos y modifica archivos a través de un sistema por capas de permisos, hooks, integraciones MCP y subagents. Domine cinco sistemas fundamentales (configuración, permisos, hooks, MCP y subagents) y desbloqueará una productividad multiplicadora. Elija el nivel de modelo adecuado para cada tarea — Opus para razonamiento complejo, Sonnet para trabajo general, Haiku para exploración rápida — o estandarice en Opus si la calidad es su única variable. Use hooks (no prompts) para todo lo que deba ejecutarse siempre.

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

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

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

Conclusiones Clave

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

Pasé meses llevando Claude Code al límite en códigos base de producción, pipelines de CI/CD y despliegues empresariales. Esta guía destila esa experiencia en la referencia completa que desearía haber tenido cuando comencé. Cada función incluye sintaxis real, ejemplos de configuración reales y los casos límite que confunden incluso a usuarios experimentados.

Cómo Usar Esta Guía

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

Use Ctrl+F / Cmd+F en su navegador para buscar flags, comandos o claves de configuración específicas. La Tarjeta de Referencia Rápida al final proporciona un resumen escaneable de todos los comandos principales.

Cómo funciona Claude Code: El modelo mental

Antes de profundizar en las funciones, comprenda cómo la arquitectura de Claude Code determina todo lo que hace con él. El sistema opera en tres capas:

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

Capa central (Core Layer): Su 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 rastro de decisiones anteriores y la calidad se degrada. Esta capa tiene un costo por token.

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

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

La idea clave: La mayoría de los usuarios trabajan enteramente en la capa central, observando cómo el contexto se infla y los costos aumentan. 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 central solo para orquestación y decisiones finales.

Tabla de contenidos

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

¿Cómo instalo Claude Code?

Requisitos del sistema

Claude Code funciona en macOS 10.15+, Ubuntu 20.04+/Debian 10+, y Windows 10+ a través de WSL o Git Bash. El sistema requiere un mínimo de 4 GB de RAM y una conexión activa a internet.⁹⁹ La compatibilidad con shells funciona mejor con Bash, Zsh o Fish.

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

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

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 por NPM (obsoleta)

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

Para entornos legacy donde npm aún es necesario:

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

Nunca use sudo con la instalación por npm. Genera problemas de permisos que complican todo lo que viene después.

Migración desde una instalación existente

Si tiene una instalación anterior basada en npm, migre al binario nativo:

claude install

Opciones de autenticación

Claude Code admite tres rutas de autenticación, cada una con diferentes compensaciones:

Claude Console (facturación API)

Conéctese a API de Anthropic directamente a través de platform.claude.com (anteriormente console.anthropic.com). Cree una cuenta, configure la facturación y autentíquese a través de CLI. La Console proporciona facturación basada en uso con acceso completo a API. Se crea automáticamente un workspace dedicado “Claude Code”; no puede crear claves API para este workspace, pero puede monitorear el uso.

Suscripción Claude Pro o Max

Use sus credenciales de la cuenta claude.ai. La suscripción cubre tanto la interfaz web como el uso de 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 empresarial con relaciones de facturación de nube existentes:

# 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

Para implementaciones empresariales detrás de proxies o a través de gateways 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+)

Administre la autenticación sin ingresar al 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

Consulte también: ¿Cómo depuro problemas? para solución de problemas de autenticación.

Actualizaciones

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

Desactivar 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

Limpiar configuración (elimina todos los ajustes):

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

Inicio rápido: Su primera sesión

1. Instale e inicie:

claude                           # Launch in current directory

2. Navegue a un proyecto:

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

3. Pida 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. Use atajos de teclado durante su 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úe después:

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

Consejo avanzado: Cree un archivo CLAUDE.md en la raíz de su proyecto con comandos de compilación, convenciones de código y notas de arquitectura. Claude lo lee en cada sesión — es lo más importante que puede hacer para mejorar la calidad.

Modos de interacción principales

REPL interactivo

Ejecute Claude Code sin argumentos para ingresar al bucle interactivo de lectura-evaluación-impresión:

cd your-project
claude

El REPL mantiene el contexto de la conversación entre turnos. Escriba sus consultas directamente, reciba respuestas y continúe hasta salir con /exit o Ctrl+D.

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

claude "explain the authentication flow in this project"

Consejo avanzado: El REPL conserva el estado entre eventos de compactación. Cuando el contexto crece demasiado, Claude resume automáticamente la conversación anterior preservando las decisiones clave y los fragmentos de código. Puede activar esto manualmente con /compact o agregar instrucciones personalizadas sobre qué preservar.

Modo no interactivo

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

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

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

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

Para obtener salida estructurada adecuada para análisis en scripts:

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

La salida JSON incluye todo lo necesario para la automatización:

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

Para procesamiento en tiempo real de 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:

Control del 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

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 su continuación. La persistencia de sesiones es esencial para trabajos complejos de múltiples 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+): Inicie una sesión vinculada a un pull request específico:⁸¹

claude --from-pr 123                                    # By PR number
claude --from-pr https://github.com/org/repo/pull/123   # By URL

Las sesiones también se vinculan automáticamente a PRs cuando los crea mediante gh pr create durante una sesión. Esto facilita retomar el trabajo en un PR específico posteriormente.

Sesiones con nombre: Asigne nombre a las sesiones al inicio 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 nombres de sesión legibles, utilice /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. Al reanudar, se preserva el contexto completo de conversaciones anteriores.

Modo de planificación

El modo de planificación restringe a Claude a exploración de solo lectura: sin edición 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 su aprobación antes de ejecutar cualquier cosa.

Ingreso 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 ingresa al modo de planificación (automáticamente para tareas complejas, o mediante Shift+Tab)
2. Explora el código base 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 su revisión
5. Usted aprueba, solicita cambios o rechaza

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 la aprobación del plan (v2.1.32+): Claude ofrece tres opciones: - “Yes, clear context and auto-accept edits” (Shift+Tab) — inicia desde cero con contexto completo para el plan - “Yes, and manually approve edits” — preserva el contexto, usted aprueba cada cambio - “Yes, auto-accept edits” — preserva el contexto, Claude ejecuta sin aprobación por edición

Limpiar el contexto al aprobar es el flujo de trabajo recomendado. Le da al plan una ventana de contexto limpia, lo que mejora significativamente la adherencia al plan: Claude se mantiene enfocado por más tiempo sin que la conversación anterior interfiera.

Cuándo usar el modo de planificación: - Implementaciones de nuevas funciones con decisiones arquitectónicas - Refactorizaciones de múltiples archivos donde desea revisar el enfoque primero - Códigos base desconocidos donde la exploración debe preceder a la modificación - Cualquier tarea donde existan múltiples enfoques válidos y desee orientación

Consejo avanzado: Cuanto más tiempo dedique al modo de planificación, más probable es que Claude tenga éxito en la implementación. El modo de planificación es efectivamente exploración gratuita: sin llamadas a herramientas riesgosas, sin ediciones desperdiciadas. Úselo generosamente.

Inmersión en el Sistema de Configuración

Claude Code utiliza un sistema de configuración por capas. Comprender la jerarquía es esencial, ya que los niveles superiores anulan a los inferiores, y la configuración empresarial no puede eludirse en absoluto.

Jerarquía de Configuración

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

Referencia Completa de settings.json

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

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

Referencia de Variables de Entorno

Autenticación y API:

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

Configuración de modelo:

ANTHROPIC_MODEL=claude-opus-4-6                 # Override default model
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6    # Opus 4.6 (Feb 2026)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
MAX_THINKING_TOKENS=10000                       # Enable extended thinking
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Configuración de proveedores en la nube:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region

Control de comportamiento:

DISABLE_AUTOUPDATER=1                           # Prevent automatic updates
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

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

Interfaz de usuario y terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]

Variables de skills (v2.1.69+):

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

Identidad del llamador 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 impacta significativamente tanto en el costo como en la calidad. Claude Code ofrece cambio flexible de modelos en múltiples niveles.

Modelos disponibles

Opus 4.6 (5 de febrero de 2026): El modelo insignia más reciente con ventana de contexto de 1M tokens, salida máxima de 128K, pensamiento adaptativo y equipos de agentes.⁸⁶ Mismo precio que Opus 4.5 ($5/$25 por MTok). A partir de la v2.1.75 (13 de marzo de 2026), la ventana de contexto de 1M está habilitada por defecto para los planes Max, Team y Enterprise — el sufijo [1m] ya no es necesario para estos niveles.¹²⁴ A partir de la v2.1.77 (17 de marzo de 2026), el límite predeterminado de tokens de salida para Opus 4.6 se incrementa a 64K tokens, con un límite superior de 128K tokens.¹²⁶ El contexto extendido (>200K de entrada) en uso exclusivo de API sigue costando $10/$37.50 por MTok. ID del modelo: claude-opus-4-6.¹

Sonnet 4.6 (17 de febrero de 2026): El nuevo modelo equilibrado que reemplaza a Sonnet 4.5 como opción predeterminada en claude.ai y Claude Cowork.¹⁰⁰ Mismo precio que Sonnet 4.5 ($3/$15 por MTok). Rendimiento mejorado en búsqueda agéntica consumiendo menos tokens. Soporta pensamiento extendido, pensamiento adaptativo y ventana de contexto de 1M tokens (beta). Salida máxima de 64K (límite superior incrementado a 128K en v2.1.77).¹²⁶ Fecha de corte del conocimiento: agosto de 2025 (confiable), enero de 2026 (datos de entrenamiento). ID del modelo: claude-sonnet-4-6. Sonnet 4.5 es ahora un modelo heredado.¹⁰⁰

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 representa $0.10-$0.45 por sesión. Con Opus, la misma sesión cuesta $0.50-$2.25, 5 veces más. Reserva Opus para problemas genuinamente difíciles.¹

Cuándo usar cada modelo

Haiku: Úsalo para subagents que realizan exploración, búsquedas simples de archivos y preguntas rápidas. Es aproximadamente 5 veces más económico 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. Maneja bien la mayoría de las tareas de programación: implementar funciones, corregir errores, escribir pruebas y revisión de código. Úsalo como tu opción predeterminada. Sonnet 4.6 (febrero de 2026) ofrece búsqueda agéntica mejorada y mayor eficiencia en el uso de tokens en comparación con Sonnet 4.5, con soporte para pensamiento adaptativo y la ventana de contexto de 1M en beta.¹⁰⁰

Opus: Resérvalo para razonamiento genuinamente complejo: decisiones arquitectónicas, depuración complicada, comprensión de sistemas complejos y análisis de seguridad. Opus 4.6 (febrero de 2026) representa un avance significativo: planifica con mayor cuidado, sostiene tareas agénticas por más tiempo, opera de manera más confiable en bases de código grandes y detecta mejor sus propios errores durante la revisión de código.⁸⁶ Cuenta con una ventana de contexto de 1M tokens en beta e introduce pensamiento adaptativo que determina automáticamente la profundidad del razonamiento. Según Anthropic, en Terminal-Bench 2.0, Opus 4.6 alcanza la puntuación más alta de la industria en programación agéntica. En GDPval-AA (trabajo de conocimiento económicamente valioso), Anthropic reporta que supera a GPT-5.2 por aproximadamente 144 puntos Elo.⁸⁶ Nota: Los usuarios con suscripción Pro tienen acceso a Opus como parte de su suscripción.²⁰

Opusplan: Un modo híbrido que utiliza Opus para la planificación (donde la calidad del razonamiento es más importante) y Sonnet para la ejecución (donde la velocidad importa). Excelente para refactorizaciones complejas donde deseas el mejor plan pero no necesitas razonamiento de nivel Opus para cada edición individual.

Cambiar de modelo

Durante la sesión:

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

Al iniciar:

claude --model opus

Mediante variable de entorno:

export ANTHROPIC_MODEL=opus

En settings.json:

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

Para subagents específicamente:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Contexto extendido

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

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

O dentro de una sesión:

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

A partir de la v2.1.75 (13 de marzo de 2026), Opus 4.6 usa contexto de 1M por defecto para los planes Max, Team y Enterprise — no se necesita el sufijo [1m].¹²⁴ El sufijo [1m] sigue siendo necesario para Sonnet y para usuarios exclusivos de API.

Opus 4.6 es el primer modelo de clase Opus con soporte nativo de contexto de 1M. Alcanza un 76% de precisión en la variante de 8 agujas y 1M de MRCR v2 (los competidores obtienen aproximadamente un 18.5%), lo que lo convierte en el modelo más potente para recuperación en contexto extenso.⁸⁶

El contexto extendido cuesta más por token (2x en entrada, 1.5x en salida cuando se superan los 200K tokens de entrada). Para Sonnet con [1m], úsalo cuando realmente lo necesites, no como opción predeterminada.

Verificar el modelo actual

> /status

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

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

Modo rápido (v2.1.36+)

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

> /fast            # Toggle fast mode on/off

Precios (modo rápido de Opus 4.6):

Los precios del modo rápido se aplican en toda la ventana de contexto, incluyendo solicitudes con más de 200K tokens de entrada — no hay recargo adicional por contexto extendido en modo rápido.¹ Los precios del modo rápido se acumulan con el almacenamiento en caché de prompts y los multiplicadores de residencia de datos, pero NO con los precios de contexto extendido. El modo rápido no está disponible con la API por lotes.

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

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

El modo rápido de Opus 4.6 ahora incluye la ventana completa de contexto de 1M (v2.1.50+). Anteriormente, el modo rápido estaba limitado al contexto estándar; ahora obtienes la misma capacidad de 1M tokens a la velocidad del modo rápido.¹⁰³

Consejo avanzado: El modo rápido combina bien con el híbrido opusplan: usa el modo rápido durante la fase de ejecución con Sonnet para iteración veloz mientras mantienes las tarifas estándar para la planificación con Opus. Ten en cuenta que /fast requiere que /extra-usage esté habilitado primero (corrección de v2.1.37).⁹³

¿Cuánto cuesta Claude Code?

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

Consultar costos

> /cost

Resultado:

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

Planes de suscripción

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

Precios de tokens de API (febrero de 2026)¹⁸⁶

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

Precios para contexto largo (>200K tokens de entrada):

El umbral de 200K se basa en el total de tokens de entrada (incluyendo lecturas/escrituras de caché). Cuando se supera, Anthropic factura todos los tokens a la tarifa de contexto largo.¹

Precios por residencia de datos: Especificar inferencia exclusiva en EE. UU. mediante inference_geo aplica un multiplicador de 1,1× en todos los precios de tokens (solo modelos Opus 4.6 y superiores).¹

El almacenamiento en caché de prompts reduce significativamente los costos de entrada repetida: las escrituras en caché cuestan 1,25× la tarifa 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%.

API por lotes ofrece descuentos del 50% con entrega en 24 horas para tareas no urgentes como suites de pruebas nocturnas.

Política de cuentas múltiples⁵⁹

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

Lo que está permitido:

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

Lo que está prohibido (según la Política de uso): - Crear cuentas para evadir prohibiciones después de haber sido suspendido - Coordinar actividades maliciosas entre cuentas para evitar la detección - Usar múltiples cuentas para eludir límites de uso o 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) resolvió la situación en 4 horas tras confirmar el uso legítimo. Si usted utiliza Claude Code extensamente tanto para trabajo como para proyectos personales en múltiples cuentas, ese es exactamente el uso para el que está diseñado el servicio, pero no intente manipular el sistema.

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

Factores de costo

Ejemplos de costos reales

Consejo para ahorrar costos: Usar Haiku para subagents de exploración y Sonnet para implementación típicamente reduce 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 por tamaño de equipo:

Tarifas ocultas de herramientas

Más allá del precio por token, algunas herramientas generan cargos adicionales:¹⁶

Estos costos se acumulan en ciclos de agentes. Un ciclo de depuración de 100 iteraciones con Bash genera ~24.500 tokens de entrada adicionales solo en sobrecarga.

Estrategias para reducir costos

1. Use Haiku para subagents: La mayoría de las exploraciones no requieren Sonnet
2. Habilite el almacenamiento en caché de prompts: Está activado por defecto, pero verifique que no esté deshabilitado
3. Establezca un máximo de turnos: claude --max-turns 5 evita conversaciones descontroladas
4. Use el modo plan para exploración: Sin ejecución = sin operaciones costosas accidentales
5. Compacte de forma proactiva: Menor contexto = menos tokens
6. Limite la salida: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. API por lotes para trabajo no urgente: 50% de descuento en tokens de entrada y salida

Monitoreo de uso

• Consola de Claude: platform.claude.com (requiere rol de Admin o Billing)
• Límites de workspace: Establezca límites de gasto por workspace
• Bedrock/Vertex: Use el monitoreo de costos nativo de 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

Típicamente menos de $0,04 por sesión.

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

Acceda programáticamente a las analíticas de uso y métricas de productividad de Claude Code de su 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:

Ejemplo de solicitud:

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

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

Nota: Los datos aparecen dentro de 1 hora de completada la actividad. Solo se incluyen datos con más de 1 hora de antigüedad en las respuestas para mantener la consistencia.

Marcos de Decisión

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

¿Qué modelo debería usar?

INICIO → ¿Es la tarea simple? (búsqueda de archivos, pregunta rápida, formato)
         │
         ├── SÍ → Use Haiku
         │         Costo: ~$0,03/tarea
         │         Velocidad: La más rápida
         │
         └── NO → ¿Requiere razonamiento profundo?
                  (arquitectura, depuración compleja, análisis de seguridad)
                  │
                  ├── SÍ → Use Opus 4.6
                  │         Costo: ~$2,00/tarea
                  │         Calidad: La más alta (contexto de 1M, pensamiento adaptativo)
                  │
                  └── NO → Use Sonnet (predeterminado)
                           Costo: ~$0,75/tarea
                           Equilibrio: El mejor en general

Regla general: Comience con Sonnet. Baje a Haiku para subagents. Escale a Opus 4.6 solo cuando la respuesta de Sonnet se sienta 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?

¿Desea control explícito sobre cuándo se ejecuta?
│
├── SÍ → Use Slash Command
│         Ejemplo: /deploy, /test, /security-review
│         Usted lo invoca. Usted controla el momento.
│
└── NO → ¿Debería aplicarse la experiencia automáticamente según el contexto?
         │
         ├── SÍ → Use Skill
         │         Ejemplo: Patrones de seguridad, reglas de dominio, estándares de código
         │         Claude reconoce el contexto y aplica la experiencia.
         │
         └── NO → ¿El trabajo necesita contexto aislado?
                  │
                  ├── SÍ → ¿Hay una subtarea o muchas subtareas en paralelo?
                  │         │
                  │         ├── UNA → Use Subagent (herramienta Task)
                  │         │         Ejemplo: Exploración profunda, análisis en paralelo
                  │         │         Previene la saturación de contexto en la conversación principal.
                  │         │
                  │         └── MUCHAS → Use Equipo de Agentes (v2.1.32+)
                  │                   Ejemplo: 5 agentes revisando diferentes módulos simultáneamente
                  │                   Opus coordina; cada agente trabaja de forma independiente.
                  │
                  └── NO → Simplemente pregunte directamente
                           No todo necesita abstracción.

¿Hook o Prompt?

¿Debe la acción ocurrir SIEMPRE, independientemente del juicio de Claude?
│
├── SÍ → Use Hook (determinista)
│         Ejemplos:
│         - Formatear código después de cada edición
│         - Registrar todos los comandos bash
│         - Bloquear acceso a archivos .env
│         Claude no puede omitirlo, olvidarlo ni decidir lo contrario.
│
└── NO → Use Prompt (probabilístico)
         Ejemplos:
         - "Considere agregar pruebas"
         - "Piense en casos límite"
         - "Revise la seguridad si es relevante"
         Claude decide según el contexto.

¿Cuándo usar Extended Thinking?

¿Es este un problema genuinamente difícil?
│
├── Decisión arquitectónica con muchas compensaciones → SÍ, use thinking
├── Depuración compleja con causa raíz poco clara → SÍ, use thinking
├── Análisis de seguridad que requiere razonamiento cuidadoso → SÍ, use thinking
├── Comprender una base de código desconocida → SÍ, use thinking
│
├── Corrección de error rutinaria → NO, omita thinking
├── Refactorización simple → NO, omita thinking
├── Formateo de código → NO, omita thinking
└── Preguntas rápidas → NO, omita thinking

Active o desactive con Alt+T durante la sesión. Los presupuestos de pensamiento más altos cuestan más; comience con el mínimo y aumente solo si las respuestas se sienten apresuradas.

Pensamiento adaptativo de Opus 4.6: Opus 4.6 ajusta automáticamente la profundidad de 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. El cambio manual de thinking es más útil con Sonnet cuando desea forzar un análisis más profundo.

¿Qué superficie de ejecución?

¿Dónde debería ejecutarse este trabajo?
│
├── Requiere SUS archivos y herramientas locales
│   │
│   ├── Trabajo interactivo e iterativo → Sesión principal REPL
│   ├── Tarea programada de una sola ejecución → claude -p "prompt" (modo print)
│   ├── Automatización CI/CD → claude -p --json (no interactivo + salida estructurada)
│   └── Tareas paralelas aisladas → Subagents via herramienta Task
│
├── Requiere el entorno de OTRA PERSONA
│   │
│   └── Base de código o servidor remoto → Agente en segundo plano (nube)
│
└── No requiere ningún entorno
    │
    ├── Investigación o análisis → Subagent con tipo Explore
    └── Extracción de contenido web → Herramientas WebFetch / WebSearch

Equipos de Agentes vs Subagents vs Sesiones Paralelas

¿Necesita múltiples agentes trabajando en subtareas relacionadas?
│
├── SÍ → ¿Son las subtareas independientes (sin estado compartido)?
│         │
│         ├── SÍ → ¿Pueden compartir la misma base de código?
│         │         │
│         │         ├── SÍ → Use Equipo de Agentes (v2.1.32+)
│         │         │         Opus coordina. Los agentes comparten acceso al repositorio.
│         │         │         Ejemplo: "Revisar auth, API, y módulos de BD en paralelo"
│         │         │
│         │         └── NO → Use Sesiones Paralelas (terminales separadas)
│         │                  Cada una tiene su propio directorio de trabajo.
│         │                  Ejemplo: "Corregir repo-A y repo-B simultáneamente"
│         │
│         └── NO → Use Subagents Secuenciales
│                  Los resultados de uno alimentan al siguiente.
│                  Ejemplo: "Explorar → Planificar → Implementar"
│
└── NO → Use un Subagent Individual o REPL Principal

¿Qué tipo de Hook?

¿Qué tipo de automatización necesita?
│
├── ¿Ejecutar un comando de shell en un evento específico?
│   │
│   └── Use Command Hook
│       Disparador: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Ejemplo: "Ejecutar prettier después de cada edición de archivo"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── ¿Modificar el prompt del sistema de Claude según el contexto?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Disparador: Los mismos eventos
│       Ejemplo: "Inyectar reglas del proyecto al trabajar en /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── ¿Que Claude haga una evaluación antes de proceder?
    │
    └── Use Agent Hook (v2.1.35+)
        Disparador: Los mismos eventos
        Ejemplo: "Evaluar si este comando bash es seguro antes de ejecutarlo"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

¿Cuándo usar /fast?

¿Es la velocidad de respuesta más importante que la profundidad en este momento?
│
├── SÍ → Use /fast
│         Mismo modelo Opus 4.6, salida más rápida
│         Bueno para: preguntas rápidas, ediciones simples, explicaciones de código,
│                     búsqueda de archivos, tareas de formateo
│
└── NO → Permanezca en modo normal
         Bueno para: decisiones de arquitectura, depuración compleja,
                     revisiones de seguridad, refactorizaciones multi-archivo,
                     cualquier cosa que requiera razonamiento profundo

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

¿Cómo funciona el sistema de permisos?

El sistema de permisos de Claude Code proporciona control detallado sobre qué operaciones pueden ejecutarse. Comprenderlo es esencial tanto para la seguridad como para la eficiencia del flujo de trabajo. Consulta también Enterprise Deployment para configuraciones administradas que aplican permisos a nivel organizacional.

Niveles de permisos

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

Capacidades de la herramienta LSP (v2.0.74+): La herramienta LSP proporciona inteligencia de código similar a un IDE: - Ir a definición: Navegar al lugar donde se define un símbolo - Buscar referencias: Listar todos los usos de un símbolo en todo el código - Documentación emergente: Obtener información de tipos y documentación de cualquier símbolo - Funciona con TypeScript, Python, Go, Rust y otros lenguajes con soporte LSP - Requiere que el servidor de lenguaje esté disponible (normalmente se instala 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 URLs - 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 a menos que se configure explícitamente lo contrario.

Modos de permisos

Modo YOLO (v2.0.68+): Para operación completamente autónoma, usa el flag --dangerously-skip-permissions. Este flag acepta todo: ediciones de archivos, comandos bash, todas las llamadas a herramientas. La palabra “dangerous” es intencional. Úsalo en entornos aislados o cuando confíes plenamente en el código.⁶¹

claude --dangerously-skip-permissions

Establece el modo mediante CLI:

claude --permission-mode acceptEdits

Cambiar 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 por prefijo, no por regex. Un patrón como Bash(curl http:*) no coincidirá con curl -X GET http://... porque las opciones van antes de la URL. Para un bloqueo confiable, deniega el comando completamente: Bash(curl:*).

Patrones de operaciones de 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/**) - comienzan 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 de comodín mcp__server__* para permitir o denegar todas las herramientas de un servidor MCP específico.³⁹ La sintaxis de comodín es útil para habilitar rápidamente todas las herramientas de servidores de confianza o bloquear servidores completos de fuentes no confiables.

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

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

Consejo avanzado: El modo sandbox es excelente para ejecutar Claude en códigos no confiables. Habilítalo al explorar proyectos desconocidos o cuando desees una capa adicional de protección. Las pruebas internas de Anthropic encontraron que el sandboxing reduce las solicitudes de permisos en un 84%.⁴⁵ El sandbox utiliza primitivas a nivel del sistema operativo (seatbelt en macOS, bubblewrap en Linux) para el aislamiento del sistema de archivos y la red, por lo que incluso una inyección de prompt exitosa queda completamente contenida. Anthropic ha publicado como código abierto el runtime del sandbox para equipos que construyen sus propios agentes.⁸⁹

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

¿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 indicarle a Claude que realice acciones mediante prompts, los hooks garantizan la ejecución independientemente del comportamiento del modelo. Son esenciales para hacer cumplir estándares de equipo y automatizar tareas repetitivas. Consulta Decision Frameworks para el árbol de decisión “¿Qué tipo de hook?” que cubre hooks de comando, prompt y agente.

Por qué hooks en lugar de prompts: Decirle a Claude “siempre ejecuta 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 archivo 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 hooks (v2.1.69+): Todos los eventos de hooks ahora incluyen los campos agent_id y agent_type cuando se activan desde un subagent o una sesión --agent, además de un campo worktree en los comandos de hook de la línea de estado.¹¹⁷

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

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

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

Para un control avanzado, los hooks pueden emitir JSON:

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

Control de decisiones en PreToolUse (formato preferido): Los hooks PreToolUse utilizan hookSpecificOutput para un control más detallado: tres resultados posibles (allow/deny/ask) más la capacidad de modificar la entrada de herramientas 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.) siguen usando decision de nivel superior.⁹⁶

Hooks asíncronos (enero de 2026)

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

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

Cuándo usar hooks asíncronos: - Notificaciones (Slack, correo electrónico, Pushover) que no deberían ralentizar la sesión - Registro y telemetría que pueden ejecutarse en segundo plano - Procesamiento posterior no 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 fallo) - Cualquier hook que necesite modificar la entrada/salida de herramientas

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

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

Hooks de prompt (type: "prompt") envían un prompt de un solo turno a un modelo rápido de Claude. El modelo 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
          }
        ]
      }
    ]
  }
}

Hooks HTTP (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 de notificación externos o validación basada en API (v2.1.63+):¹¹¹

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

Los hooks HTTP usan el mismo formato de decisión que los hooks de comando (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 los eventos SessionStart/Setup.

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

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

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

Variables de entorno de hooks

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

Persistir variables de entorno desde SessionStart:

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

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

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

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

Ejemplos prácticos de hooks

Auto-formatear archivos TypeScript después de editar:

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

Registrar todos los comandos bash:

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

Bloquear acceso a archivos sensibles:

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

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

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

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

Sistema de notificaciones personalizado:

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

Inyectar contexto dinámico en los prompts:

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

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

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

Depuración de hooks

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

claude --debug

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

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

Hooks con alcance de componente (v2.1.0+)

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

Skill con hooks integrados:

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

Eventos compatibles: PreToolUse, PostToolUse, Stop

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

Estrategia para sesiones de larga duración

Para sesiones 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 barandillas que obliguen 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. Puerta de finalización: Los hooks Stop verifican todos los criterios de aceptación antes de que Claude declare “listo”
4. Notificación: Los hooks Stop pueden notificarte vía Slack/Pushover cuando Claude termina o se queda atascado

Combina con --dangerously-skip-permissions en un contenedor con sandbox para ejecuciones nocturnas completamente 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 a través de un protocolo estandarizado. El ecosistema ha crecido exponencialmente: 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 IA con herramientas y datos.³⁵⁴ Comprender MCP es esencial para integrar Claude en su 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 su base de datos de producción, crear tickets en Jira, revisar PRs en GitHub, verificar errores en Sentry e interactuar con cualquier API que su equipo utilice, todo mediante solicitudes en lenguaje natural. El protocolo estandariza cómo las herramientas de IA se conectan a servicios externos, evitando la dependencia de un proveedor específico. Consulte Marcos de decisión para obtener orientación sobre cuándo usar MCP en lugar de otros mecanismos de extensión.

Soporte remoto de MCP (junio de 2025)

Claude Code ahora admite servidores MCP remotos con autenticación nativa OAuth.²⁸ Conéctese a herramientas y fuentes de datos sin necesidad de gestionar servidores locales. Solo autentíquese una vez y Claude Code se encargará de la renovación de tokens automáticamente.

# 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

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

Claude Code ahora puede utilizar conectores MCP configurados en su cuenta de claude.ai. Esto cierra la brecha entre la web y CLI: los servidores MCP que haya configurado a través de la interfaz de claude.ai están disponibles automáticamente en Claude Code sin necesidad de reconfigurarlos localmente.¹⁰²

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

Búsqueda de herramientas MCP (v2.1.7+)

A medida que los servidores MCP crecieron en capacidad (algunos exponiendo más de 50 herramientas), las descripciones de herramientas comenzaron a consumir contexto excesivo. La Búsqueda de herramientas MCP 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 MCP - Opus 4.5: 79,5% → 88,1% en evaluaciones MCP - Reducción de 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 aplaza la carga completa de las descripciones hasta que realmente se necesiten. 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 - Siempre activar la búsqueda de herramientas - false - Siempre desactivar (cargar todas las descripciones de herramientas de inmediato) - auto:N - Activar cuando las herramientas superen el N% del contexto (0-100)

Consejo avanzado: Con la Búsqueda de herramientas activada, puede conectar muchos más servidores MCP sin preocuparse por los límites de contexto. La reducción del 95% del contexto significa que los servidores que antes competían por contexto ahora coexisten sin problemas.

Elicitación MCP (v2.1.76+)

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

Integración con hooks: Dos nuevos eventos de hooks — Elicitation (antes de que aparezca el diálogo) y ElicitationResult (después de que el usuario responda) — le permiten interceptar, validar o anular respuestas de elicitación de manera programática. Esto habilita flujos de trabajo empresariales donde las solicitudes de servidores MCP se completan previamente o se restringen según políticas.

Asistente interactivo de configuración MCP

Ejecute claude mcp add sin argumentos para iniciar una interfaz paso a paso para agregar servidores MCP. El asistente lo 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 cmd para stdio:

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

Gestión de alcance

Los servidores MCP existen en tres alcances con precedencia clara (local anula proyecto, proyecto anula usuario):

Especifique el alcance durante la instalación:

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

Formato del archivo de configuración

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

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

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

Comandos de gestión MCP

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

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

Autenticación OAuth

Para servidores que requieren OAuth:

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

Uso de recursos y prompts MCP

Referenciar recursos:

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

Prompts MCP como comandos de barra:

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

Límites de salida

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

Aumente si es necesario:

export MAX_MCP_OUTPUT_TOKENS=50000

Servidores MCP populares

Patrones prácticos de MCP

Flujo de trabajo con GitHub:

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

Consultas a bases de datos:

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

Monitoreo de errores:

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

Configuración empresarial de MCP

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

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@approved/server"] }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" }
  ]
}

Ubicación: - macOS: /Library/Application Support/ClaudeCode/managed-mcp.json - Linux: /etc/claude-code/managed-mcp.json - Windows: C:\ProgramData\ClaudeCode\managed-mcp.json

La lista de denegación tiene precedencia absoluta. Los comandos deben coincidir exactamente, incluyendo el orden de los argumentos.

MCP Apps (enero de 2026)

Anthropic lanzó MCP Apps, una extensión del Model Context Protocol que habilita interfaces de usuario interactivas de herramientas directamente dentro de la interfaz de Claude.⁷⁸ MCP Apps permite a los usuarios ver, editar e interactuar con contenido de servicios externos sin salir de Claude, incluyendo Asana, Box, Canva, Figma, Hex, monday.com y Slack. Cualquier servidor MCP puede proporcionar una interfaz interactiva que se renderiza dentro de Claude. Aunque MCP Apps actualmente aparece en la interfaz web de claude.ai, las extensiones del protocolo MCP subyacentes son relevantes para el ecosistema MCP de Claude Code a medida que los servidores adoptan las nuevas capacidades interactivas.

Plataforma API: Herramienta de ejecución de código v2 (enero de 2026)

Anthropic lanzó la v2 de la Herramienta de ejecución de código en beta pública, reemplazando el sandbox original exclusivo de Python con ejecución de comandos Bash y manipulación directa de archivos.⁷⁹ Cambios principales: - Ejecutar comandos Bash (no solo Python) en contenedores aislados - Escribir y ejecutar código en cualquier lenguaje - Llamadas programáticas a herramientas (también en beta pública): Claude puede invocar herramientas desde dentro de la ejecución de código, reduciendo la latencia y el uso de tokens en flujos de trabajo con múltiples herramientas

La herramienta v2 afecta principalmente a los usuarios de API, pero señala la dirección de las capacidades de ejecución en la nube de Claude Code.

¿Qué son los subagents?

Los subagents son instancias especializadas de Claude que manejan tareas complejas de forma independiente. Son una de las funciones más poderosas de Claude Code y una de las menos comprendidas. Dominar los subagents amplía drásticamente lo que puede lograr. Consulte Marcos de decisión para orientación sobre Agent Teams vs Subagents vs sesiones paralelas.

Por qué existen los subagents: La conversación principal de Claude Code tiene una única ventana de contexto. Todo lo que discute, cada archivo que Claude lee, cada salida de herramienta: todo consume ese contexto. En sesiones largas, el contexto se llena, Claude pierde el seguimiento de decisiones anteriores y el rendimiento se degrada. Los subagents resuelven esto aislando el trabajo: los resultados de exploración no inflan su conversación principal, solo el resumen regresa. Claude también puede ejecutar hasta 10 subagents en paralelo, habilitando trabajo concurrente que sería imposible de forma secuencial.²

Cómo funcionan los subagents

Cuando Claude encuentra una tarea que se beneficia de atención enfocada (exploración profunda, análisis de múltiples pasos, trabajo especializado), puede generar un subagent. El subagent:

1. Comienza con un contexto limpio (sin contaminación de la conversación principal)
2. Tiene acceso a herramientas especificadas
3. Opera con un modelo específico (frecuentemente más económico/rápido)
4. Devuelve resultados a la conversación principal

La arquitectura previene el desbordamiento de contexto mientras habilita flujos de trabajo complejos.

Tipos de subagents integrados

Explore (rápido, solo lectura): - Modelo: Haiku (ultra-rápido) - Modo: Estrictamente solo lectura - Herramientas: Glob, Grep, Read, y comandos bash seguros (ls, git status, git log, git diff, find, cat, head, tail) - Niveles de exhaustividad: Quick, Medium, Very thorough - Uso: Exploración del código base, búsqueda de archivos, comprensión de la estructura

General-purpose: - Modelo: Hereda de la conversación principal - Modo: Lectura/escritura completa - Herramientas: Todas las herramientas disponibles - Uso: Tareas complejas de investigación + modificación

Plan: - Modelo: Hereda de la conversación principal (u Opus con opusplan) - Modo: Solo lectura - Herramientas: Read, Glob, Grep, Bash - Uso: Planificación de implementaciones complejas antes de la ejecución

Activación de subagents

Claude delega automáticamente a subagents según el tipo de tarea. También puede solicitarlos explícitamente:

> Use the explore agent to find all authentication-related files

> Have a subagent analyze the database schema thoroughly

> Spawn an agent to research how error handling works in this codebase

Consejo experto: Para tareas complejas, solicite explícitamente la delegación a subagents. “Use an explore agent to find…” previene la inflación de contexto en su conversación principal.

Creación de subagents personalizados

Defina subagents en .claude/agents/ (proyecto) o ~/.claude/agents/ (personal):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Campos de configuración:

Restricción de subagents generables (v2.1.33+, renombrado v2.1.63): El campo tools soporta la sintaxis Agent(agent_type) para limitar qué tipos de subagent puede generar un agente. Por ejemplo, tools: Read, Grep, Agent(Explore) permite al agente usar Read y Grep directamente pero solo delegar a subagents de tipo Explore. La restricción previene la sobre-delegación en agentes con restricciones. Nota: En v2.1.63, la herramienta Task fue renombrada a Agent. Las referencias existentes Task(...) en configuraciones y definiciones de agentes aún funcionan como alias retrocompatibles.¹¹³

Subagents definidos por CLI (v2.1.32+)

Defina subagents como JSON al iniciar para pruebas rápidas o automatización. Estos existen solo durante la sesión y no se guardan en disco:⁹⁶

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality and security.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

El flag --agents acepta JSON con los mismos campos de frontmatter que los subagents basados en archivos: description, prompt, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, y memory.

Gestión de subagents

> /agents                    # Gestión interactiva
> /agents create             # Crear nuevo subagent
> /agents edit               # Modificar existente
> /agents delete             # Eliminar subagent
> /agents list               # Ver todos

Listado por CLI (v2.1.50+): Liste todos los agentes configurados desde la línea de comandos sin iniciar una sesión interactiva:

claude agents                # Muestra agentes agrupados por origen (integrados, usuario, proyecto, plugin)

Control remoto (v2.1.51+): El subcomando claude remote-control sirve su entorno local para builds externos, permitiendo a todos los usuarios acceder a las capacidades del entorno local de forma remota:¹⁰⁵

claude remote-control                      # Comenzar a servir el entorno local
claude remote-control --name "My Project"  # Título de sesión personalizado visible en claude.ai/code (v2.1.69+)[^117]

Ejecución de agentes en segundo plano

Para tareas de larga duración:

> Run a thorough security review in the background

> /agents  # Check status of running agents

Recupere los resultados más tarde con el ID del agente.

Patrones avanzados

Subagents encadenados:

> First use the code-analyzer subagent to find performance issues, then use the optimizer subagent to fix them

Exploración paralela:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Agentes reanudables: Los agentes pueden reanudarse con su ID para continuar trabajo previo:

> Resume agent abc123 and continue the analysis

Subagents asíncronos (diciembre de 2025)

Los subagents asíncronos habilitan la multitarea y la ejecución paralela para proyectos a gran escala:

> Run security review in the background while I continue frontend work
> /tasks                    # Check status of running agents

Los agentes asíncronos devuelven resultados a través del TaskOutputTool unificado, habilitando flujos de trabajo eficientes estilo pipeline.

Resiliencia ante denegación de permisos (v2.1.0+)

A partir de v2.1.0, los subagents continúan trabajando después de denegaciones de permisos en lugar de detenerse por completo. Cuando un subagent encuentra un muro de permisos, intenta enfoques alternativos automáticamente. El cambio hace que los flujos de trabajo autónomos sean más resilientes y reduce la necesidad de intervención humana.⁴⁷

Agent Teams (febrero de 2026, Research Preview)

Los Agent Teams coordinan múltiples instancias de Claude Code trabajando juntas. Una sesión actúa como team lead, generando teammates que trabajan independientemente en sus propias ventanas de contexto, comunicándose directamente entre sí a través de un buzón compartido y una lista de tareas.⁸⁶⁹¹

A diferencia de los subagents (que se ejecutan dentro de una sola sesión y solo reportan al invocador), los teammates son sesiones independientes completas que pueden enviarse mensajes entre sí, cuestionar los hallazgos del otro y auto-coordinarse.

Habilitar:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

O mediante variable de entorno: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Arquitectura:

Modos de visualización:

Configure en ajustes: "teammateMode": "in-process" o "tmux". O por sesión: claude --teammate-mode in-process.

Controles clave: - Shift+Down: Recorrer teammates (modo in-process; regresa al lead después del último teammate) - Shift+Tab: Habilitar delegate mode (restringe al lead solo a coordinación, sin cambios de código) - Ctrl+T: Alternar lista de tareas compartida - Enter en teammate: Ver su sesión; Escape para interrumpir su turno

Cuándo usar agent teams vs subagents:

Mejores casos de uso: - Investigación y revisión (múltiples perspectivas simultáneamente) - Nuevos módulos/funciones (cada teammate es dueño de piezas separadas) - Depuración con hipótesis competidoras (probar diferentes teorías en paralelo) - Coordinación entre capas (frontend, backend, pruebas cada uno propiedad de un teammate diferente)

Aprobación de plan para teammates: Para tareas complejas o riesgosas, requiera que los teammates planifiquen antes de implementar. El teammate trabaja en modo plan de solo lectura hasta que el lead revise y apruebe su enfoque:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

El lead toma decisiones de aprobación de forma autónoma. Influya en su criterio con condiciones: “only approve plans that include test coverage” o “reject plans that modify the database schema.”

Prompts de ejemplo:

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

Spawn a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.

Almacenamiento: Las configuraciones de equipos se encuentran en ~/.claude/teams/{team-name}/config.json (arreglo de miembros con nombre, ID de agente, tipo de agente). Listas de tareas en ~/.claude/tasks/{team-name}/. Las tareas soportan dependencias: las tareas bloqueadas se desbloquean automáticamente cuando sus dependencias se completan.⁹¹

Integración con hooks: Use los hooks TeammateIdle (código de salida 2 para enviar retroalimentación y mantener al teammate trabajando) y TaskCompleted (código de salida 2 para prevenir la finalización) para aplicar puertas de calidad a los teammates.

Limitaciones (experimental): - Sin reanudación de sesión para teammates in-process (/resume no los restaurará) - Un equipo por sesión; sin equipos anidados - Los teammates no pueden generar sus propios equipos - Los paneles divididos requieren tmux o iTerm2 (no soportado en terminal de VS Code, Windows Terminal, o Ghostty) - Todos los teammates inician con el modo de permisos del lead - Intensivo en tokens: cada teammate es una instancia separada de Claude

Agent Skills (diciembre de 2025)

Los Agent Skills son carpetas organizadas de instrucciones, scripts y recursos que los agentes descubren y cargan dinámicamente.³¹ Proporcionan experiencia de dominio componible y portátil:

.claude/skills/
├── security-review/
│   ├── skill.md           # Instructions and prompts
│   ├── checklist.md       # Security checklist
│   └── common-vulns.sh    # Detection scripts
└── performance-audit/
    ├── skill.md
    └── profiling-guide.md

Los skills difieren de los comandos: los comandos se invocan explícitamente, mientras que los skills se activan automáticamente según el contexto de la tarea. El Claude Agent SDK (renombrado de Claude Code SDK) proporciona el marco para construir agentes personalizados con soporte de skills.³²

¿Qué es el modo de pensamiento extendido?

El pensamiento extendido le da a Claude más tiempo para razonar sobre problemas complejos antes de responder. Es particularmente valioso para decisiones arquitectónicas, depuración de problemas difíciles y tareas que requieren un análisis cuidadoso.

Estado actual (marzo de 2026)

El pensamiento extendido ahora está habilitado por defecto con un presupuesto de 31.999 tokens.⁷⁰ Anthropic realizó este cambio porque el pensamiento extendido mejora significativamente el rendimiento en tareas complejas de planificación y razonamiento.

Niveles de esfuerzo (v2.1.68+, simplificado en v2.1.72): Opus 4.6 utiliza por defecto esfuerzo medio para suscriptores Max y Team — el punto óptimo entre velocidad y profundidad. El nivel de esfuerzo se muestra en el logotipo y el indicador de carga con símbolos simplificados: ○ (bajo), ◐ (medio), ● (alto).¹²¹ La palabra clave “ultrathink” ha sido reintroducida para activar el modo de esfuerzo alto. Otros activadores en lenguaje natural (“think”, “think hard”, “think harder”) siguen obsoletos — use MAX_THINKING_TOKENS o /config en su lugar.⁷⁰¹¹⁶

Nota: Opus 4 y Opus 4.1 han sido eliminados de Claude Code en la API propia (v2.1.68). Los usuarios que tenían estos modelos fijados fueron migrados automáticamente a Opus 4.6.¹¹⁶

Modelos compatibles

• Claude Opus 4.6 (también compatible con pensamiento adaptativo, que determina automáticamente la profundidad del razonamiento)
• Claude Sonnet 4.6 (también compatible con pensamiento adaptativo)
• Claude Opus 4.5
• Claude Sonnet 4.5
• Claude Haiku 4.5

Control del pensamiento extendido

Alternancia rápida durante la sesión:

Press Alt+T to toggle thinking on/off

Nota: Anthropic cambió la alternancia de pensamiento de Tab a Alt+T para evitar activaciones accidentales.³⁹

Mediante /config: Navegue a /config → Extended Thinking para habilitar/deshabilitar o ajustar el presupuesto.

Variable de entorno (permanente):

# Set custom budget (default is 31,999)
export MAX_THINKING_TOKENS=8000
claude

# Double the default for complex tasks
export MAX_THINKING_TOKENS=63999
claude

Deshabilitar para ahorrar costos: Para tareas más simples donde el razonamiento profundo no es necesario, puede reducir costos deshabilitando el pensamiento en /config o reduciendo el presupuesto:

export MAX_THINKING_TOKENS=8000  # Reduce from default 31,999

Presupuestos de tokens de pensamiento

Consideración de costos: Anthropic factura los tokens de pensamiento como tokens de salida. El presupuesto por defecto de 31.999 funciona bien para la mayoría de las tareas, pero para operaciones simples puede ahorrar costos reduciendo el presupuesto o deshabilitando el pensamiento por completo.

Cómo funciona

Cuando el pensamiento está habilitado, Claude realiza un razonamiento interno que influye en la respuesta pero no aparece en la salida. Claude Code cifra el pensamiento y lo devuelve en un campo signature para verificación.

En conversaciones de múltiples turnos con uso de herramientas, los bloques de pensamiento deben enviarse de vuelta a la API para preservar la continuidad del razonamiento. Claude Code maneja esto automáticamente.

Cuándo considerar deshabilitar/reducir

El pensamiento extendido es ahora el valor por defecto, pero considere reducir el presupuesto o deshabilitarlo para: - Ediciones simples de archivos - Refactorización rutinaria - Preguntas rápidas - Formateo de código - Operaciones de alto volumen donde los costos se acumulan

Comportamiento de caché

Claude Code preserva el almacenamiento en caché del prompt del sistema cuando cambian los parámetros de pensamiento. Cambiar el presupuesto de pensamiento o el estado de habilitación entre turnos invalida el almacenamiento en caché de mensajes.

Estilos de salida

Los estilos de salida personalizan cómo Claude presenta la información, lo cual es útil para aprendizaje, documentación o preferencias específicas del equipo.¹⁹

Estilos integrados

Configuración del estilo de salida

> /output-style Explanatory
> /output-style Learning

O mediante la configuración:

{
  "outputStyle": "Explanatory"
}

Estilos de salida personalizados

Créelos en .claude/styles/:

# my-style

## Instructions
- Always explain the WHY behind each decision
- Include relevant documentation links
- Format code examples with comments
- End with a "What to do next" section

## Format
Use markdown headers for organization.
Keep explanations under 200 words per section.

Invoque con /output-style my-style.

Obsoleto (v2.1.73+): /output-style está obsoleto. Use /config para gestionar los estilos de salida en su lugar.¹²²

Comandos Slash

Los comandos slash proporcionan acceso rápido a las funciones de Claude Code y permiten flujos de trabajo personalizados. Son más rápidos que escribir prompts completos para operaciones comunes.

Referencia de Comandos Integrados