Presence

Memoria entre sesiones y una puerta de verificación para Claude Code

Documentación

presence

Nuevo en v0.8.0: notificador webhook opcional para veredictos de puerta de confianza, desactivado por defecto y forzosamente deshabilitado bajo zerotrust. Ver docs/recipes.md.

Cada sesión de Claude Code comienza en frío. presence hace que la siguiente comience donde terminó la anterior.

Un plugin de Claude Code con proyecciones de solo lectura (servidor MCP, adaptador AGENTS.md) para que clientes compatibles con MCP (Cursor, Claude Desktop, Continue) y herramientas compatibles con AGENTS.md (Codex, Gemini CLI, Windsurf, GitHub Copilot) también puedan leer su contexto acumulado. Convierte cada sesión en parte de un continuo.

presence añade cuatro cosas a Claude Code, globalmente, con una sola instalación y cero configuración por proyecto:

Modelo de proyecto vivo. Claude construye y reutiliza notas sobre cada repositorio que toca. No más re-derivar la misma arquitectura en cada sesión.
Telemetría de resultados. Rastrea lo que Claude confirmó (commits), luego vigila reversiones, enmiendas y cierres de PRs. Las sesiones futuras ven "tus últimos 3 cambios aquí fueron revertidos en 24h" en lugar de repetir el mismo error.
Resumen de eventos. Cambios de archivos, fallos de pruebas y resultados de compilación ocurridos entre turnos se muestran en el siguiente prompt en lugar de requerir sondeo.
Confianza calibrada. El hook Stop verifica si las afirmaciones de éxito ("arreglado", "hecho", "funciona") están respaldadas por verificación real (pruebas ejecutadas, compilación verde) desde el cambio. Advierte cuando no lo están. Puerta dura opcional en git commit/push.

El estado vive en ~/.claude/presence/, completamente local, nunca se sube.

Instalación (30 segundos)

curl -fsSL https://raw.githubusercontent.com/sara-star-quant/presence/main/install.sh | bash

¿Sin Python 3.12+? Añade -s -- --bootstrap para auto-instalarlo vía uv (una llamada a astral.sh). El comando simple anterior hace cero llamadas salientes.

Eso es todo. Instalador idempotente, no hace llamadas de red salientes más allá de obtenerse a sí mismo, se aplica globalmente a cada proyecto de Claude Code. Reinicia Claude Code y ejecuta /presence-status para confirmar. Para opciones (--bootstrap para auto-instalar Python, --verify, --build-ext para la ruta rápida nativa), ver Inicio rápido abajo.

En números

Métrica	Predeterminado (stdlib)	Con `--build-ext`	Método
Arranque de hook en frío	82 ms mediana	8.9 ms mediana	n=50 / n=30, `bench/cold_startup.py`
SessionStart poblado	112 ms mediana	9.1 ms mediana	modelo de 10 KB + 100 eventos + 50 afirmaciones
Sesión agregada (77 disparos)	6.4 s	770 ms	n=10 / n=5, `bench/aggregate_session.py`
Instalación + primer /presence-status	245 ms total	245 ms total	n=25, `bench/install_to_working.py`
Pruebas	291 pasando		Python 3.12 + 3.13 + 3.14 en Linux + macOS
Dependencias de ejecución (predeterminado)	0 (solo stdlib)		una opcional: `cryptography` para cifrado en reposo Zero-Trust
Opcional con `--build-ext`		cadena de herramientas Rust al instalar	el binario luego se ejecuta sin Rust
Superficie	4 presets, 6 hooks, 6 comandos slash, 3 habilidades, 1 subagente, 1 servidor MCP, 1 adaptador entre herramientas, 3 perfiles de redacción		perfiles de redacción opcionales para cargas de trabajo reguladas
Egreso de red	0 en presets predeterminados		llamada de estado de PR `gh` opcional; `--bootstrap` / `--download-ext` opcionales; todo deshabilitado por defecto
Plataformas	macOS arm64 + Linux x86_64 (CI)		Windows: instalar en WSL2

La columna --build-ext refleja la aceleración nativa opcional vía el cliente daemon Rust (./install.sh --build-ext para compilar localmente, o --download-ext para obtener un binario precompilado de la última versión). Sin él, los hooks se ejecutan en la ruta solo-stdlib. Ver bench/HISTORY.md para el historial completo de benchmarks versión por versión.

Todas las mediciones: macOS arm64, Python 3.14.4. Reproduce localmente con python3 bench/<name>.py --runs N. Ver bench/README.md para la convención completa.

Cambios recientes: ver CHANGELOG.md para el diff completo por versión. v0.8.0 incluye un notificador webhook opcional para veredictos de puerta de confianza, controlado por el mismo interruptor zerotrust network.egress_allowed que la verificación de frescura de versiones. v0.5.0 incluye perfiles de redacción componibles para datos sensibles conscientes de jurisdicción. Opt-in vía redact.profiles en configuración: pii-eu, pii-us, pci-dss (coincidencias PAN controladas por Luhn). Nuevo docs/compliance.md dice exactamente qué hace y qué no hace presence para cargas de trabajo reguladas. Sin marco de certificación: los nombres de perfil describen clases de datos, no marcos de cumplimiento. v0.4.2 incluye el adaptador AGENTS.md entre herramientas. Establece PRESENCE_HOST=agents-md y presence refresca <repo>/AGENTS.md en cada SessionStart de Claude Code, recogido automáticamente por Codex, Cursor, Gemini CLI, Windsurf, GitHub Copilot y otros que leen el estándar abierto AGENTS.md. Ver docs/multi-host.md. v0.4.1 incluyó el servidor MCP: cualquier cliente compatible con MCP (Claude Desktop, Cursor, Continue, agentes personalizados) puede leer el modelo vivo + telemetría de resultados de presence sobre JSON-RPC stdio. Ver docs/mcp.md. v0.4.0 incluyó el cliente daemon Rust + daemon Python cálido + costura de adaptador. Opcional vía --build-ext / --download-ext. Reduce la latencia de ruta caliente de 82 ms a 8.9 ms (-89%). v0.3.x redujo la latencia de hook en frío ~27% y corrigió un bug latente de v0.2 donde usuarios Zero-Trust tenían su resumen de eventos vaciado silenciosamente. v0.2.0 incluyó el preset Zero-Trust: AES-GCM en reposo, registro de auditoría a prueba de manipulación, integridad SessionStart a prueba de fallos. Ver docs/zerotrust.md.

Inicio rápido

Si este es tu primer plugin de Claude Code: solo ejecuta estos dos comandos.

1. Instalar

curl -fsSL https://raw.githubusercontent.com/sara-star-quant/presence/main/install.sh | bash

El instalador es idempotente. Verifica Python 3.12+, enlaza simbólicamente el plugin en ~/.claude/plugins/presence, crea el directorio de estado en ~/.claude/presence/ con permisos 0700, genera MANIFEST.lock y precompila lib/ a bytecode.

Si no tienes Python 3.12+, el instalador imprime una advertencia y continúa; presence se instala pero permanece inactivo hasta que un Python 3.12+ esté en PATH. Esto es intencional para que puedas instalar en una máquina que obtendrá Python más tarde (o ejecutar --bootstrap). Para auto-instalar Python 3.13 vía uv (binario único, sin sudo, ~5 MB), pasa --bootstrap:

curl -fsSL https://raw.githubusercontent.com/sara-star-quant/presence/main/install.sh | bash -s -- --bootstrap

--bootstrap es opt-in porque hace una llamada de red a astral.sh. La ruta de instalación predeterminada no hace llamadas salientes.

2. Verificar que funciona

~/.claude/plugins/presence/install.sh --verify

Verifica el enlace simbólico, el registro del plugin en settings.json, permisos, Python, la integridad de MANIFEST.lock y dispara sintéticamente los 6 hooks contra el árbol lib/ real. Salida 0 significa listo. Las líneas FAIL te dicen exactamente qué falta. Para salida legible por máquina: --verify --json.

3. Usarlo

Reinicia Claude Code (o abre una nueva sesión) en cualquier repositorio y ejecuta /presence-status.

Otros métodos de instalación

Vía el flujo de marketplace de plugins de Claude Code

El repositorio incluye su propio marketplace.json para que pueda añadirse directamente:

/plugin marketplace add github.com/sara-star-quant/presence
/plugin install presence

Vía git clone

git clone https://github.com/sara-star-quant/presence ~/code/presence
~/code/presence/install.sh

Para el cifrado en reposo del preset Zero-Trust (opt-in), también instala la biblioteca cryptography en el mismo Python que usa presence. En macOS/Linux modernos esto importa porque Homebrew y la mayoría de distribuciones marcan el Python del sistema como gestionado externamente según PEP 668; un pip install simple sale con error: externally-managed-environment.

Elige la ruta que coincida con cómo obtuviste Python:

# A. You used --bootstrap (presence has its own uv-managed Python).
#    pip works directly there, no PEP 668 wall.
"$(cat ~/.claude/presence/.python_bin)" -m pip install cryptography

# B. You're on Homebrew / a system Python and want to override PEP 668
#    (installs into your user site, not system; safe in practice).
python3 -m pip install --user --break-system-packages cryptography

# C. You want isolation (cleanest): create a venv and pin presence at it.
python3 -m venv ~/.claude/presence-venv
~/.claude/presence-venv/bin/pip install cryptography
echo "$HOME/.claude/presence-venv/bin/python3" > ~/.claude/presence/.python_bin

Si no estás seguro de qué Python está usando presence, ejecuta /presence-doctor y mira las líneas pinned python / python, luego usa el -m pip install cryptography de ese intérprete.

Otros presets y el resto de controles Zero-Trust (verificación de integridad, redacción, puertas, registro de auditoría) son solo-stdlib.

Actualización

Para instalaciones hechas vía curl o git clone:

~/.claude/plugins/presence/install.sh --update

--update hace git fetch + git pull --ff-only + una re-ejecución del instalador. Se niega a continuar si el árbol de trabajo tiene cambios sin confirmar (para nunca sobrescribir trabajo en progreso). Para instalaciones hechas vía el flujo /plugin, usa el mecanismo nativo de actualización de plugins de Claude Code.

Recibir notificaciones de nuevas versiones (opt-in)

/presence-doctor puede mostrar la última etiqueta publicada frente a tu versión instalada. Desactivado por defecto; actívalo añadiendo lo siguiente a ~/.claude/presence/settings.json:

{ "update_check": { "enabled": true } }

El siguiente SessionStart pre-calienta una caché de 24 h (un GET HTTPS anónimo a api.github.com); el doctor luego muestra una línea, p. ej. latest : v0.6.0 (you have v0.5.4) [checked 12h ago]. Forzosamente desactivado bajo el preset zerotrust (sin egreso de red bajo esa postura). Ejecuta /presence-doctor --refresh para omitir el TTL al verificar una etiqueta nueva.

Verificar instalación

La verificación más rápida es ./install.sh --verify de la sección anterior. Desde dentro de Claude Code también puedes ejecutar:

/presence-status

Deberías ver tu preset activo, el ID de proyecto para el repositorio actual y el tamaño de los almacenes de modelo + telemetría. Para una lista de verificación Zero-Trust enfocada:

/presence-status --zerotrust

Para un diagnóstico completo:

/presence-doctor

Para auto-corregir problemas recuperables (deriva de permisos, manifiesto faltante, marcador .integrity-blocked obsoleto):

PYTHONPATH=~/.claude/plugins/presence/lib python3 ~/.claude/plugins/presence/lib/doctor.py --fix

Presets

presence incluye cuatro paquetes de presets. Cambia en cualquier momento:

/presence-preset use solo-dev
/presence-preset use team-oss
/presence-preset use enterprise-strict
/presence-preset use zerotrust

Preset	Modelo	Telemetría	Puerta de commit	Puerta de Stop	En reposo
`solo-dev` (predeterminado)	activo, conciso	activo, sin verificación de PR	desactivado (solo asesoría vía Stop)	silencioso (registrado, mostrado en la próxima sesión)	plano
`team-oss`	activo, verboso	activo, verificación de PR opcional	advertir (texto de asesoría inyectado)	silencioso	plano
`enterprise-strict`	activo, verboso, auditoría	activo, registro de auditoría	bloquear (rechaza commit)	bloquear (re-pregunta sobre éxito no verificado)	plano
`zerotrust`	activo, cifrado, auditoría	activo, cifrado, auditoría, sin verificación de PR	bloquear	bloquear	AES-GCM + llavero

Presets personalizados: coloca un <name>.json en ~/.claude/presence/presets/ y cambia a él.

Ver docs/zerotrust.md para el perfil Zero-Trust en detalle y CHANGELOG.md para el diff por versión.

Desinstalación

/plugin uninstall presence

O, para instalación local:

~/.claude/plugins/presence/install.sh --uninstall

El estado en ~/.claude/presence/ se conserva por defecto. Pasa --purge para también eliminar el estado. Bajo el preset Zero-Trust, también usa /presence-reset --crypto para rotar la clave del llavero y borrar el estado cifrado.

Privacidad

Todo el estado es local. Nada se sube nunca.
Sin analíticas, sin telemetría al proveedor, sin llamadas remotas.
La habilidad outcome-check hace una llamada gh opcional para leer el estado de PR si gh está en $PATH y autenticado; esto golpea la API de GitHub directamente, no a terceros. Deshabilítalo en el preset.
Bajo zerotrust, incluso esa llamada opcional está deshabilitada.
Perfiles de redacción componibles para patrones relevantes por jurisdicción (PII de la UE, PII de EE. UU., PCI-DSS) se incluyen en presets/redaction/. Ver docs/compliance.md para el alcance honesto (presence no tiene certificación formal).

Arquitectura

Ver docs/architecture.md para el diseño completo: qué hace cada hook, cómo se organiza el estado, el esquema de contexto XML y cómo escribir un preset personalizado.

Documentación

Empieza en docs/index.md para un mapa. Destacados:

docs/architecture.md - cómo encajan las piezas
docs/security.md - modelo de amenazas (T1 a T12)
docs/zerotrust.md - el perfil Zero-Trust opcional
docs/compliance.md - qué hace y qué no hace presence para cargas de trabajo reguladas (sin marco de certificación)
docs/glossary.md - definiciones de términos específicos del proyecto
docs/recipes.md - personalizaciones comunes de ajustes preestablecidos
docs/roadmap.md - qué hemos diferido y por qué
SECURITY.md, CONTRIBUTING.md, bench/README.md, llms.txt

Reportar errores

Abre un issue en GitHub usando la plantilla de errores. Para hallazgos de seguridad, no publiques un issue público: sigue el proceso de divulgación privada en SECURITY.md.

Aviso legal

presence se proporciona tal cual bajo la Licencia Apache 2.0, sin garantía de ningún tipo, expresa o implícita. Los autores y titulares de derechos de autor (Sara Star Quant LLC) y cualquier colaborador no son responsables de ningún daño, pérdida de datos, incidente de seguridad, regresión, pérdida de productividad u otro resultado adverso que surja de la instalación o el uso de este plugin.

Este proyecto no es asesoramiento de ningún tipo:

No es asesoramiento legal. El modelo de seguridad documentado en docs/security.md y docs/zerotrust.md es informativo. No es una atestación de cumplimiento, certificación o garantía bajo ningún marco regulatorio (GDPR, HIPAA, SOC 2, ISO 27001, etc.). Si operas en un entorno regulado, consulta a un asesor calificado antes de confiar en las propiedades de este plugin.
No es asesoramiento de seguridad. El ajuste preestablecido Zero-Trust reduce la superficie de ataque y añade controles en capas (cifrado en reposo, registro de auditoría, integridad de cierre ante fallos, compuertas de confirmación estrictas), pero no sustituye un modelado de amenazas adecuado, pruebas de penetración o revisión de seguridad operativa en tu entorno específico.
No es asesoramiento de ingeniería. La compuerta de confianza calibrada y el modelo de proyecto vivo son empujones útiles, no pruebas de corrección. Reducen un modo de fallo común (afirmar finalización sin verificación); no reemplazan pruebas, revisión de código o tu propio criterio.

Al instalar o usar presence, aceptas plena responsabilidad por:

Revisar el código fuente antes de ejecutarlo en tu sistema o en cualquier sesión que toque datos sensibles.
Verificar que las propiedades documentadas (sin salida de red, estado solo local, patrones de redacción, formato de cifrado, etc.) realmente coincidan con lo que tu entorno requiere.
Cualquier consecuencia posterior de decisiones tomadas o afirmaciones aceptadas mientras presence estuvo activo en tus sesiones, incluyendo, entre otros: código confirmado, código revertido, configuraciones cambiadas e inferencias extraídas del modelo de proyecto o del resumen de telemetría.

Los términos legales completos están en LICENSE. La sección de Aviso legal de este README es un resumen informativo del espíritu de esos términos; en caso de conflicto, la LICENCIA prevalece.

Licencia

Apache-2.0, ver LICENSE.