Presence

Memória entre sessões e um portal de verificação para Claude Code

Documentação

presence

Novo na v0.8.0: notificador webhook opcional para veredictos do portão de confiança, desativado por padrão e forçadamente desabilitado sob zerotrust. Veja docs/recipes.md.

Toda sessão do Claude Code começa do zero. presence faz a próxima começar de onde a última parou.

Um plugin do Claude Code com projeções somente leitura (servidor MCP, adaptador AGENTS.md) para que clientes compatíveis com MCP (Cursor, Claude Desktop, Continue) e ferramentas compatíveis com AGENTS.md (Codex, Gemini CLI, Windsurf, GitHub Copilot) também possam ler seu contexto acumulado. Transforma cada sessão em parte de um continuum.

presence adiciona quatro coisas ao Claude Code, globalmente, com uma única instalação e zero configuração por projeto:

Modelo vivo do projeto. Claude constrói e reutiliza notas sobre cada repositório que toca. Chega de redescobrir a mesma arquitetura a cada sessão.
Telemetria de resultados. Rastreia o que Claude commitou e depois monitora reversões, emendas e fechamentos de PRs. Sessões futuras veem "suas últimas 3 alterações aqui foram revertidas em 24h" em vez de repetir o mesmo erro.
Resumo de eventos. Alterações de arquivos, falhas de teste e resultados de build que ocorreram entre turnos são exibidos no próximo prompt, sem necessidade de consulta manual.
Confiança calibrada. O hook Stop verifica se alegações de sucesso ("corrigido", "concluído", "funciona") são respaldadas por verificação real (testes executados, build verde) desde a alteração. Avisa quando não são. Portão rígido opcional em git commit/push.

O estado vive em ~/.claude/presence/, totalmente local, nunca enviado.

Instalação (30 segundos)

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

Sem Python 3.12+? Acrescente -s -- --bootstrap para instalá-lo automaticamente via uv (uma chamada para astral.sh). O comando simples acima faz zero chamadas externas.

Isso é tudo. Instalador idempotente, não faz chamadas de rede externas além de buscar a si mesmo, aplica-se globalmente a todos os projetos do Claude Code. Reinicie o Claude Code e execute /presence-status para confirmar. Para opções (--bootstrap para instalar Python automaticamente, --verify, --build-ext para o caminho rápido nativo), veja Quickstart abaixo.

Pelos números

Métrica	Padrão (stdlib)	Com `--build-ext`	Método
Inicialização a frio do hook	82 ms mediana	8,9 ms mediana	n=50 / n=30, `bench/cold_startup.py`
SessionStart populado	112 ms mediana	9,1 ms mediana	modelo de 10 KB + 100 eventos + 50 alegações
Sessão agregada (77 disparos)	6,4 s	770 ms	n=10 / n=5, `bench/aggregate_session.py`
Instalação + primeiro /presence-status	245 ms total	245 ms total	n=25, `bench/install_to_working.py`
Testes	291 passando		Python 3.12 + 3.13 + 3.14 em Linux + macOS
Dependências de runtime (padrão)	0 (somente stdlib)		uma opcional: `cryptography` para criptografia em repouso Zero-Trust
Opcional com `--build-ext`		toolchain Rust no momento da instalação	binário então roda sem Rust
Superfície	4 presets, 6 hooks, 6 comandos slash, 3 skills, 1 subagente, 1 servidor MCP, 1 adaptador entre ferramentas, 3 perfis de redação		perfis de redação opcionais para cargas reguladas
Egresso de rede	0 nos presets padrão		chamada de status de PR `gh` opcional; `--bootstrap` / `--download-ext` opcionais; todos desabilitados por padrão
Plataformas	macOS arm64 + Linux x86_64 (CI)		Windows: instale no WSL2

A coluna --build-ext reflete aceleração nativa opcional via cliente daemon Rust (./install.sh --build-ext para compilar localmente, ou --download-ext para buscar um binário pré-compilado do último release). Sem isso, os hooks rodam no caminho somente stdlib. Veja bench/HISTORY.md para o histórico completo de benchmarks por versão.

Todas as medições: macOS arm64, Python 3.14.4. Reproduza localmente com python3 bench/<name>.py --runs N. Veja bench/README.md para a convenção completa.

Alterações recentes: veja CHANGELOG.md para o diff completo por versão. v0.8.0 traz um notificador webhook opcional para veredictos do portão de confiança, controlado pelo mesmo interruptor zerotrust network.egress_allowed da verificação de atualização do release. v0.5.0 traz perfis de redação compostos para dados sensíveis cientes de jurisdição. Opcional via redact.profiles nas configurações: pii-eu, pii-us, pci-dss (correspondências PAN controladas por Luhn). Novo docs/compliance.md diz exatamente o que presence faz e não faz para cargas reguladas. Sem enquadramento de certificação: nomes de perfil descrevem classes de dados, não estruturas de conformidade. v0.4.2 traz o adaptador AGENTS.md entre ferramentas. Defina PRESENCE_HOST=agents-md e presence atualiza <repo>/AGENTS.md a cada SessionStart do Claude Code, captado automaticamente por Codex, Cursor, Gemini CLI, Windsurf, GitHub Copilot e outros que leem o padrão aberto AGENTS.md. Veja docs/multi-host.md. v0.4.1 trouxe o servidor MCP: qualquer cliente compatível com MCP (Claude Desktop, Cursor, Continue, agentes personalizados) pode ler o modelo vivo + telemetria de resultados do presence via JSON-RPC stdio. Veja docs/mcp.md. v0.4.0 trouxe o cliente daemon Rust + daemon Python aquecido + costura de adaptador. Opcional via --build-ext / --download-ext. Reduz a latência do caminho crítico de 82 ms para 8,9 ms (-89%). v0.3.x reduziu a latência do hook a frio em ~27% e corrigiu um bug latente do v0.2 em que usuários Zero-Trust tinham seu resumo de eventos silenciosamente esvaziado. v0.2.0 trouxe o preset Zero-Trust: AES-GCM em repouso, log de auditoria à prova de adulteração, integridade SessionStart com falha fechada. Veja docs/zerotrust.md.

Quickstart

Se este é seu primeiro plugin do Claude Code: basta executar estes dois comandos.

1. Instalação

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

O instalador é idempotente. Ele verifica Python 3.12+, cria symlink do plugin em ~/.claude/plugins/presence, cria o diretório de estado em ~/.claude/presence/ com permissões 0700, gera MANIFEST.lock e pré-compila lib/ para bytecode.

Se você não tiver Python 3.12+, o instalador imprime um aviso e continua; presence é instalado, mas permanece inativo até que um Python 3.12+ esteja em PATH. Isso é intencional para que você possa instalar em uma máquina que receberá Python depois (ou executar --bootstrap). Para instalar Python 3.13 automaticamente via uv (binário único, sem sudo, ~5 MB), passe --bootstrap:

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

--bootstrap é opcional porque faz uma chamada de rede para astral.sh. O caminho de instalação padrão não faz chamadas externas.

2. Verifique se funciona

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

Verifica o symlink, o registro do plugin em settings.json, permissões, Python, a integridade de MANIFEST.lock e dispara sinteticamente todos os 6 hooks contra a árvore lib/ real. Saída 0 significa pronto. Linhas FAIL dizem exatamente o que está faltando. Para saída legível por máquina: --verify --json.

3. Use

Reinicie o Claude Code (ou abra uma nova sessão) em qualquer repositório e execute /presence-status.

Outros métodos de instalação

Via fluxo de marketplace de plugins do Claude Code

O repositório traz seu próprio marketplace.json para que possa ser adicionado diretamente:

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

Via git clone

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

Para a criptografia em repouso do preset Zero-Trust (opcional), instale também a biblioteca cryptography no mesmo Python usado pelo presence. Em macOS/Linux modernos isso importa porque Homebrew e a maioria das distros marcam o Python do sistema como gerenciado externamente (PEP 668); um pip install puro sai com error: externally-managed-environment.

Escolha o caminho que corresponde a como você obteve o 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

Se não souber qual Python o presence está usando, execute /presence-doctor e observe as linhas pinned python / python, depois use o -m pip install cryptography desse interpretador.

Outros presets e o restante dos controles Zero-Trust (verificação de integridade, redação, portões, log de auditoria) são somente stdlib.

Atualização

Para instalações feitas via curl ou git clone:

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

--update faz git fetch + git pull --ff-only + uma nova execução do instalador. Ele se recusa a prosseguir se a árvore de trabalho tiver alterações não commitadas (para nunca sobrescrever trabalho em andamento). Para instalações feitas via fluxo /plugin, use o mecanismo nativo de atualização de plugins do Claude Code.

Receba notificações de novos releases (opcional)

/presence-doctor pode exibir a tag mais recente publicada em comparação à sua versão instalada. Desativado por padrão; ative adicionando o seguinte a ~/.claude/presence/settings.json:

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

O próximo SessionStart pré-aquece um cache de 24 h (um GET HTTPS anônimo para api.github.com); o doctor então renderiza uma linha, ex.: latest : v0.6.0 (you have v0.5.4) [checked 12h ago]. Forçadamente desligado sob o preset zerotrust (sem egresso de rede nessa postura). Execute /presence-doctor --refresh para ignorar o TTL ao verificar uma tag nova.

Verificar instalação

A verificação mais rápida é ./install.sh --verify da seção anterior. De dentro do Claude Code você também pode executar:

/presence-status

Você deve ver seu preset ativo, o ID do projeto para o repositório atual e o tamanho dos armazenamentos de modelo + telemetria. Para uma lista de verificação Zero-Trust focada:

/presence-status --zerotrust

Para um diagnóstico completo:

/presence-doctor

Para corrigir automaticamente problemas recuperáveis (desvio de permissões, manifesto ausente, marcador .integrity-blocked obsoleto):

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

Presets

presence vem com quatro pacotes de preset. Alterne a qualquer momento:

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

Preset	Modelo	Telemetria	Portão de commit	Portão Stop	Em repouso
`solo-dev` (padrão)	ativo, conciso	ativo, sem verificação de PR	desligado (somente consultivo via Stop)	silencioso (registrado, exibido na próxima sessão)	simples
`team-oss`	ativo, detalhado	ativo, verificação de PR opcional	avisar (texto consultivo injetado)	silencioso	simples
`enterprise-strict`	ativo, detalhado, auditoria	ativo, log de auditoria	bloquear (recusa commit)	bloquear (re-pergunta em sucesso não verificado)	simples
`zerotrust`	ativo, criptografado, auditoria	ativo, criptografado, auditoria, sem verificação de PR	bloquear	bloquear	AES-GCM + keychain

Presets personalizados: coloque um <name>.json em ~/.claude/presence/presets/ e alterne para ele.

Veja docs/zerotrust.md para o perfil Zero-Trust em detalhes e CHANGELOG.md para o diff por versão.

Desinstalação

/plugin uninstall presence

Ou, para instalação local:

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

O estado em ~/.claude/presence/ é preservado por padrão. Passe --purge para também remover o estado. Sob o preset Zero-Trust, use também /presence-reset --crypto para rotacionar a chave do keychain e apagar o estado criptografado.

Privacidade

Todo o estado é local. Nada é nunca enviado.
Sem analytics, sem telemetria para fornecedores, sem chamadas remotas.
A skill outcome-check faz uma chamada gh opcional para ler o status de PR se gh estiver em $PATH e autenticado; isso acessa a API do GitHub diretamente, não terceiros. Desative no preset.
Sob zerotrust, até essa chamada opcional é desabilitada.
Perfis de redação compostos para padrões relevantes por jurisdição (PII da UE, PII dos EUA, PCI-DSS) vêm em presets/redaction/. Veja docs/compliance.md para o escopo honesto (presence não tem certificação formal).

Arquitetura

Veja docs/architecture.md para o design completo: o que cada hook faz, como o estado é organizado, o esquema de contexto XML e como escrever um preset personalizado.

Documentação

Comece em docs/index.md para um mapa. Destaques:

docs/architecture.md - como as peças se encaixam
docs/security.md - modelo de ameaças (T1 a T12)
docs/zerotrust.md - o perfil Zero-Trust opt-in
docs/compliance.md - o que o presence faz / não faz para cargas de trabalho regulamentadas (sem enquadramento de certificação)
docs/glossary.md - definições para termos específicos do projeto
docs/recipes.md - personalizações comuns de predefinições
docs/roadmap.md - o que adiamos e por quê
SECURITY.md, CONTRIBUTING.md, bench/README.md, llms.txt

Relatando bugs

Abra uma issue no GitHub usando o modelo de bug. Para achados de segurança, não abra uma issue pública - siga o processo de divulgação privada em SECURITY.md.

Aviso Legal

presence é fornecido como está sob a Apache License 2.0, sem garantia de qualquer tipo, expressa ou implícita. Os autores e detentores de direitos autorais (Sara Star Quant LLC) e quaisquer contribuidores não são responsáveis por qualquer dano, perda de dados, incidente de segurança, regressão, perda de produtividade ou outro resultado adverso decorrente da instalação ou uso deste plugin.

Este projeto não é aconselhamento de nenhum tipo:

Não é aconselhamento jurídico. O modelo de segurança documentado em docs/security.md e docs/zerotrust.md é informativo. Não é uma atestação de conformidade, certificação ou garantia sob qualquer estrutura regulatória (GDPR, HIPAA, SOC 2, ISO 27001, etc.). Se você opera em um ambiente regulamentado, consulte um advogado qualificado antes de confiar nas propriedades deste plugin.
Não é aconselhamento de segurança. A predefinição Zero-Trust reduz a superfície de ataque e adiciona controles em camadas (criptografia em repouso, log de auditoria, integridade com falha fechada, portões de commit rígidos), mas não substitui a modelagem de ameaças adequada, testes de penetração ou revisão de segurança operacional no seu ambiente específico.
Não é aconselhamento de engenharia. O portão de confiança calibrada e o modelo de projeto vivo são empurrões úteis, não provas de correção. Eles reduzem um modo de falha comum (afirmar conclusão sem verificação); eles não substituem testes, revisão de código ou seu próprio julgamento.

Ao instalar ou usar o presence, você aceita total responsabilidade por:

Revisar o código-fonte antes de executá-lo no seu sistema ou em qualquer sessão que lide com dados sensíveis.
Verificar se as propriedades documentadas (sem saída de rede, estado somente local, padrões de redação, formato de criptografia, etc.) realmente correspondem ao que seu ambiente exige.
Quaisquer consequências posteriores de decisões tomadas ou alegações aceitas enquanto o presence estava ativo em suas sessões, incluindo, mas não se limitando a: código commitado, código revertido, configurações alteradas e inferências extraídas do modelo de projeto ou resumo de telemetria.

Os termos legais completos estão em LICENSE. A seção de Aviso Legal deste README é um resumo informativo do espírito desses termos; em caso de conflito, o LICENSE prevalece.

Licença

Apache-2.0, veja LICENSE.