Claude Code CLI: guía técnica completa en español (2026)

Claude Code CLI es un agente de codificación desarrollado por Anthropic que opera directamente desde la terminal. A diferencia del chat web de Claude, tiene acceso real a tu sistema de archivos, puede ejecutar comandos de shell, gestionar operaciones git y modificar código sin que tengas que copiar y pegar nada manualmente.

La diferencia clave: el chat de Claude responde. Claude Code actúa. Cuando le indicas «refactoriza este módulo y ejecuta los tests», Claude Code lee los archivos, aplica los cambios, lanza los tests y te muestra el resultado — todo en el mismo flujo, sin salir de la terminal.

La arquitectura en tres capas: Core, Delegation, Extension

Entender la arquitectura de Claude Code no es academicismo — determina directamente cuánto cuesta cada operación y qué calidad de output puedes esperar.

Core es el modelo de IA principal que recibe tus instrucciones, razona sobre ellas y decide qué herramientas usar. Delegation es el sistema de subagentes: Claude Code puede lanzar instancias especializadas en paralelo para explorar código, planificar arquitectura o investigar documentación. Extension engloba todo lo que conecta Claude Code con el exterior: hooks (scripts propios que se disparan en momentos del flujo) y servidores MCP (Model Context Protocol — el protocolo de Anthropic para integrar herramientas externas como GitHub, bases de datos o APIs).

Cuándo usar Claude Code CLI y cuándo no usarlo

Claude Code CLI se instala mediante npm como paquete global. El método con curl que circula en algunos tutoriales corresponde a versiones alpha obsoletas — el método oficial y actualizado es npm.

Requisitos del sistema

• Node.js 18 o superior (recomendado: Node.js 20 LTS)
• npm 9+ (incluido con Node.js)
• macOS 12+, Ubuntu 20.04+, Windows 10/11, o cualquier distribución Linux moderna
• Conexión a internet (Claude Code requiere acceso a la API de Anthropic)

Instalación con npm (macOS y Linux)

# Instalar Claude Code CLI globalmente
npm install -g @anthropic-ai/claude-code

# Verificar la instalación
claude --version

# Primer arranque (abre autenticación en el navegador)
claude

Instalación en Windows

En Windows, Claude Code CLI funciona mediante npm en PowerShell o a través de la aplicación de escritorio de Claude (disponible para Windows), que instala la CLI automáticamente. Si usas npm en Windows, asegúrate de ejecutar PowerShell como administrador la primera vez.

# En PowerShell (como administrador)
npm install -g @anthropic-ai/claude-code

# Si npm no está en el PATH, añadir al perfil de PowerShell:
$env:PATH += ";$env:APPDATA\npm"

Solución a los errores más frecuentes de instalación

Claude Code CLI admite dos métodos de autenticación: OAuth mediante el navegador (para suscripciones Pro, Max y Team) y clave de API directa mediante la variable de entorno ANTHROPIC_API_KEY (para uso con la API de Anthropic o entornos enterprise). El primer arranque de claude abre automáticamente el navegador para el flujo OAuth.

Claude Console, suscripción Pro/Max y plataformas enterprise

Qué modelo elegir según la tarea

Claude Code permite seleccionar el modelo de IA subyacente. La elección afecta tanto al coste por token como a la calidad del razonamiento. La familia de modelos disponible a abril de 2026:

Claude Code CLI opera en tres modos principales: el REPL interactivo (la sesión de conversación por defecto), el modo no-interactivo con el flag -p (para scripting y CI/CD), y la reanudación de sesiones previas con --continue. Cada modo tiene un caso de uso distinto — elegir el incorrecto desperdicia tokens o rompe flujos automatizados.

Modo REPL: la sesión interactiva

El modo REPL (Read-Eval-Print Loop — bucle de lectura-evaluación-impresión) es el modo por defecto. Ejecutas claude y entras en una sesión conversacional donde puedes dar instrucciones en lenguaje natural, aprobar o rechazar acciones, y mantener contexto entre mensajes.

# Iniciar sesión REPL
claude

# El prompt de Claude Code aparece y espera tu instrucción
> Analiza el archivo src/auth.py y encuentra posibles vulnerabilidades SQL injection

Cuándo usar -p en lugar del REPL

El flag -p (o --print) ejecuta Claude Code en modo no-interactivo: recibe la instrucción, la ejecuta y termina. No espera más input. Es el modo correcto para scripts de automatización, GitHub Actions, cron jobs y cualquier contexto donde no haya un humano presente.

# Modo no-interactivo: ejecuta y termina
claude -p "Genera tests unitarios para src/utils.py"

# Pasar contexto desde stdin (pipe)
cat error.log | claude -p "Identifica la causa raíz de este error"

# Especificar modelo para la sesión
claude -p "Revisa la arquitectura de este PR" --model claude-opus-4-7

Gestión de sesiones y continuación de contexto

Cada sesión de Claude Code mantiene el historial de la conversación. Con --continue (o -c) reanuudas la última sesión activa, recuperando todo el contexto anterior. Con --resume <session-id> puedes recuperar cualquier sesión anterior por ID.

# Continuar la última sesión
claude --continue

# O con la forma corta
claude -c

# Ver sesiones disponibles
claude --list-sessions

Claude Code CLI usa un sistema de configuración en cascada con cuatro niveles de jerarquía. Cada nivel sobreescribe al anterior en el orden: Enterprise → User → Project → Local. Entender esta jerarquía evita conflictos entre configuración de equipo y configuración personal.

Tabla de niveles de configuración

Configuración de equipo vs. configuración personal

La distinción entre Project y Local es especialmente importante en equipos: .claude/settings.json se commitea al repositorio y aplica a todos los miembros. .claude/settings.local.json se añade al .gitignore y permite que cada desarrollador tenga preferencias personales sin afectar al resto.

// .claude/settings.json — configuración de proyecto (commitear)
{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Bash(npm run test)",
      "Bash(npm run lint)",
      "Read",
      "Edit"
    ]
  }
}

// .claude/settings.local.json — preferencias personales (gitignore)
{
  "model": "claude-opus-4-7",
  "theme": "dark"
}

Claude Code solicita confirmación del usuario antes de ejecutar operaciones con impacto real: escribir archivos, ejecutar comandos de shell o realizar llamadas a red. Este comportamiento es configurable mediante listas de permisos explícitos en settings.json, lo que permite automatizar operaciones habituales sin interrupciones constantes.

Permisos por defecto y cómo modificarlos

Por defecto, Claude Code puede leer archivos libremente. Para escribir, ejecutar comandos o usar herramientas externas, pide aprobación en cada caso. Puedes definir un allowlist (lista blanca) de operaciones preaprobadas para tu proyecto.

// Estructura de permisos en settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(git status)",
      "Bash(git diff)",
      "Bash(git log)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  }
}

Configuración para entornos de CI/CD

En pipelines automatizados donde no hay un humano que apruebe cada acción, Claude Code necesita operar con un modo de permisos más permisivo — pero controlado. El flag --dangerously-skip-permissions desactiva todas las confirmaciones. Úsalo exclusivamente en entornos aislados (contenedores Docker, sandboxes de CI).

Los hooks son comandos de shell que el sistema ejecuta automáticamente en momentos concretos del flujo de Claude Code: antes de que use una herramienta, después, cuando termina, o cuando genera una notificación. La diferencia con instruir a Claude «haz X antes de Y» es fundamental: los hooks son deterministas, no dependen del razonamiento del modelo.

Tipos de hooks disponibles

Ejemplo completo: hook de lint automático tras edición

Este ejemplo configura un hook PostToolUse que ejecuta ESLint automáticamente cada vez que Claude Code edita un archivo JavaScript o TypeScript — sin que tengas que recordar pedírselo.

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>&1 || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code ha terminado\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

MCP (Model Context Protocol — Protocolo de Contexto de Modelo) es el estándar abierto de Anthropic para conectar modelos de IA con herramientas externas. Desde Claude Code CLI, los servidores MCP amplían las capacidades del agente con acceso a GitHub, bases de datos, servicios de monitorización, calendarios o cualquier API que tenga un servidor MCP disponible.

Cómo configurar un servidor MCP

Los servidores MCP se declaran en settings.json bajo la clave mcpServers. Cada servidor es un proceso que Claude Code lanza en segundo plano y con el que se comunica mediante el protocolo MCP.

// ~/.claude/settings.json — servidores MCP
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_tu_token_aqui"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/tu-usuario/proyectos"
      ]
    }
  }
}

Casos de uso reales: GitHub, bases de datos, Sentry

Claude Code puede lanzar subagentes — instancias especializadas del modelo que operan en paralelo o en secuencia para resolver partes de una tarea compleja. Cada subagente arranca con contexto propio, lo que protege la ventana de contexto del agente principal y permite paralelizar trabajo.

Tipos de subagentes disponibles

Cuándo lanzar un subagente y cuándo no vale la pena

Los subagentes tienen un coste: cada instancia adicional consume tokens del modelo y añade latencia. No tiene sentido lanzar un subagente Explore para buscar una función en un archivo que ya tienes en contexto — el agente principal lo hará más rápido.

Los comandos slash son instrucciones especiales que Claude Code reconoce dentro del REPL para controlar el comportamiento de la sesión. La memoria persistente es un sistema de archivos Markdown en ~/.claude/ que mantiene contexto entre sesiones distintas — el equivalente a la memoria a largo plazo del agente.

Comandos más útiles para el trabajo diario

Sistema de memoria: qué persiste entre sesiones

Claude Code almacena memorias como archivos Markdown en ~/.claude/projects/, organizados por proyecto. Existen cuatro tipos: user (perfil y preferencias del desarrollador), feedback (correcciones y confirmaciones de comportamiento), project (contexto activo del proyecto: decisiones, deadlines, deuda técnica) y reference (punteros a recursos externos como tableros de Jira o dashboards de Grafana).

Claude Code CLI integra git de forma nativa: puede leer diffs, crear commits, gestionar ramas y abrir pull requests sin salir del REPL. En pipelines de CI/CD, el modo no-interactivo con -p permite automatizar tareas de análisis y generación de código como un paso más del workflow.

Flujo de trabajo con git desde Claude Code CLI

# Flujo git completo desde Claude Code CLI

# Crear rama y hacer cambios
claude -p "Crea una rama feature/auth-refactor, refactoriza src/auth.py eliminando duplicados y commitea con mensaje descriptivo"

# Revisar y abrir PR
claude -p "Revisa los cambios en la rama actual vs main y crea un PR con título y descripción detallada"

Uso de Claude Code CLI en pipelines automatizados

El siguiente ejemplo muestra un paso de GitHub Actions que usa Claude Code para analizar automáticamente los cambios de un PR y publicar un comentario con el resumen de riesgos:

# .github/workflows/claude-review.yml
name: Claude Code PR Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run analysis
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "Analiza los cambios de este PR, identifica riesgos de seguridad y genera un informe en review-output.md"

¿Claude Code CLI es de pago?

Claude Code CLI está incluido en las suscripciones Claude Pro y Max de Anthropic — no hay un coste adicional por instalarlo ni usarlo dentro del límite de uso de tu plan. Si accedes mediante API Key directa (sin suscripción), pagas por tokens consumidos según la tarifa de la API de Anthropic. Para equipos, existe Claude for Teams con facturación por asiento.

¿Cuál es la diferencia entre Claude Code CLI y Cursor o GitHub Copilot?

Cursor y GitHub Copilot son herramientas que operan principalmente dentro del IDE: sugieren código inline, completan funciones y responden preguntas en un panel lateral. Claude Code CLI opera desde la terminal con acceso completo al sistema de archivos y capacidad de ejecutar comandos — es un agente que puede tomar acciones en tu proyecto, no solo sugerir código. Las tres herramientas son complementarias: muchos desarrolladores usan Claude Code para refactoring y análisis profundo, y Copilot para autocompletado rápido en el editor.

¿Funciona Claude Code CLI sin conexión a internet?

No. Claude Code requiere conexión a internet en todo momento — el modelo de IA reside en los servidores de Anthropic, no en local. No hay una versión offline de Claude Code CLI.

¿Mi código se envía a Anthropic y se usa para entrenamiento?

El código que Claude Code lee y procesa se envía a la API de Anthropic para generar las respuestas. Según la política de uso de Anthropic (actualizada en 2024), el contenido enviado mediante la API no se usa para entrenar modelos por defecto. Para suscripciones Enterprise, Anthropic ofrece acuerdos adicionales de privacidad de datos. Revisa siempre la política de privacidad actual en anthropic.com/privacy para información actualizada.

¿Claude Code CLI es compatible con Windows?

Sí. Claude Code CLI funciona en Windows mediante npm (requiere Node.js 18+) o a través de la aplicación de escritorio Claude para Windows, que instala la CLI automáticamente. El funcionamiento en Windows es equivalente al de macOS y Linux, aunque algunos hooks que dependen de comandos Unix (como osascript para notificaciones macOS) necesitan adaptarse a equivalentes de Windows.

¿Cómo se gestiona Claude Code en un equipo de varios desarrolladores?

El sistema de configuración en cascada está diseñado precisamente para equipos: commitea .claude/settings.json con las reglas del proyecto (modelo, permisos de herramientas permitidas, hooks de lint/test) y deja que cada desarrollador personalice su experiencia en .claude/settings.local.json (ignorado por git). El archivo CLAUDE.md en la raíz del repositorio actúa como documentación del proyecto que todos los miembros del equipo comparten.

¿Cuánto contexto puede manejar Claude Code por sesión?

El límite de contexto depende del modelo seleccionado. Claude Sonnet 4.6 y Opus 4.7 disponen de hasta 200.000 tokens de contexto (aproximadamente 150.000 palabras o un repositorio de tamaño mediano). En la práctica, sesiones de trabajo largas acumulan historial que consume ese límite gradualmente — usa /compact regularmente para comprimir el historial y liberar espacio de contexto sin perder el hilo de la conversación.