10. El núcleo (Core) de Gemini CLI

Objetivo del tema

Conocer los componentes internos de Gemini CLI Core, cómo expone herramientas mediante la Tools API, de qué forma procesa memorias con el Memory Import Processor y cómo se comunican el cliente y el servidor local.

Entender esta arquitectura facilita la extensión del CLI, la depuración y la integración con ecosistemas empresariales.

10.1 Visión general del core

Gemini CLI se distribuye como dos paquetes principales:

Paquete Rol
@google/gemini-cli Frontend que ves en la terminal: acepta comandos, muestra resultados, maneja atajos (slash commands, at commands, etc.).
@google/gemini-cli-core Servidor local que orquesta la sesión: gestiona herramientas, memoria, telemetría y la comunicación con la API de Gemini.

El core coordina varios servicios internos:

  • Tool Dispatcher: decide qué herramienta ejecutar cuando el modelo emite una llamada.
  • Memory Discovery Service: rastrea archivos GEMINI.md globales, de proyecto y de subdirectorios para construir el contexto jerárquico.
  • Telemetry Collector: agrega métricas y opcionalmente las envía mediante OpenTelemetry.
  • Checkpoint Manager: crea snapshots antes de operaciones sensibles (según vimos en el Tema 7).

El CLI interactivo y el core se ejecutan como procesos separados comunicándose a través de JSON RPC/IPC; esta separación permite aislar privilegios, registrar telemetría y facilitar pruebas automatizadas.

10.2 Tools API

La Tools API define cómo el core descubre, registra y ejecuta herramientas. El flujo estándar es:

  1. Descubrimiento: el core consulta fuentes declaradas en settings.json:
    • tools.discoveryCommand: script que devuelve una lista de FunctionDeclaration.
    • mcpServers: servidores MCP que exponen herramientas externas; los nombres se prefijan con el alias del servidor.
    • Herramientas integradas (read_file, write_file, run_shell_command, etc.).
  2. Registro en el modelo: el core envía al modelo la firma de cada herramienta para que pueda invocarla mediante function calling.
  3. Ejecución: cuando el modelo llama a una herramienta, el core invoca el callCommand correspondiente o el MCP server y empaqueta el resultado en un ToolResult con dos partes:
    • llmContent: información que regresa al modelo para continuar la conversación.
    • returnDisplay: mensaje adaptado para mostrar en la terminal.
  4. Respuesta al modelo y al usuario: el core envía FunctionResponse al modelo y actualiza la UI con el resultado.

Ejemplo de herramienta descubierta vía comando:

[
  {
    "name": "list_services",
    "description": "Lista servicios activos en el clúster",
    "parameters": {
      "type": "object",
      "properties": {
        "namespace": { "type": "string" }
      },
      "required": ["namespace"]
    }
  }
]

Si agregas nuevas herramientas, recuerda actualizar también tools.callCommand para que el core sepa cómo ejecutarlas. También puedes agruparlas en un MCP server si necesitas aislar permisos.

10.3 Memory Import Processor

El Memory Import Processor expande directivas de importación dentro de tus archivos GEMINI.md. Esto permite construir memorias modulares sin repetir contenido.

  • Sintaxis: usa @ruta/al/archivo.md en el cuerpo del GEMINI.md para incluir otro documento.
  • Resolución de rutas: se calcula en base al archivo que contiene la directiva. Puedes usar rutas relativas o absolutas.
  • Protección: el procesador evita importaciones repetidas, detecta ciclos y lanza advertencias si hay referencias circulares.
  • Depuración: habilita el modo debug para ver el orden de carga y las rutas resueltas.

Ejemplo simple:

# Guía del proyecto

@docs/arquitectura.md
@docs/estilos.md

## Notas
- Actualizar esta memoria cuando cambien los endpoints.

El servicio de descubrimiento combina estos archivos con los contextos globales y locales (como vimos en el Tema 6) y expone el resultado mediante /memory show.

10.4 Relación entre cliente y servidor local

La comunicación entre los paquetes @google/gemini-cli (cliente) y @google/gemini-cli-core (servidor local) sigue estos pasos:

  1. Inicialización: al ejecutar gemini, el cliente lanza el core como proceso separado (o se conecta a uno existente) y negocia la versión de la API interna.
  2. Ciclo de mensajes: cada entrada del usuario se envía al core, que:
    • Enriquece el prompt con memoria (Memory Discovery + Import Processor).
    • Solicita respuesta a la API de Gemini, manejando credenciales y cuotas.
    • Intercepta llamadas a herramientas y las ejecuta en el entorno local.
    • Registra telemetría y checkpoints según corresponda.
  3. Respuesta renderizada: el core devuelve al cliente los mensajes, citations, diffs de herramientas y eventos de estado para que el frontend actualice la UI (tema seleccionado, indicadores de sandbox/trusted folders, etc.).
  4. Integraciones: si el usuario habilita telemetría, extensiones MCP o temas personalizados, el core actúa como punto central para coordinar esas extensiones y proveerle al cliente una vista consistente.

Gracias a esta arquitectura, puedes ejecutar el frontend en uno de tus scripts (por ejemplo con --prompt) mientras el core mantiene la sesión, reintentos y acceso a herramientas de forma confiable.

Conclusión: el núcleo de Gemini CLI es mucho más que una interfaz: coordina herramientas, memoria, telemetría y seguridad para entregar respuestas contextualizadas sin comprometer tu entorno. Al comprender la Tools API, el Memory Import Processor y la relación cliente-servidor puedes extender el CLI, diagnosticar problemas e integrarlo profesionalmente.

Retornar