12. Extensiones

Objetivo del tema

Comprender qué son las extensiones de Gemini CLI, cómo se construyen, cómo se publican y qué ecosistema existe para compartirlas.

Las extensiones permiten sumar herramientas, comandos y contexto persistente sin modificar el núcleo del CLI, apoyándose en el Model Context Protocol (MCP) y en manifestos JSON que describen la funcionalidad expuesta.

12.1 ¿Qué son las extensiones?

Una extensión empaqueta recursos adicionales para el CLI:

Componente Descripción
gemini-extension.json Manifesto de la extensión: define nombre, metadatos, herramientas extras, comandos y memorias asociadas.
Servidor MCP Proceso opcional que expone métodos y recursos adicionales (APIs, bases de datos, servicios propios).
Comandos personalizados Atajos (/) que se registran junto con los demás comandos del CLI.
Contextos Archivos GEMINI.md o memorias que se cargan automáticamente cuando la extensión está activa.

Las extensiones pueden instalarse localmente (carpeta en ~/.gemini/extensions) o descargarse desde repositorios/remotos (GitHub Releases u otros).

12.2 Cómo empezar una extensión

La documentación oficial sugiere estos pasos:

  1. Clonar la plantilla: 
    git clone https://github.com/google-gemini/gemini-cli-extension-template.git mi-extension
cd mi-extension
  2. Instalar dependencias: las extensiones están escritas en TypeScript. 
    npm install
npm run build
  3. Configurar el manifiesto: edita gemini-extension.json para describir la extensión (nombre, versión, comandos, servidor MCP, memorias).
  4. Agregar herramientas: implementa las funciones del servidor MCP o configura tools.discoveryCommand si usas scripts directos.
  5. Registrar contextos: puedes incluir GEMINI.md para proporcionar guías o instructivos que el CLI cargará cada vez.
  6. Probar y enlazar localmente: 
    npm run build
npm link
    Luego reinicia el CLI para que detecte la extensión.
  7. Activar en un proyecto: copia el directorio al workspace o utiliza gemini extension install <URL> si la publicaste en un repositorio.

Utiliza gemini extension list y gemini extension info <nombre> para verificar que la extensión se cargó correctamente y conocer los comandos disponibles.

12.3 Publicación de extensiones

Hay dos alternativas principales:

  • Repositorio público (Git/GitHub): distribuye la extensión como un proyecto abierto. Las personas usuarias pueden clonar, instalar y seguir las instrucciones de tu README.
  • GitHub Releases: empaqueta versiones con binarios o tarballs listos para descargar e instalar con gemini extension install <URL>.

La guía oficial recomienda:

  • Usar npm run package para generar paquetes por plataforma si tu extensión incluye ejecutables.
  • Configurar un flujo de CI/CD (GitHub Actions) que corra tests, compile y publique releases automáticas.
  • Incluir un CHANGELOG.md y etiquetas semánticas (v1.0.0, v1.1.0...).

Recuerda documentar claramente los requisitos (versiones de Node.js, dependencias, variables de entorno) para evitar errores en instalaciones remotas.

12.4 Ejemplos y ecosistema

  • Extensiones oficiales: integraciones con Google Cloud, GitHub u otras herramientas publicadas por el equipo de Gemini.
  • Extensiones comunitarias: repositorios que proveen comandos para gestionar proyectos, interactuar con APIs internas o automatizar auditorías.
  • Compatibilidad IDE: las extensiones pueden complementar la integración companion spec con VSCode/Neovim, compartiendo comandos o contextos comunes.

Gemini CLI mantiene la prioridad de los comandos según el origen:

  1. Comandos internos de Gemini CLI.
  2. Comandos definidos por el usuario/proyecto.
  3. Comandos de extensiones.

Si hay conflicto, el CLI renombra los comandos de la extensión con el prefijo alias.command (por ejemplo, /gcp.deploy).

12.5 Buenas prácticas

  • Proporciona pruebas unitarias y de integración para tu extensión (ver la sección de contribuciones del repositorio oficial).
  • Explica cómo configurar credenciales y secretos de forma segura.
  • Mantén tus extensiones actualizadas con las versiones nuevas del CLI.
  • Valida que los comandos se comporten bien con sandbox y trusted folders.
  • Ofrece un canal de soporte (issues en GitHub, contacto) para que la comunidad pueda reportar problemas.

Conclusión: las extensiones son el camino para adaptar Gemini CLI a necesidades específicas y compartir funcionalidades con la comunidad. Con un manifiesto claro, herramientas MCP bien diseñadas y una distribución cuidada, puedes transformar el CLI en una plataforma colaborativa centrada en tu ecosistema.

Retornar