GroundEffect

Indexación hiperrápida y local de Gmail y Google Calendar para Claude Code, disponible como Skill o MCP Server.

Documentación

GroundEffect

Indexación local y ultrarrápida de Gmail y Google Calendar para Claude Code.

GroundEffect es un cliente IMAP/CalDAV local sin interfaz gráfica, una habilidad de Claude Code y un servidor MCP construido en Rust con LanceDB.

Características

Búsqueda híbrida: BM25 de texto completo + búsqueda semántica vectorial con fusión de rango recíproco (Reciprocal Rank Fusion)
Embeddings locales: Ejecuta nomic-embed-text-v1.5 localmente mediante Candle con aceleración Metal
Multi-cuenta: Conecta cuentas ilimitadas de Gmail/GCal con sincronización independiente
Integración MCP: Expone herramientas de correo y calendario directamente a Claude Code
Sincronización en tiempo real: IMAP IDLE para notificaciones instantáneas de correo, sondeo CalDAV para calendario
Extracción de texto HTML: Convierte automáticamente correos HTML a texto plano limpio usando html2text
Almacenamiento de tokens conectable: Basado en archivos (predeterminado) o PostgreSQL con cifrado AES-256-GCM

Inicio rápido

1. Instalar

brew tap jamiequint/groundeffect
brew install groundeffect

Esto automáticamente:

Instala el daemon (se inicia al iniciar sesión)
Instala la habilidad de Claude Code
Añade permisos para ejecutar comandos de groundeffect

2. Configurar OAuth

Crea un proyecto de Google Cloud con credenciales OAuth:

Ve a Google Cloud Console
Crea un proyecto y habilita Gmail API y Google Calendar API
Ve a APIs & Services > Credenciales
Crea ID de cliente OAuth (tipo de aplicación de escritorio)
Añade tus credenciales:

echo 'export GROUNDEFFECT_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"' >> ~/.zshrc
echo 'export GROUNDEFFECT_GOOGLE_CLIENT_SECRET="your-client-secret"' >> ~/.zshrc
source ~/.zshrc

3. Añadir una cuenta

groundeffect account add

Esto abre un navegador para OAuth de Google. Después de la autenticación, el daemon se sincroniza automáticamente.

¡Eso es todo! Pide a Claude Code que busque en tus correos y calendario.

Referencia de CLI

Todos los comandos generan JSON por defecto. Añade --human para una salida legible.

Comandos de cuenta

Comando	Descripción
`account list`	Listar todas las cuentas conectadas
`account show <account>`	Mostrar detalles de la cuenta y estado de sincronización
`account add`	Añadir nueva cuenta de Google mediante OAuth
`account reauth <account>`	Reautenticar una cuenta existente mediante OAuth
`account delete <account>`	Eliminar cuenta y todos los datos sincronizados
`account configure <account>`	Actualizar configuración de la cuenta (alias, adjuntos)

Parámetros para add:

Parámetro	Descripción	Predeterminado
`--years`	Años de historial de correo a sincronizar (1-20 o "all")	1
`--attachments`	Habilitar descarga automática de adjuntos	off
`--alias`	Nombre amigable para la cuenta	-

Comandos de correo

Comando	Descripción
`email search <query>`	Búsqueda híbrida BM25 + semántica
`email list`	Listar correos recientes
`email show <id>`	Mostrar contenido completo del correo
`email thread <thread_id>`	Mostrar todos los correos en un hilo
`email send`	Redactar y enviar correo
`email attachment <id>`	Obtener contenido de adjuntos
`email folders`	Listar carpetas IMAP

Parámetros para search:

Parámetro	Descripción	Predeterminado
`--account`	Filtrar a cuenta específica	all
`--limit`	Máximo de resultados (máx: 100)	10
`--from`	Filtrar por remitente	-
`--to`	Filtrar por destinatario	-
`--date-from`	Filtrar después de fecha (YYYY-MM-DD)	-
`--date-to`	Filtrar antes de fecha (YYYY-MM-DD)	-
`--has-attachment`	Filtrar correos con adjuntos	-

Parámetros para send:

Parámetro	Descripción
`--from`	Cuenta desde la que enviar (obligatorio)
`--to`	Destinatario(s) (obligatorio)
`--subject`	Asunto del correo (obligatorio)
`--body`	Cuerpo del correo (obligatorio)
`--cc`	Destinatarios en CC
`--bcc`	Destinatarios en CCO
`--reply-to`	ID del correo al que responder (para hilos)
`--html`	Forzar formato HTML (auto-detectado desde markdown/URLs)
`--save-as-draft`	Guardar como borrador en lugar de enviar
`--confirm`	Enviar inmediatamente (sin: solo vista previa)

Comandos de borradores

Comando	Descripción
`email draft create`	Crear un nuevo borrador de correo
`email draft list`	Listar todos los borradores de una cuenta
`email draft show <id>`	Mostrar contenido completo del borrador
`email draft update <id>`	Actualizar un borrador existente
`email draft send <id>`	Enviar un borrador
`email draft delete <id>`	Eliminar un borrador

Parámetros para draft create:

Parámetro	Descripción
`--from`	Cuenta en la que crear el borrador (obligatorio)
`--to`	Destinatario(s)
`--subject`	Asunto del correo
`--body`	Cuerpo del correo
`--cc`	Destinatarios en CC
`--bcc`	Destinatarios en CCO
`--html`	Forzar formato HTML
`--reply-to`	ID del correo al que responder (para hilos)

Comandos de calendario

Comando	Descripción
`calendar events`	Listar eventos en un rango de fechas (sin consulta requerida)
`calendar search <query>`	Buscar eventos con búsqueda semántica
`calendar show <id>`	Mostrar detalles del evento
`calendar create`	Crear nuevo evento

Parámetros para events:

Parámetro	Descripción	Predeterminado
`--from`	Fecha de inicio (YYYY-MM-DD)	hoy
`--to`	Fecha de fin (YYYY-MM-DD)	7 días desde el inicio
`--account`	Filtrar a cuenta(s) específica(s)	all
`--limit`	Máximo de resultados (máx: 200)	50
`--human`	Salida legible para humanos agrupada por fecha	-

Usa calendar events para responder preguntas como "¿qué tengo en mi calendario mañana?" o "muéstrame mis reuniones de la próxima semana" sin requerir una consulta de búsqueda.

Parámetros para create:

Parámetro	Descripción	Predeterminado
`--account`	Cuenta en la que crear el evento (obligatorio)	-
`--summary`	Título del evento (obligatorio)	-
`--start`	Hora de inicio (ISO 8601) (obligatorio)	-
`--end`	Hora de fin (ISO 8601) (obligatorio)	-
`--description`	Descripción del evento	-
`--location`	Ubicación del evento	-
`--attendees`	Correos de asistentes (repetible)	-
`--calendar`	ID de calendario	primary

Comandos de sincronización

Comando	Descripción
`sync status`	Mostrar estado de sincronización de todas las cuentas
`sync reset --account <a> --confirm`	Borrar todos los datos sincronizados
`sync extend --account <a> --target-date <d>`	Sincronizar correos antiguos hasta una fecha
`sync resume-from --account <a> --target-date <d>`	Forzar reanudación de sincronización desde una fecha
`sync download-attachments --account <a>`	Descargar adjuntos pendientes

Comandos del daemon

Comando	Descripción
`daemon install`	Instalar agente launchd (inicio automático al iniciar sesión)
`daemon uninstall`	Eliminar agente launchd
`daemon status`	Comprobar si el daemon está en ejecución
`daemon restart`	Reiniciar el daemon

Comandos de configuración

Comando	Descripción
`config settings`	Ver/modificar configuración del daemon
`config add-permissions`	Añadir a la lista de permitidos de Claude Code
`config remove-permissions`	Eliminar de la lista de permitidos de Claude Code

Parámetros para settings:

Parámetro	Descripción	Predeterminado
`--logging`	Habilitar/deshabilitar registro en archivo	off
`--email-interval`	Intervalo de sondeo de correo en segundos (60-3600)	300
`--calendar-interval`	Intervalo de sondeo de calendario en segundos (60-3600)	300
`--max-fetches`	Máximo de descargas concurrentes (1-50)	10
`--timezone`	Zona horaria del usuario para análisis de fechas (p. ej., America/Los_Angeles)	UTC
`--embedding-provider`	Backend de embeddings: `local`, `openrouter`, `remote`	local
`--embedding-batch-size`	Tamaño de lote de embeddings + descarga IMAP (1-1024)	128
`--openrouter-model`	ID del modelo de embeddings de OpenRouter	`openai/text-embedding-3-small`
`--openrouter-api-key-env`	Nombre de variable de entorno con clave API de OpenRouter	`OPENROUTER_API_KEY`

Ejemplos de backend de embeddings:

# Use local embeddings (default)
groundeffect config settings --embedding-provider local

# Use OpenRouter embeddings
export OPENROUTER_API_KEY="your-key"
groundeffect config settings --embedding-provider openrouter

# Set embedding + IMAP fetch batch size (128 recommended for Gmail/OpenRouter stability)
groundeffect config settings --embedding-batch-size 128

# Optional: set a different OpenRouter model
groundeffect config settings --openrouter-model "openai/text-embedding-3-large"

Integración MCP (Alternativa)

Si prefieres MCP sobre la habilidad CLI, añade a ~/.claude.json:

{
  "mcpServers": {
    "groundeffect": {
      "type": "stdio",
      "command": "groundeffect-mcp",
      "env": {
        "GROUNDEFFECT_GOOGLE_CLIENT_ID": "${GROUNDEFFECT_GOOGLE_CLIENT_ID}",
        "GROUNDEFFECT_GOOGLE_CLIENT_SECRET": "${GROUNDEFFECT_GOOGLE_CLIENT_SECRET}"
      }
    }
  }
}

La habilidad es más rápida (llamadas CLI directas vs sobrecarga JSON-RPC de MCP) pero MCP funciona con otros clientes compatibles con MCP.

Compilar desde el código fuente

git clone https://github.com/jamiequint/groundeffect.git
cd groundeffect
cargo build --release

Binarios:

target/release/groundeffect - CLI
target/release/groundeffect-daemon - Daemon de sincronización en segundo plano
target/release/groundeffect-mcp - Servidor MCP

Instalar manualmente:

# Install binaries
sudo cp target/release/groundeffect* /usr/local/bin/

# Install skill
cp -r skill ~/.claude/skills/groundeffect

# Install daemon
groundeffect daemon install

# Add permissions
groundeffect config add-permissions

Almacenamiento de datos

~/.config/groundeffect/
├── config.toml            # Main configuration
├── daemon.toml            # Daemon configuration
└── tokens/                # OAuth tokens (file provider)

~/.local/share/groundeffect/
├── lancedb/               # LanceDB database
├── attachments/           # Downloaded attachments
├── models/                # Embedding model files
├── logs/                  # Log files
└── cache/
    └── sync_state/        # Sync state

~/.claude/skills/groundeffect/   # Claude Code skill

Almacenamiento de tokens

Por defecto, los tokens OAuth se almacenan en ~/.config/groundeffect/tokens/ como archivos JSON cifrados.

Para despliegues de servidor o contenedores efímeros, puedes almacenar tokens en PostgreSQL en su lugar. Esto requiere la característica postgres.

Almacenamiento de tokens en PostgreSQL

Compila con la característica postgres:

cargo build --release --features postgres

Crea la tabla de tokens:

CREATE TABLE IF NOT EXISTS groundeffect_tokens (
    email VARCHAR(255) PRIMARY KEY,
    encrypted_tokens BYTEA NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

Configura en ~/.config/groundeffect/config.toml:

[tokens]
provider = "postgres"
database_url_env = "DATABASE_URL"
encryption_key_env = "GE_TOKEN_ENCRYPTION_KEY"
# table_name = "groundeffect_tokens"  # optional

Establece variables de entorno:

export DATABASE_URL="postgres://user:pass@localhost/mydb"
export GE_TOKEN_ENCRYPTION_KEY="your-secret-key-here"

Los tokens se cifran en reposo usando AES-256-GCM con una clave derivada de tu clave de cifrado mediante HKDF-SHA256.

Solución de problemas

"Token OAuth expirado"

Reautentica:

groundeffect account reauth <email-or-alias>

El daemon no se está ejecutando

Comprueba el estado y reinicia:

groundeffect daemon status
groundeffect daemon restart

O comprueba launchd:

launchctl list | grep groundeffect

Ver registros

tail -f ~/.local/share/groundeffect/logs/daemon.log

Habilita el registro si está deshabilitado:

groundeffect config settings --logging true
groundeffect daemon restart

Alto uso de memoria

El modelo de embeddings usa ~500MB-1GB durante la incrustación activa. Normal cuando está inactivo.

Arquitectura

┌──────────────┐      ┌──────────────────┐
│ Claude Code  │─────►│ groundeffect-mcp │────────┐
│ (MCP Host)   │stdio │                  │        │
└──────────────┘      └──────────────────┘        │
                                                  ▼
┌──────────────┐      ┌──────────────────┐    ┌─────────┐
│ Claude Code  │─────►│ groundeffect     │───►│ LanceDB │
│ (Skill/Bash) │      │ (CLI)            │    └─────────┘
└──────────────┘      └──────────────────┘         ▲
                                                   │
                      ┌──────────────────┐         │
                      │ groundeffect-    │─────────┘
                      │ daemon           │◄──── IMAP/CalDAV
                      └──────────────────┘

Licencia

MIT