Cómo instalar Claude Code en 2026: guía completa paso a paso

Por qué instalar Claude Code y no otro agente de coding?

Claude Code es el agente de programación autónomo de Anthropic. A diferencia de los asistentes de IDE que autocompletan líneas de código, Claude Code opera desde el terminal, lee el repositorio completo, edita múltiples archivos de forma coordinada, ejecuta tests y gestiona Git sin necesitar supervisión continua del desarrollador. A mayo de 2026 es la referencia del mercado en autonomía y calidad de razonamiento para tareas de ingeniería de software complejas.

La instalación es deliberadamente simple: un comando npm y un proceso de autenticación de menos de dos minutos. Esta guía cubre todos los escenarios posibles: instalación estándar en macOS y Linux, instalación en Windows (con WSL2 y en modo nativo), despliegue en contenedor Docker para entornos de CI/CD, y configuración inicial de las integraciones con VS Code y JetBrains.

Los paquetes oficiales se publican en npmjs.com/@anthropic-ai/claude-code y la documentación oficial de instalación está en docs.anthropic.com.

Primera configuración: autenticación y primer comando

Una vez instalado el CLI, el siguiente paso es autenticarte para que Claude Code pueda hacer llamadas a los modelos de Anthropic. Hay dos flujos de autenticación según si usas API key o cuenta de Claude.ai.

Opción A: autenticación con cuenta Claude.ai (OAuth)

Este es el flujo recomendado si tienes una suscripción Pro o Max. Ejecuta el siguiente comando en el terminal:

claude auth login

El CLI abrira una URL en el navegador por defecto. Inicia sesión con tu cuenta de Claude.ai y autoriza la aplicación. El token de sesión se almacena de forma segura en ~/.claude/ y se renueva automáticamente. No necesitas gestionar claves de API manualmente con este método.

Opción B: autenticación con API key de Anthropic

Si prefieres usar una API key (pago por tokens), exporta la variable de entorno antes de ejecutar claude:

# En macOS y Linux (bash/zsh)
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# En Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-api03-..."

# Para que persista entre sesiones, añade la linea a tu .bashrc / .zshrc / perfil de PS

Alternativa: Claude Code también acepta la configuración de la API key via el comando interactivo:

claude config set api-key sk-ant-api03-...

Primera ejecución

Con la autenticación lista, ve al directorio raiz de cualquier repositorio y ejecuta claude:

cd ~/proyectos/mi-proyecto
claude

Claude Code iniciara una sesión interactiva. El agente leera el contexto del repositorio (estructura de archivos, CLAUDE.md si existe, historial de Git reciente) y quedara esperando tu primera instrucción. Puedes escribir en lenguaje natural: "explica la arquitectura de este proyecto" o "encuentra y corrige el bug que hace que el test test_user_auth falle".

Para una primera prueba rápida sin repositorio, claude --print "hola" imprime la respuesta en stdout y sale. Útil para verificar que la autenticación funciona correctamente.

Modo no interactivo (scripts y automatizaciones)

# Ejecutar una tarea y obtener la respuesta en stdout
claude --print "lista todos los archivos PHP del proyecto con mas de 100 lineas"

# Ejecutar con un prompt desde un archivo
claude --print --input-file prompt.txt

Configuración del proyecto con CLAUDE.md y settings.json

La configuración de Claude Code tiene dos niveles: la configuración global del usuario (en ~/.claude/) y la configuración del proyecto (en la raiz del repositorio). La configuración del proyecto tiene prioridad sobre la global cuando hay conflictos.

El archivo CLAUDE.md

CLAUDE.md es el archivo de instrucciones que Claude Code lee automáticamente al iniciar cada sesión en un directorio. Coloca este archivo en la raiz del repositorio. Su proposito es dar contexto al agente sobre el proyecto: stack tecnologico, convenciones de código, archivos protegidos, reglas de commit y cualquier instrucción específica del proyecto.

Ejemplo de CLAUDE.md para un proyecto PHP:

# Instrucciones para Claude Code

## Stack
PHP 8.2, MySQL 8, Apache. Sin frameworks. Sin Composer.

## Reglas de codigo
- Indentar con 4 espacios, nunca tabs.
- Nombres de funciones en snake_case.
- Validar sintaxis con `php -l archivo.php` antes de cualquier cambio.

## Archivos protegidos — nunca los modifiques
- config/config.prod.php
- .env
- deploy.sh (solo bajo instruccion explicita)

## Flujo de commit
- Cada commit debe tener mensaje descriptivo: "tipo: descripcion"
- Tipos validos: feat, fix, refactor, docs, test, chore

Puedes tener un CLAUDE.md global en ~/.claude/CLAUDE.md con instrucciones que apliquen a todos los proyectos, y un CLAUDE.md específico en cada repositorio para instrucciones particulares de ese proyecto. Claude Code combina ambos.

Configuración via settings.json

Para configuración más avanzada, Claude Code usa un archivo settings.json en ~/.claude/settings.json (global) o en .claude/settings.json del proyecto. Ahí se configuran los hooks automáticos, los servidores MCP y los permisos de herramientas:

{
  "model": "claude-sonnet-4-6",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Ejecutando comando shell...' >&2"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Sesion completada'"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/ruta/al/proyecto"]
    }
  }
}

Permisos y nivel de autonomía

Claude Code pregunta confirmación antes de ejecutar acciones potencialmente destructivas (borrar archivos, ejecutar comandos que modifiquen el sistema, hacer push a repositorios remotos). El nivel de confirmación se puede ajustar:

# Ver configuracion actual de permisos
claude config list

# Configurar nivel de autonomia (auto, ask, manual)
claude config set permission-mode auto

En modo auto el agente ejecuta la mayoría de acciones sin pedir confirmación. En modo ask (por defecto) pide confirmación para acciones que modifican el sistema. En modo manual pide confirmación para cada acción individual.

Actualizar y desinstalar Claude Code

Actualizar a la última versión

Claude Code avisa cuando hay una nueva versión disponible al iniciar una sesión. Para actualizar manualmente:

# Si instalaste via npm
npm update -g @anthropic-ai/claude-code

# Si instalaste via Homebrew
brew upgrade claude-code

# Verificar la version instalada
claude --version

Se recomienda mantener Claude Code actualizado ya que las versiones nuevas suelen incluir mejoras de rendimiento, nuevas capacidades del agente y correcciones de seguridad. Las versiones siguen versionado semántico; los cambios de versión menor son compatibles hacia atrás.

Desinstalar Claude Code

# Si instalaste via npm
npm uninstall -g @anthropic-ai/claude-code

# Si instalaste via Homebrew
brew uninstall claude-code

# Limpiar configuracion y datos de sesion (opcional)
rm -rf ~/.claude/

La desinstalación del paquete no elimina los archivos CLAUDE.md de tus proyectos ni el directorio .claude/ local de cada repositorio. Si quieres una limpieza completa, elimina esos archivos y directorios manualmente en cada proyecto.