Hoja de referencia de Claude Code: comandos, configuración y atajos

Todos los flags de CLI, comandos de barra, atajos de teclado, claves de configuración, eventos de hooks y variables de entorno en un solo lugar. Para explicaciones detalladas, consulta la guía completa de Claude Code. Para la configuración inicial, consulta el inicio rápido.

1. Instalación

Tres métodos de instalación, en orden de preferencia.

# Native binary (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew (macOS)
brew install --cask claude-code

# NPM (deprecated — migrate with `claude install`)
npm install -g @anthropic-ai/claude-code

Instala una versión específica:

curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Verifica la instalación:

claude doctor
claude --version

Autentícate:

claude auth login       # Log in or switch accounts
claude auth status      # Check current auth state
claude auth logout      # Clear stored credentials

2. Flags de CLI

Subcomando añadido en v2.1.212: claude auto-mode reset restablece el estado de auto-mode desde la terminal; pasa --yes para omitir la solicitud de confirmación.⁷

3. Slash Commands

Comandos personalizados: Crea .claude/commands/my-command.md (proyecto) o ~/.claude/commands/my-command.md (personal) e invócalo con /my-command. Los comandos admiten frontmatter de YAML para indicar la descripción, las herramientas permitidas, el cambio de modelo y la interpolación de argumentos mediante $ARGUMENTS o los parámetros posicionales $1, $2.

---
description: Fix a GitHub issue
allowed-tools: Read, Edit, Bash(git:*)
model: opus
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

Uso: /fix-issue 123

4. Atajos de teclado

Controles generales

Prefijos rápidos

Entrada multilínea

Puedes personalizar las combinaciones de teclas mediante /keybindings (se almacenan en ~/.claude/keybindings.json).

5. Archivos de configuración

Jerarquía de precedencia (de mayor a menor)

La primera coincidencia prevalece. La configuración empresarial no se puede eludir.

6. Referencia de Settings.json

Configuraciones clave con tipos y ejemplos. Colócalas en cualquiera de los archivos de configuración de la jerarquía anterior.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Read", "Glob", "Grep", "Bash(npm run:*)", "Bash(git:*)", "Edit(src/**)"],
    "deny": ["Read(.env*)", "Bash(rm -rf:*)", "Bash(sudo:*)"],
    "ask": ["WebFetch", "Bash(docker:*)"],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../shared-lib"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {},
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true
  },
  "cleanupPeriodDays": 30,
  "respectGitignore": true,
  "showTurnDuration": true,
  "language": "en",
  "autoMemoryDirectory": ".claude/memory",
  "plansDirectory": ".claude/plans"
}

Sintaxis de las reglas de permisos: Tool(pattern:*) permite la coincidencia por prefijo. Bash(npm run test:*) permite npm run test, npm run test:unit, etc. Los patrones de archivos usan sintaxis glob: Edit(src/**). A partir de v2.1.214, una regla allow dir/** de un solo segmento coincide únicamente con <cwd>/dir, ya no con cualquier dir/ del árbol; escribe Edit(**/src/**) para que coincida a cualquier profundidad. Las reglas deny/ask conservan la coincidencia a cualquier profundidad, y las condiciones if: de los hooks reciben el mismo alcance según el cwd.

Claves nuevas (v2.1.118+):

Para consultar el esquema de configuración completo, revisa el análisis detallado de la configuración en la guía completa.

7. Referencia rápida de CLAUDE.md

CLAUDE.md es el archivo de instrucciones de tu proyecto. Claude lo lee al comienzo de cada sesión.

Dónde se encuentra:

AGENTS.md (v2.1.277+): en un proyecto sin CLAUDE.md, Claude Code lee AGENTS.md en su lugar; cambia este comportamiento en «Project instructions» dentro de /config (aún no está disponible en Bedrock/Vertex/Foundry).

Qué incluir:

# Project Name

## Stack
- Backend: FastAPI, Python 3.11+
- Frontend: HTMX + Alpine.js + Bootstrap 5

## Commands
- Dev: `uvicorn app.main:app --reload --port 8000`
- Test: `python -m pytest -v`
- Lint: `ruff check .`

## Conventions
- Conventional commits: feat:, fix:, docs:, refactor:
- Never force push to main
- Always activate venv before Python commands

## Key Files
- app/main.py — FastAPI app and routes
- app/models.py — SQLAlchemy models

Procura que sea fácil de revisar. La prosa densa desperdicia tokens de contexto en cada sesión. Usa viñetas, tablas y bloques de código breves. Evita los párrafos largos: Claude lee CLAUDE.md al comienzo de cada sesión, por lo que cada palabra consume contexto.

Consejos prácticos: - Usa el prefijo # en el REPL para agregar elementos a la memoria automática sin editar CLAUDE.md: # Always use TypeScript strict mode - El CLAUDE.md de un subdirectorio se carga cuando Claude lee archivos de ese directorio - Coloca las reglas compartidas por el equipo en .claude/rules/*.md para mantener una organización modular

8. Modos de permisos

Desde el 14 de agosto de 2026, Auto Mode (v2.1.85+) es el modo de permisos predeterminado para las sesiones nuevas de los planes Pro, Max y Team (si configuraste un defaultMode, este se conserva hasta que aceptes la solicitud única para cambiarlo; disableAutoMode lo desactiva para toda la organización). Es el reemplazo recomendado de --dangerously-skip-permissions. Las operaciones de solo lectura y las ediciones de archivos se aprueban automáticamente; desde v2.1.281, cuando la revisión del clasificador comenzó a ejecutarse en el servidor, las operaciones de solo lectura y los comandos de shell aislados también esperan su evaluación y se bloquean cuando los marca como peligrosos. Las reglas personalizadas de allow/deny se resuelven primero. Todo lo demás pasa al clasificador de seguridad. Se bloquean automáticamente de forma predeterminada: curl | bash, los force-push a main, los despliegues en producción, las eliminaciones masivas en la nube, los cambios de IAM y el envío externo de datos sensibles.¹

Disyuntor: 3 bloqueos consecutivos o 20 en total durante una sesión hacen que se vuelva a solicitar confirmación manual.

Uso peligroso de rm en modos sin supervisión (v2.1.281): en modo auto y con --dangerously-skip-permissions, la solicitud de confirmación para un rm peligroso espera 2 minutos y luego rechaza el comando con una sugerencia para reformularlo, de modo que la sesión pueda continuar. Un rm recursivo cuyo destino sea únicamente la salida de una sustitución de comando, como rm -rf "$(pwd)", ahora solicita confirmación incluso si existe una regla allow de Bash.

# Enable at startup (--enable-auto-mode was removed in v2.1.111)
claude --permission-mode auto

# Cycle during session
Shift+Tab    # Manual (aka default) -> acceptEdits -> auto -> plan

Aprobación automática de PowerShell (v2.1.119+): los comandos de la herramienta PowerShell se aprueban automáticamente en el modo de permisos de la misma manera que los comandos de Bash. Las reglas allow como PowerShell(Get-*:*) omiten las solicitudes de confirmación para las operaciones de solo lectura. Usa v2.1.149+ en los flujos de trabajo que dependen mucho de PowerShell; corrige la omisión de permisos del comando integrado cd, la coincidencia de reglas allow mediante prefijos y comodines, y el seguimiento desactualizado de variables de directorio.

9. Eventos de hooks

| InstructionsLoaded | Se carga CLAUDE.md | No | | ConfigChange | El archivo de configuración cambia durante la sesión | Sí | | DirectoryAdded | /add-dir o register_repo_root de SDK añade un directorio de trabajo durante la sesión (v2.1.219+) | No | | WorktreeCreate | Se está creando el worktree | Sí | | WorktreeRemove | Se está eliminando el worktree | No | | PreCompact | Antes de compactar el contexto | No | | PostCompact | Después de compactar el contexto | No | | Elicitation | MCP solicita datos estructurados | Sí | | ElicitationResult | El usuario responde al cuadro de diálogo de MCP | Sí | | StopFailure | El turno termina debido a un error de API | No | | PermissionRequest | Se muestra el cuadro de diálogo de permisos | Sí | | PermissionDenied | El modo automático rechaza una acción (v2.1.88+) | No | | CwdChanged | Cambia el directorio de trabajo (v2.1.83+) | No | | FileChanged | Un archivo supervisado se modifica externamente (v2.1.83+) | No | | TaskCreated | Se crea una tarea nueva (v2.1.84+) | No | | TeammateIdle | Un miembro del equipo de agentes queda inactivo | Sí | | TaskCompleted | La tarea se marca como completada | Sí |

Para consultar el protocolo completo de hooks (campos de entrada y salida de JSON, matchers y códigos de salida), consulta el análisis detallado de hooks en la guía completa.

10. Configuración de hooks

Los hooks se encuentran en settings.json o en un archivo específico llamado hooks.json. Ejemplo mínimo:

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

Sintaxis de matchers:

Códigos de salida:

Los hooks asíncronos se ejecutan en segundo plano sin bloquear: añade "async": true al objeto del hook.²

Campos de entrada y salida de hooks:

• duration_ms en la entrada del hook PostToolUse / PostToolUseFailure (v2.1.119+): tiempo de ejecución de la herramienta, sin contar las solicitudes de permiso ni los hooks PreToolUse.
• hookSpecificOutput.updatedToolOutput (v2.1.121+): reemplaza la salida de cualquier herramienta (v2.1.118 introdujo esta función solo para MCP; v2.1.121 la amplía a todas las herramientas).
• hookSpecificOutput.sessionTitle (v2.1.96+): establece el título de la sesión desde un hook UserPromptSubmit.
• args: string[] en hooks de comandos (v2.1.139+): pasa un argv estructurado sin entrecomillado del shell.
• continueOnBlock en hooks PostToolUse (v2.1.139+): devuelve el motivo del bloqueo a Claude y continúa el turno.
• subagent_type en la entrada del hook del agente (v2.1.140+): identifica qué tipo de agente se está ejecutando.
• terminalSequence en la salida de JSON del hook (v2.1.141+): emite secuencias de control de terminal para notificaciones, títulos de ventanas y alertas sonoras.

11. Configuración rápida de MCP

Añade un servidor de MCP con un solo comando:

# Remote HTTP server (recommended)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Remote with auth header
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN"

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

Control del alcance:

claude mcp add --scope project ...   # Team-shared (.mcp.json)
claude mcp add --scope user ...      # Personal (~/.claude.json)

Ejemplo de .mcp.json del 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": "postgresql://user:pass@localhost/db"
      }
    }
  }
}

MCP ya alcanza 100 millones de descargas mensuales y cuenta con más de 3.000 servidores indexados.³ Para conocer los tipos de transporte, la obtención de datos estructurados y la configuración de búsqueda de herramientas, consulta la sección sobre MCP en la guía completa.

alwaysLoad (v2.1.121+): Excluye un servidor de confianza del aplazamiento de Tool Search. Todas sus herramientas se cargan al iniciar la sesión, sin una solicitud adicional de ToolSearch:

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

Reintento automático (v2.1.121+): Los servidores de MCP que presentan un error durante el inicio vuelven a intentarlo hasta 3 veces antes de marcarse como desconectados.

redirectUri de mcp_authenticate de SDK (v2.1.121+): Es obligatorio para completar OAuth con esquemas de URI personalizados, como en aplicaciones de escritorio y flujos de conectores de claude.ai.

11.5. Comandos de CLI para plugins

12. Tipos de subagents

Claude delega automáticamente en subagents. También puedes solicitarlos de forma explícita:

> Use the explore agent to find all auth-related files
> Have a subagent analyze the database schema

Los subagents personalizados se definen en .claude/agents/ (proyecto) o ~/.claude/agents/ (personal) como archivos markdown con frontmatter de YAML. Pueden ejecutarse hasta 10 subagents en paralelo.⁴

claude agents abre Agent View en las versiones actuales: una pantalla operativa en fase preliminar de investigación para las sesiones de Claude Code en ejecución, bloqueadas y completadas. claude agents --cwd <path> limita la vista a un directorio (v2.1.141+); v2.1.142 añade flags de ejecución para sesiones en segundo plano y v2.1.143 los aplica de manera uniforme al panel y a dichas sesiones: --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort y --dangerously-skip-permissions. v2.1.144 añade compatibilidad con /resume para las sesiones en segundo plano y las identifica con bg; v2.1.145 incorpora claude agents --json, recuentos de pestañas pendientes de datos y correcciones en el panel de respuestas de Agent View; v2.1.147 añade sesiones en segundo plano fijadas que permanecen activas cuando están inactivas y se reinician en el mismo lugar para aplicar actualizaciones. Usa Agent View para supervisar, no como prueba de que el trabajo superó los controles de calidad.⁶

Campos del frontmatter de agentes personalizados:

Ejemplo de agente personalizado (.claude/agents/security-reviewer.md):

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

You are a senior security engineer. Analyze for OWASP Top 10 vulnerabilities,
secrets, hardcoded credentials, and SQL injection. Report findings with severity
levels and remediation steps.

13. Variables de entorno

Autenticación y API

Configuración del modelo

Proveedores de servicios en la nube

Control del comportamiento

Configuración de herramientas

Red y proxy

Para consultar la lista completa, revisa Variables de entorno en la guía completa.

14. Referencia de costos

Precios por 1 millón de tokens (a septiembre de 2026).⁵

Una sesión típica consume entre 50K y 200K tokens de entrada y entre 10K y 50K tokens de salida. Sesión con Haiku: $0.10-$0.45. Sesión con Opus 5.5: $0.40-$1.80.

Modelo predeterminado en Claude Code (según el plan): Opus en todos los planes desde v2.1.280 (22 de septiembre de 2026) – Pro y Team Standard pasaron de Sonnet a Opus, al igual que Max, Team Premium y Enterprise – y el modelo Opus predeterminado es Opus 5.5 (claude-opus-5-5), al que ahora apunta el alias opus. La división de v2.1.251 (Opus 5 en los planes prémium y Sonnet 5 en Pro/Team Standard) y Sonnet 5 como opción predeterminada para todos desde v2.1.197 ya son cosa del pasado. Los administradores pueden establecer un valor predeterminado para toda la organización, que aparece como “Valor predeterminado de la organización” en /model (desde v2.1.196). Claude Platform en AWS, Amazon Bedrock y Agent Platform de Google Cloud también usan Opus 5.5 de forma predeterminada; Microsoft Foundry es la única excepción (su valor predeterminado es Sonnet 4.5 y es el único lugar donde opus se resuelve como Opus 4.6) – fija un modelo específico mediante ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL.

Opus 5.5, Sonnet 5, Opus 5, Opus 4.8, Fable 5 y Fable 5.1 solo usan razonamiento adaptativo (sin presupuestos de razonamiento fijos), con /effort xhigh para las tareas de programación o con agentes más exigentes. El valor predeterminado de effort es high en todos ellos, excepto en Opus 5.5, donde es medium – y, desde v2.1.280, un nivel de esfuerzo guardado antes de que /effort se configurara por modelo ya no se transfiere a modelos recién publicados como Opus 5.5, por lo que comienza con su propio valor predeterminado hasta que elijas otro. El razonamiento no puede desactivarse en Opus 5.5 ni en los modelos Fable (MAX_THINKING_TOKENS=0 no surte efecto en ellos). Cambios incompatibles de Opus 5 frente a Opus 4.8: el razonamiento se activa de forma predeterminada en las solicitudes que omiten el campo thinking, y thinking: {type: "disabled"} con el nivel de esfuerzo xhigh o max devuelve un error 400.

El modo rápido (/fast) se aplica a Opus 5.5, Opus 5 y Opus 4.8, y Opus 5.5 es el modelo predeterminado desde v2.1.280 – $8 / $40 por MTok en Opus 5.5, $10 / $50 en Opus 5 y 4.8 (el doble del precio base en cada caso) para obtener hasta 2,5 veces más tokens de salida por segundo. Opus 4.7 se eliminó: claude-opus-4-7 + speed: "fast" ahora produce un error en lugar de recurrir a la velocidad estándar. Vista previa de investigación, disponible solo para Claude API y suscripciones (no para Bedrock/Vertex/Foundry ni Claude Platform en AWS); cambiar de velocidad invalida la caché del prompt. Desde v2.1.271, el modo rápido también funciona en las sesiones remotas de Claude Code (ejecutores en la nube y autoalojados): se aplica la configuración del modo rápido del host o /fast escrito en la sesión cuando tu organización lo permite.

Cambiar de modelo durante una sesión:

/model opus       # Switch to Opus 5.5 (v2.1.280+)
/model sonnet     # Switch to Sonnet 5
/model haiku      # Switch to Haiku 4.5
/model fable      # Switch to Fable 5.1 (tier above Opus, v2.1.257+)
/effort xhigh     # Recommended for the hardest coding/agentic work

Regla de decisión: Usa Haiku para la exploración sencilla. Usa Sonnet para la programación diaria con costos controlados. Usa Opus para el razonamiento complejo, la arquitectura, los ciclos con agentes y el análisis de seguridad. Usa opusplan para refactorizaciones complejas (Opus planifica y Sonnet ejecuta).

15. Ubicaciones de archivos clave

16. Registro de cambios

17. Referencias

Esta hoja de referencia rápida complementa la guía completa de Claude Code CLI. Para consultar los pasos de configuración, revisa la guía de inicio rápido de Claude Code. Para proyectos específicos de iOS y macOS, consulta la guía de desarrollo de agentes para iOS, los patrones de integración de XcodeBuildMCP y la serie sobre el ecosistema de Apple. Última actualización: 17 de julio de 2026.