Instalación de Claude Code y Conexión de tu Primer Proyecto
Claude Code se instala una vez desde tu terminal, y luego se lanza desde dentro de cualquier directorio de proyecto en el que quieras que funcione.
Esta página recorre esa configuración de principio a fin: instalación, conexión a un proyecto real y ejecución de una primera solicitud.
Resumen
Instalar Claude Code es un único comando CLI, similar a instalar cualquier otra herramienta de desarrollador global.
Una vez instalado, la CLI no tiene una conexión persistente con un proyecto hasta que lo lanzas desde dentro del directorio de ese proyecto.
Cada sesión comienza de nuevo en la carpeta en la que te encontrabas cuando escribiste el comando de lanzamiento.
La primera sesión en un proyecto nuevo es un buen momento para permitir que Claude Code se oriente antes de pedirle algo complejo.
Conseguir que esta configuración inicial sea correcta evita la mayoría de las confusiones con las que los nuevos usuarios se encuentran en su primera semana.
Receta
Tarjeta de referencia rápida - lista para copiar y pegar.
# 1. Instala la CLI globalmente
npm install -g @anthropic-ai/claude-code
# 2. Confirma que se instaló
claude --version
# 3. Muévete al proyecto con el que quieres ayuda
cd ~/projects/my-app
# 4. Lanza la sesión interactiva
claudeCuándo usar esto:
- La primera vez que configuras Claude Code en una máquina nueva.
- Conectar Claude Code a un proyecto en el que no ha trabajado antes.
- Incorporar a un nuevo desarrollador a un equipo que ya utiliza Claude Code.
- Reinstalar después de cambiar de máquina o actualizar tu cadena de herramientas de Node.js.
Ejemplo de Trabajo
# Un recorrido completo de la primera sesión, desde una terminal limpia
# Instala la CLI (Node.js y npm deben estar instalados previamente)
npm install -g @anthropic-ai/claude-code
# Verifica la instalación
claude --version
# Navega al proyecto que quieres conectar
cd ~/projects/my-app
# Lanza Claude Code en ese proyecto
claude
# En el prompt que se abre, describe tu primera tarea en lenguaje natural
> Resume de qué trata este proyecto y lista sus dependencias principalesLo que esto demuestra:
- El paso de instalación es una acción global única, independiente de cualquier proyecto específico.
- Conectar a un proyecto es simplemente cuestión de usar
cdpara entrar en él antes de lanzarlo. - Una buena primera solicitud pide a Claude Code que resuma u oriente, lo que te permite verificar que leyó el proyecto correctamente.
- La sesión abre un prompt REPL (
>) donde se escribe cada solicitud posterior.
Profundización
Cómo Funciona
- La CLI en sí misma es un pequeño binario; el trabajo real del agente ocurre en una sesión que comienza una vez que ejecutas
claudedesde un directorio. - Al lanzar, Claude Code lee el directorio de trabajo actual como la raíz del proyecto y comienza a construir contexto sobre él.
- No hay un paso de "conexión" separado más allá de lanzar desde la carpeta correcta; la CLI no requiere que registres un proyecto con antelación.
- La autenticación ocurre una vez por máquina (o sesión, dependiendo de tu configuración) y está separada del paso de conexión por proyecto.
Lista de Verificación de la Primera Sesión
| Paso | Por qué es importante |
|---|---|
Confirmar que claude --version funciona | Confirma que la instalación y PATH son correctos antes de depender de ella |
cd al directorio raíz real del proyecto | Claude Code lee desde el directorio actual, no desde una ruta que escribes más tarde |
| Hacer una pregunta de orientación primero | Confirma que leyó el proyecto correctamente antes de delegar trabajo real |
| Elegir un modo de permiso de inicio | Decide de antemano si quieres indicaciones de aprobación en esta primera sesión |
Notas de la CLI
# Actualiza a la última versión más adelante
npm update -g @anthropic-ai/claude-code
# Comprueba dónde está instalado el binario si `claude` no se encuentra
npm root -gErrores Comunes
- Lanzar desde el directorio incorrecto - Claude Code lee el directorio de trabajo actual como la raíz del proyecto, por lo que lanzarlo desde tu carpeta de inicio en lugar de la carpeta del proyecto le da el contexto incorrecto. Solución: siempre usa
cden el directorio raíz real del proyecto antes de ejecutarclaude. - Asumir que la instalación lo conecta automáticamente a un proyecto - la instalación de la CLI es global y agnóstica al proyecto; no recuerda ni se adjunta a ningún proyecto específico hasta que lo lanzas desde dentro de uno. Solución: trata cada lanzamiento de
claudecomo una nueva conexión limitada al directorio actual. - Omitir la verificación de versión - un
PATHroto después de la instalación puede hacer queclauderesuelva silenciosamente a nada o a una versión antigua en caché. Solución: ejecutaclaude --versioninmediatamente después de instalar, antes de comenzar el trabajo real. - Saltar directamente a una solicitud compleja - pedir un cambio grande de varios archivos antes de que Claude Code tenga contexto sobre el proyecto produce un plan más débil. Solución: comienza con una solicitud de orientación pequeña para que lea los archivos relevantes primero.
- Olvidar que Node.js es un requisito previo - la CLI se instala a través de
npm, por lo que una instalación de Node.js faltante o muy antigua hará que el comando de instalación falle por completo. Solución: confirma quenode --versionynpm --versionfuncionan antes de instalar Claude Code.
Alternativas
| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
Lanzar con claude y sin flags | Quieres tus valores predeterminados configurados para el modo de permiso | Necesitas un modo de permiso específico solo para esta sesión |
| Lanzar con un flag de permiso explícito | Quieres estar seguro del modo para una sesión única | Ya tienes un valor predeterminado a nivel de proyecto en el que confías |
| Reinstalar desde cero | Tu instalación está rota o muy desactualizada | Una simple npm update -g arreglaría el mismo problema más rápido |
Preguntas Frecuentes
¿Necesito instalar Claude Code por separado para cada proyecto?
No. La instalación es global, se hace una vez por máquina. Conectar a un proyecto específico solo significa lanzar claude desde dentro del directorio de ese proyecto.
¿Qué necesito tener instalado antes de poder instalar Claude Code?
- Node.js y npm, ya que la CLI se instala como un paquete global de npm.
- Una terminal en la que puedas ejecutar comandos.
- Una cuenta de Anthropic con acceso a Claude Code para la autenticación.
¿Cómo sé que la instalación realmente funcionó?
Ejecuta claude --version justo después de instalar. Un número de versión de vuelta confirma que tanto la instalación como tu PATH son correctos.
¿Qué sucede si lanzo `claude` desde la carpeta incorrecta?
Claude Code trata cualquier directorio desde el que lanzaste como la raíz del proyecto, por lo que leerá y razonará sobre los archivos incorrectos. Sal, usa cd en el proyecto correcto y relanza.
¿Cuál debería ser mi primera solicitud en un proyecto nuevo?
Algo de bajo riesgo y orientador, como pedirle que resuma el proyecto o liste sus dependencias. Esto confirma que leyó el proyecto correctamente antes de que delegues trabajo real.
¿Existe un archivo de configuración a nivel de proyecto, o todo es por sesión?
Existe configuración a nivel de proyecto para cosas como los valores predeterminados de permiso, pero el paso de conexión principal es simplemente lanzar desde el directorio del proyecto cada vez; no hay un paso de registro separado.
¿Puedo usar Claude Code en más de un proyecto a la vez?
Sí, pero cada sesión está limitada al directorio desde el que la lanzaste. Trabajar en dos proyectos a la vez significa ejecutar dos sesiones separadas, típicamente en dos pestañas de terminal.
¿Necesito elegir un modo de permiso antes de mi primera sesión?
Ayuda. Decidir de antemano si quieres pedir confirmación siempre o aceptar automáticamente para esa primera sesión evita sorpresas, especialmente en una base de código desconocida o importante.
¿Cómo actualizo Claude Code después de que está instalado?
npm update -g @anthropic-ai/claude-codeEjecuta claude --version después para confirmar que la actualización tuvo efecto.
¿Qué pasa si `claude` no se encuentra después de instalar?
Esto generalmente significa que el directorio de binarios globales de npm no está en el PATH de tu shell. Ejecuta npm root -g para encontrar dónde se instalan los paquetes globales y confirma que el directorio de binarios correspondiente está en tu PATH.
¿Requiere la instalación de Claude Code sudo o derechos de administrador?
Depende de cómo estén configuradas tus instalaciones globales de npm en tu máquina. Si encuentras errores de permiso, eso es una señal de que tu directorio global de npm necesita ajustarse en lugar de algo específico de Claude Code.
Relacionado
- Conceptos Básicos de Claude Code 101 - un conjunto más completo de ejemplos de primera sesión más allá de la instalación y conexión.
- El Modelo Mental de Claude Code: Agente, No Autocompletado - qué esperar una vez que tu primera sesión esté en funcionamiento.
- Navegando el REPL de Claude Code: Prompts y Comandos de Barra Diagonal - cómo usar la sesión una vez que está conectada.
- Modos de Permiso Explicados: Aceptación Automática vs. Preguntar Siempre - decide tu modo de inicio antes de tu primera solicitud real.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.