Integración con VS Code

📚 Navegación de la serie: El artículo anterior 07 · Primera vez de uso te guió para ejecutar tu primer ejemplo en la terminal. Este artículo lleva Claude Code a VS Code, ofreciendo las mismas capacidades pero con la jugabilidad de una interfaz gráfica.

Cuando apenas haces la transición para usar la extensión de VS Code, es muy fácil cometer un error bastante tonto.

Siendo que Claude Code funcionaba tan bien en la terminal, al instalar la extensión quieres probar la interfaz gráfica. Abres una carpeta vacía, miras a la izquierda y a la derecha, y simplemente no puedes encontrar el famoso "icono de Spark" del que habla el equipo oficial (el icono en forma de chispa en la barra de herramientas, que es el punto de entrada de Claude Code en el IDE). En ese momento, es fácil pensar que la instalación falló. Desinstalas, reinstalas, reinicias, limpias el caché, y después de casi veinte minutos de lucha, finalmente miras la documentación y descubres que... ese icono solo aparece cuando abres un archivo específico, no basta con abrir una carpeta. Buscando el icono en un espacio de trabajo vacío, podrías buscarlo toda la vida sin encontrarlo.

Para decirlo sin rodeos, la integración con VS Code no es difícil, pero tiene una lógica de interacción diferente a la de la terminal. Algunas cosas que das por "obvias" pueden dejarte atascado en el primer paso. Este artículo te señalará esas trampas con antelación.

Después de leer este artículo, obtendrás:

• Los pasos completos para instalar la extensión Claude Code en VS Code (incluyendo forks como Cursor), además de una lista de verificación para solucionar el problema de "no encuentro el icono".
• Cómo usar los tres placeres exclusivos de la interfaz gráfica: diff lado a lado (revisión de cambios línea por línea), menciones con @ y revisión de planes.
• Una tabla de comparación sobre "¿debería usar la extensión o la CLI?", además de un conjunto de atajos de teclado útiles.

---

01 Primero lo primero: ¿Cuál es la relación entre la extensión y la CLI?

"Ya sé cómo usar claude en la terminal, ¿tengo que instalar la extensión?". La conclusión primero: La extensión no es un reemplazo de la CLI, es solo una interfaz gráfica superpuesta a ella. Instalar la extensión traerá la CLI consigo, y ambas comparten la misma configuración en ~/.claude/settings.json. El historial de conversación se puede restaurar, pero no se sincroniza en tiempo real: si estás a mitad de una charla en la extensión, más tarde puedes ejecutar claude --resume en la terminal para retomar proactivamente esa conversación.

Analogía: La misma cocina, dos ventanillas de pedidos. La CLI es como gritar tu orden en la ventana de la cocina: rápido, completo, puedes pedir lo que sea. La extensión es el camarero en el comedor: te hace el menú ilustrado, pedir y ver el progreso es más visual, pero hay algunos elementos del "menú secreto" que solo puedes pedir en la ventana. La cocina es la misma, la comida es exactamente la misma.

Entonces, ¿cuándo usar cuál? El equipo oficial proporciona una tabla de capacidades, que se resume a continuación:

Función	CLI (Terminal)	Extensión de VS Code
Comandos y skills	Todos	Subconjunto (Escribe / para ver los disponibles)
Configuración de servidor MCP	Completa	Parcial (Agrega con CLI, gestiona en el panel con /mcp)
Checkpoints (Puntos de control)	Soportado	Soportado
Atajo de bash !	Soportado	No soportado
Autocompletado con Tab	Soportado	No soportado
Diff lado a lado, contexto por código seleccionado	Requiere conectar el IDE	Nativo, listo para usar

En una frase: Para trabajos relacionados con archivos, como escribir código o revisar cambios, la extensión es claramente mejor; los atajos de bash como !ls y el autocompletado con Tab solo están en la CLI. El uso típico es trabajar principalmente en la extensión, y si necesitas ejecutar comandos en bloque o usar comandos que no están en la extensión, simplemente tecleas claude directamente en la terminal integrada: el historial está conectado, el cambio es fluido.

💡 Resumen en una frase: La extensión y la CLI son dos caras del mismo motor, comparten historial y configuración, cámbialas en cualquier momento según la tarea en cuestión, no tienes que elegir una o la otra.

---

02 Instalación: Tres métodos y qué hacer si no encuentras el icono

Revisa la versión antes de instalar

El requisito estricto oficial es: VS Code 1.98.0 o superior; por debajo de esta versión, no se instalará o no funcionará (ve a "Ayuda → Acerca de" para ver el número de versión). Al abrir la extensión por primera vez, te pedirá iniciar sesión en tu cuenta de Anthropic; para empresas que usan proveedores de terceros como Bedrock, Vertex AI, etc., la configuración es diferente, y se menciona por separado al final.

Tres métodos de instalación

Método uno: Buscar en el mercado de extensiones (el más seguro, recomendado para principiantes)

En VS Code, presiona Cmd+Shift+X (Mac) o Ctrl+Shift+X (Windows/Linux) para abrir la vista de Extensiones, busca Claude Code y haz clic en Instalar.

La imagen de arriba muestra cómo se ve buscar Claude Code en la vista de extensiones: el elemento enmarcado en rojo "Claude Code for VS Code", con el publicador Anthropic que tiene una marca de verificación azul, es el oficial. Asegúrate de hacer clic en instalar ese.

Aquí hay la trampa en la que los novatos caen más fácilmente: buscar Claude Code arrojará un montón de extensiones con nombres similares, asegúrate de que el editor sea Anthropic, no instales una falsificación de terceros.

Método dos: Instalar directamente mediante un enlace

Teniendo VS Code abierto, hacer clic en el enlace vscode:extension/anthropic.claude-code te llevará directamente a la página de instalación de la extensión (en Cursor, cambia vscode: por cursor:).

Método tres: Editores alternativos / cuando no se puede instalar

La extensión también se puede instalar en otras ramificaciones de VS Code (Cursor, Devin Desktop, Kiro, etc.): busca Claude Code en su vista de extensiones, o instálala desde el registro Open VSX. Si por alguna razón no puedes instalarla, no te obstines, la solución de respaldo oficial es simplemente ejecutar claude en la terminal integrada.

Nota para China: La instalación, autorización de inicio de sesión, y dejar que Claude trabaje más tarde requerirán conexión a los servidores de Anthropic. Todo el proceso requiere magia de internet (VPN), igual que con la versión de terminal.

¿Instalado pero no encuentras el icono? Revisa esta lista de verificación

Esta es la trampa del principio. Tras la instalación, la extensión no muestra una ventana emergente por defecto, tienes que abrir el panel tú mismo. La forma más rápida: primero abre un archivo específico, luego haz clic en el icono de Spark en la barra de herramientas de la parte superior derecha del editor (un icono que parece una pequeña chispa).

La imagen de arriba resalta las ubicaciones de los tres puntos de entrada: el icono de Spark en la esquina superior derecha del editor (②, el más rápido pero solo aparece cuando un archivo está abierto), el Spark en la barra de actividad (①, siempre está ahí), y la ✱ Claude Code en la barra de estado (③, se puede hacer clic aunque no haya archivos abiertos).

El punto clave en una oración: El icono de Spark solo aparece cuando tienes un archivo abierto, solo abrir una carpeta no es suficiente. Si aún no puedes verlo, verifica en este orden oficial:

Síntoma	Acción a tomar
No hay icono en la esquina superior derecha del editor	Primero abre un archivo (no solo una carpeta)
Archivo abierto pero sigue sin aparecer	Confirma que VS Code es ≥ 1.98.0 (Ayuda → Acerca de)
La versión es correcta	Ejecuta Developer: Reload Window en la paleta de comandos para recargar la ventana
Recargar no ayudó	Desactiva temporalmente otras extensiones de IA (Cline, Continue, etc.), podría ser un conflicto
El espacio de trabajo está en "Modo Restringido"	La extensión no funciona en modo restringido, necesitas confiar en el espacio de trabajo

Si de verdad no puedes encontrar el icono de Spark, aquí hay dos alternativas:

• En la Barra de Actividad (la columna de iconos más a la izquierda): hay un icono de Spark: este siempre está ahí, si haces clic en él verás tu lista de sesiones.
• En la Barra de Estado (esquina inferior derecha de la ventana): ✱ Claude Code: puedes hacer clic en él aunque no haya un archivo abierto, por lo general este es más conveniente para no tener que preocuparse de si tienes un archivo abierto o no. También puedes usar la Paleta de Comandos (Cmd+Shift+P / Ctrl+Shift+P) y escribir Claude Code.

La primera vez que abras el panel aparecerá una pantalla de inicio de sesión, haz clic en Login, completa la autorización en el navegador y listo. (Si configuraste ANTHROPIC_API_KEY pero aún se te pide iniciar sesión, probablemente VS Code no heredó la variable de entorno de la terminal; la solución oficial es iniciar VS Code desde la terminal usando code . para arrastrar las variables).

💡 Resumen en una frase: Al instalar la extensión busca al editor Anthropic, el icono de Spark requiere que un archivo esté abierto para aparecer; si no puedes encontrarlo, primero abre un archivo, o si no funciona, usa la entrada de la barra de estado en la parte inferior derecha.

---

03 Vista Diff: Compara los cambios cara a cara y aprueba después de ver

Esta es la característica que atrapa a muchos usuarios desde el principio. Al modificar archivos en la versión de terminal, el diff se dibuja con caracteres de texto, por lo que cuando el archivo es grande y hay muchos cambios, es agotador leerlo. La extensión traslada esto a la vista diff nativa de VS Code: resaltados en rojo y verde para las adiciones y eliminaciones, lo mismo que cuando miras un diff de Git.

Analogía: Una comparación de "modo revisión" antes de firmar un contrato. La otra parte envía el contrato revisado con el borrador original a la izquierda y la versión revisada a la derecha, con cada adición o eliminación claramente marcada, por lo que no estás firmando a ciegas, sino revisando cláusula por cláusula antes de poner la pluma. Cuando Claude modifica el código, es igual; presenta los cambios y pide permiso, y tienes tres opciones: Aceptar, Rechazar, o decirle directamente que lo cambie por otra cosa.

También hay un detalle que es fácil pasar por alto y que solo notas después de usarlo por un tiempo: antes de aceptar, puedes modificar directamente la sugerencia de Claude a mano dentro de la vista diff. Una vez que lo cambies, él sabrá que "lo modificaste" y no continuará con la versión anterior. Por ejemplo, le pides que refactorice una función de más de 200 líneas y realiza siete u ocho cambios de una vez. Si notas con un vistazo en el diff que la lógica de comprobación de los límites en un lugar está invertida, corrígelo directamente en el lado derecho y luego acéptalo, lo que te ahorra un ciclo de ida y vuelta.

💡 Resumen en una frase: La vista diff pone cada cambio frente a ti, míralo claramente, cámbialo en el lugar y luego decide si lo aceptas; mucho más seguro que el diff de texto en la terminal.

---

04 Mención con @ y Selección de Código: Alimentando el contexto con precisión

El mayor desperdicio al dejar que Claude trabaje es que "no sabe de qué código estás hablando", por lo que pierde el tiempo adivinando. En la extensión, hay dos trucos para alimentar el contexto de forma rápida y precisa.

Truco uno: Mencionar con @ archivos / carpetas

En el cuadro de entrada, escribe @, seguido de un archivo o nombre de carpeta, y Claude irá y leerá ese contenido. Soporta coincidencia difusa (fuzzy match), por lo que no tienes que escribir el nombre completo:

> Explica la lógica en @auth (coincidirá automáticamente con auth.js, AuthService.ts, etc.)
> ¿Qué hay en @src/components/ ? (¡Recuerda agregar la barra / al final para las carpetas!)

Analogía: Dejar caer los documentos en el chat del grupo antes de la reunión. En lugar de decir verbalmente "ya sabes, ese archivo relacionado con el inicio de sesión", es mejor @ enviar directamente el archivo, lo que le evita hurgar y adivinar incorrectamente en todo el proyecto. En el caso de archivos PDF súper grandes, incluso puedes decirle que solo lea páginas específicas (p. ej., páginas 1-10), en lugar de leer el documento completo.

Truco dos: Selecciona el código y él lo verá automáticamente

Este truco ahorra aún más esfuerzo que @: solo tienes que seleccionar una porción de código en el editor y Claude lo verá automáticamente. Un mensaje de "XX líneas seleccionadas" aparecerá debajo del cuadro de entrada. Simplemente preguntas "¿Por qué da error esto?", y él sabrá exactamente a qué porción te refieres.

Unas cuantas técnicas complementarias:

• Insertar referencias con números de línea: Presiona Option+K / Alt+K, para insertar automáticamente una referencia con la ruta y los números de línea, como @app.ts#5-10 (requiere que el editor tenga el foco).
• Ocultar temporalmente la selección: Haz clic en el "indicador de selección" en la parte inferior del cuadro de entrada para alternar; si aparece un icono de un "ojo con una barra", significa que esta porción está oculta a Claude, es decir, seleccionaste el texto pero solo porque querías copiarlo.
• Arrastrar archivos como anexos: Mantén presionado Shift al arrastrar un archivo al cuadro de entrada. Haz clic en la × del anexo para eliminarlo.

Por ejemplo, al depurar un error de estilo con cinco o seis niveles de CSS anidado, simplemente selecciona la regla sospechosa y lanza un "¿Por qué no tiene efecto aquí?". En dos rondas, detectó que el overflow: hidden del elemento padre estaba recortando el elemento hijo. Escribir el texto para describir todos esos niveles habría llevado mucho más tiempo.

⚠️ El texto seleccionado y el archivo abierto actualmente se enviarán a Claude con la indicación por defecto. Para archivos sensibles como .env, la documentación oficial recomienda agregar una regla de denegación Read (Lectura) a la ruta; una vez que coincida, no llegará a Claude (consulta la documentación oficial para obtener instrucciones precisas).

💡 Resumen en una frase: Usar menciones con @ y alimentar el contexto con código seleccionado, elimina directamente el mayor costo de suposiciones de "de qué fragmento de código estás hablando".

---

05 Revisión de planes (Plan Review): Haz que te entregue una propuesta primero y tú la apruebas antes de actuar

Esta sección probablemente explica la mayor mejora en la experiencia de usuario que tiene la extensión en comparación con la terminal. Primero, hablemos de los modos de permisos: haz clic en el indicador de modos en la parte inferior de la caja de diálogo para cambiar. Claude Code tiene las siguientes configuraciones:

Modo	Comportamiento de Claude	Cuándo usarlo
Normal (predeterminado)	Pregunta por tu permiso antes de cada acción	Tareas poco familiares, quieres tener control completo
Plan Mode (Modo Plan)	Primero describe lo que piensa hacer, espera tu aprobación	Grandes cambios, múltiples archivos, quieres ver la propuesta primero
Aceptación Automática	Cambia directamente, ya no pregunta paso a paso	Tareas pequeñas, repetitivas o en las que confías ciegamente

Hay una cuarta opción bypassPermissions (evitar todos los controles de permisos), que necesita activar allowDangerouslySkipPermissions en la configuración; solo está destinado para entornos sandbox completamente aislados, y no se recomienda para uso diario.

Analogía: Si un pasante te pregunta antes de actuar. El Modo Normal es "levanto la mano y pregunto cada paso", Aceptación Automática es "dejarlo ir y hacer las cosas", y el Modo Plan es especial: como un pasante que te entrega primero una propuesta de "así es como pretendo hacerlo" para que la revises. Tú asientes antes de que empiece a trabajar.

El Modo Plan tiene un beneficio en VS Code que la terminal no puede darte: Claude abrirá automáticamente el plan como un documento Markdown completo y puedes dejar comentarios (inline) allí. No necesitas responder de manera vaga con un "El paso dos no es correcto"; puedes escribir directamente al lado de la línea del "Paso Dos": "No toques la base de datos aquí, agrega caché primero". Él absorberá tus comentarios en el momento de comenzar, mucho más preciso que las revisiones verbales después de la tarea.

La imagen de arriba muestra un documento Markdown del plan abierto en Modo Plan: Claude enumera cada paso, y escribes tu comentario en línea junto a la línea del "Paso 2" ("No toques la base de datos, agrega memoria caché primero"). Él incorporará estos comentarios antes de que apruebes el comienzo.

¿Quieres que sea el valor predeterminado? Cambia claudeCode.initialPermissionMode en la configuración a plan. Un hábito seguro a adoptar: para cualquier cambio de "múltiples archivos, más de 50 líneas", cambia primero a Modo Plan. Una lección común: si dejas la Aceptación Automática activada todo el tiempo por comodidad y le dices que agregue logs a un módulo, él podría "optimizar" incidentalmente el orden de importaciones en varios archivos; te tomará diez minutos desenredar luego todo lo que tocó. Los cambios grandes siempre deben requerir una revisión del plan primero; controlarlo en la fase de la propuesta es mucho más limpio que arreglarlo después.

💡 Resumen en una frase: Modo Plan = revisa la propuesta antes de actuar, y también te permite añadir comentarios en línea en el plan Markdown. Cambia a él para modificaciones de varios archivos o grandes modificaciones, te ahorrará mucho trabajo rehecho.

---

06 A ensuciarse las manos: 10 minutos para ejecutar el flujo completo de la interfaz gráfica

A continuación, ejecutaremos el proceso desde cero. Cada paso indica lo que "debes ver", así que si lo sigues, podrás comprobar si lo tienes instalado correctamente y si sabes cómo usarlo.

Paso 0: Crear un proyecto de práctica mínimo

No necesitas un proyecto real; basta con crear una carpeta vacía y poner un archivo en ella. Ejecuta esto en la terminal:

mkdir vscode-claude-demo && cd vscode-claude-demo
printf 'def greet(name):\n    return "Hello " + name\n\nprint(greet("world"))\n' > demo.py
code .

Resultado esperado: VS Code abre esta carpeta, y en el Explorador a la izquierda puedes ver demo.py. (Si no has instalado la herramienta de línea de comandos code, simplemente abre esta carpeta manualmente).

Paso 1: Abre el panel de Claude e inicia sesión

Haz clic en demo.py (recuerda, debes tener un archivo abierto), haz clic en el icono de Spark en la esquina superior derecha. Cuando aparezca la pantalla de inicio de sesión por primera vez, haz clic en Login (Iniciar Sesión) y completa la autorización en el navegador.

Resultado esperado: El panel de conversación de Claude Code aparece a la derecha, y la parte superior ya no dice "Sin iniciar sesión".

Paso 2: Selecciona el código + pídele que lo cambie y mira el diff en línea

Selecciona las dos líneas de la función greet en demo.py. Debería mostrar "2 líneas seleccionadas" debajo del cuadro de entrada. Ahora escribe:

Cámbialo para que use f-string y añade anotaciones de tipo

Resultado esperado: Claude no pregunta "¿Qué función?" (mostrando que el contexto seleccionado fue alimentado correctamente), y aparece de inmediato un diff lado a lado. El lado derecho muestra return "Hello " + name cambiado a return f"Hello {name}" con anotaciones de tipo agregadas a la firma, y opciones de Aceptar / Rechazar aparecen debajo. Míralo claramente y haz clic en Aceptar.

Paso 3: Prueba el Modo Plan por una vez

Haz clic en el indicador de modo en la parte inferior del cuadro de entrada y cámbialo a Plan Mode, luego ingresa una solicitud un poco más grande:

Añade soporte para parámetros de línea de comandos a este archivo, de modo que el usuario pueda pasar el nombre desde la terminal

Resultado esperado: Claude no modificará el archivo directamente. Primero abrirá un documento del plan en Markdown listando su propuesta (por ejemplo, importando argparse). Puedes confirmar o agregar un comentario en línea al lado de un paso, y luego él ejecutará. Al llegar a este punto, has utilizado el núcleo: diff en línea, alimentación de contexto seleccionado y revisiones de planes.

---

07 Favoritos a mano: Atajos de teclado comunes y cómo "Cambiar a CLI"

Conjunto de atajos de teclado comunes (de la documentación oficial, diferencias de plataforma anotadas):

Acción	Atajo	Descripción
Cambiar Foco (Editor ↔ Claude)	Cmd+Esc / Ctrl+Esc	Dondequiera que esté el panel enfocado, ahí es donde actuará el atajo
Abrir Conversación en Nueva Pestaña	Cmd+Shift+Esc / Ctrl+Shift+Esc	Abre varias conversaciones en paralelo
Insertar referencia con @	Option+K / Alt+K	El editor debe tener el foco
Reabrir conversación recién cerrada	Cmd+Shift+T / Ctrl+Shift+T	Activado por defecto
Iniciar nueva conversación	Cmd+N / Ctrl+N	Desactivado por defecto, debe activarse en configuración mediante enableNewConversationShortcut

Los usuarios de macOS Tahoe+ se encuentran con una trampa: El "Overlay de Juego (Game overlay)" del sistema intercepta por defecto Cmd+Esc. Ve a "Configuración del Sistema → Teclado → Atajos de Teclado → Controladores de Juego" y desmárcalo, o reasigna Claude Code: Focus input a otra tecla.

¿Quieres volver al estilo de interfaz CLI? Simplemente abre la terminal integrada (Cmd+` / Ctrl+`) y ejecuta claude. La CLI se conectará automáticamente a VS Code, y aún podrás usar la función de diff nativo (para terminales externas, ejecuta /ide para conectar manualmente); o marca Usar Terminal (useTerminal) en la configuración para que la extensión inicie directamente en modo terminal.

Proveedores externos (Bedrock / Vertex AI / Foundry): Primero marca Deshabilitar la solicitud de inicio de sesión (disableLoginPrompt), luego configura ~/.claude/settings.json según la guía del proveedor (consulta la documentación oficial para estar seguro).

💡 Resumen en una frase: Cmd+Esc es el más utilizado para cambiar el enfoque; Option+K inserta una referencia; para recuperar la sensación de la terminal, ejecuta claude o marca useTerminal; tanto el modo de interfaz gráfica como la línea de comandos están a tu disposición.

---

08 Resumen

Este artículo llevó Claude Code desde la terminal a VS Code, enfocándose en unas pocas cosas esenciales:

• La Extensión ≠ un Reemplazo para la CLI: Es el mismo motor, que comparte historial y configuración. Escribe código en la extensión, y si necesitas funcionalidad exclusiva de la CLI, cambia a la terminal.
• El Primer Obstáculo de la Instalación es Encontrar el Icono: Busca al publicador Anthropic; el icono de Spark solo aparece cuando hay un archivo abierto. Si no puedes encontrarlo, entra a través de la barra de estado en la parte inferior derecha.
• Tres Placeres de la Interfaz Gráfica: Diff lado a lado (véalo claramente antes de asentir, edítelo en el lugar); Menciones con @ / Selección de código (contexto alimentado con precisión); Revisión del plan (vea la propuesta primero, deje comentarios en línea).

Ahora deberías poder instalar de forma independiente la extensión, usar el diff lado a lado para revisar las modificaciones, usar @ y seleccionar código para alimentar con precisión el contexto, y cambiar al Modo Plan antes de realizar cambios grandes. Una vez que te familiarices con este flujo de trabajo, podrás confiar de manera constante en él para la codificación diaria.

---

En el siguiente artículo, 09 Integración con JetBrains, si tu entorno de trabajo principal es IntelliJ IDEA, PyCharm u otra herramienta de la suite de JetBrains, Claude Code también ofrece un plugin nativo. Echaremos un vistazo a sus similitudes y diferencias con la extensión de VS Code, así como algunos puntos de configuración exclusivos para los usuarios de JetBrains.

---

Lecturas recomendadas

• Voice Modo de voz: Di tus prompts en lugar de escribirlos
• Web y Cloud: Pon a Claude Code en el navegador y el teléfono
• Imágenes y Multimodal: Pega una captura, lo entiende al instante