presence

> **New in v0.8.0:** opt-in webhook notifier for confidence-gate verdicts, off by default and hard-disabled under `zerotrust`. See `docs/recipes.md`.

Every Claude Code session starts cold. presence makes the next one start where the last one left off.

A Claude Code plugin with read-only projections (MCP server, AGENTS.md adapter) so MCP-aware clients (Cursor, Claude Desktop, Continue) and AGENTS.md-aware tools (Codex, Gemini CLI, Windsurf, GitHub Copilot) can also read its accumulated context. Turns every session into part of a continuum.

`presence` adds four things to Claude Code, globally, with one install and zero per-project setup:

1. Living project model. Claude builds and reuses notes about each repo it touches. No more re-deriving the same architecture every session.

2. Outcome telemetry. Tracks what Claude committed, then watches for reverts, amends, and PR closes. Future sessions see "your last 3 changes here were reverted within 24h" instead of repeating the same mistake.

3. Event digest. File changes, test failures, and build results that happened between turns are surfaced at the next prompt instead of needing to be polled.

4. Calibrated confidence. The Stop hook checks whether success claims ("fixed", "done", "works") are backed by actual verification (tests run, build green) since the change. Warns when they're not. Optional hard gate on `git commit`/`push`.

State lives in `~/.claude/presence/`, fully local, never uploaded.

Install (30 seconds)

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

> No Python 3.12+? Append `-s -- --bootstrap` to auto-install it via uv (one call to astral.sh). The plain command above makes zero outbound calls.

That's the whole thing. Idempotent installer, makes no outbound network calls beyond fetching itself, applies globally to every Claude Code project. Restart Claude Code and run `/presence-status` to confirm. For options (`--bootstrap` to auto-install Python, `--verify`, `--build-ext` for the native fast path), see Quickstart below.

By the numbers

The `--build-ext` column reflects optional native acceleration via the Rust daemon client (`./install.sh --build-ext` to compile locally, or `--download-ext` to fetch a pre-built binary from the latest release). Without it, hooks run on the stdlib-only path. See `bench/HISTORY.md` for the full version-by-version benchmark history.

All measurements: macOS arm64, Python 3.14.4. Reproduce locally with `python3 bench/.py --runs N`. See `bench/README.md` for the full convention.

> Recent changes: see `CHANGELOG.md` for the full per-version diff.

> v0.8.0 ships an opt-in webhook notifier for confidence-gate verdicts, gated by the same `network.egress_allowed` zerotrust switch as the release-freshness check.

> v0.5.0 ships composable redaction profiles for jurisdiction-aware sensitive data. Opt-in via `redact.profiles` in settings: `pii-eu`, `pii-us`, `pci-dss` (PAN matches gated by Luhn). New `docs/compliance.md` says exactly what presence does and does not do for regulated workloads. No certification framing: profile names describe data classes, not compliance frameworks.

> v0.4.2 ships the cross-tool AGENTS.md adapter. Set `PRESENCE_HOST=agents-md` and presence refreshes `/AGENTS.md` on every Claude Code SessionStart, picked up automatically by Codex, Cursor, Gemini CLI, Windsurf, GitHub Copilot, and others reading the open AGENTS.md standard. See `docs/multi-host.md`.

> v0.4.1 shipped the MCP server: any MCP-aware client (Claude Desktop, Cursor, Continue, custom agents) can read presence's living model + outcome telemetry over JSON-RPC stdio. See `docs/mcp.md`.

> v0.4.0 shipped the Rust daemon client + warm Python daemon + adapter seam. Optional via `--build-ext` / `--download-ext`. Cuts hot-path latency from 82 ms to 8.9 ms (-89%).

> v0.3.x cut cold-hook latency by ~27% and fixed a latent v0.2 bug where Zero-Trust users had their event digest silently emptied.

> v0.2.0 shipped the Zero-Trust preset: AES-GCM at rest, tamper-evident audit log, fail-closed SessionStart integrity. See `docs/zerotrust.md`.

Quickstart

If this is your first Claude Code plugin: just run these two commands.

1. Install

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

The installer is idempotent. It checks for Python 3.12+, symlinks the plugin into `~/.claude/plugins/presence`, creates the state directory at `~/.claude/presence/` with `0700` perms, generates `MANIFEST.lock`, and pre-compiles `lib/` to bytecode.

If you don't have Python 3.12+, the installer prints a warning and continues; presence is installed but stays inactive until a 3.12+ Python is on `PATH`. This is intentional so you can install on a machine that will get Python later (or run `--bootstrap`). To auto-install Python 3.13 via uv (single binary, no sudo, ~5 MB), pass `--bootstrap`:

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

`--bootstrap` is opt-in because it makes one network call to `astral.sh`. The default install path makes no outbound calls.

2. Verify it works

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

Checks the symlink, plugin registration in `settings.json`, perms, Python, the `MANIFEST.lock` integrity, and synthetically fires all 6 hooks against the real lib/ tree. Exit 0 means ready. `FAIL` lines tell you exactly what is missing. For machine-readable output: `--verify --json`.

3. Use it

Restart Claude Code (or open a new session) in any repo and run `/presence-status`.

Other install methods

Via the Claude Code plugin marketplace flow

The repo ships its own `marketplace.json` so it can be added directly:

/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

For the Zero-Trust preset's at-rest encryption (opt-in), also install the `cryptography` library into the same Python presence uses. On modern macOS / Linux this matters because Homebrew and most distros mark the system Python as PEP 668 externally-managed; a bare `pip install` exits with `error: externally-managed-environment`.

Pick the path that matches how you got 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

If unsure which Python presence is using, run `/presence-doctor` and look at the `pinned python` / `python` lines, then use that interpreter's `-m pip install cryptography`.

Other presets and the rest of the Zero-Trust controls (integrity check, redaction, gates, audit log) are stdlib-only.

Update

For installs done via curl or git clone:

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

`--update` does `git fetch` + `git pull --ff-only` + a re-run of the installer. It refuses to proceed if the working tree has uncommitted changes (so it never clobbers WIP). For installs done via the `/plugin` flow, use Claude Code's native plugin update mechanism.

Get notified of new releases (opt-in)

`/presence-doctor` can surface the latest released tag against your installed version. Off by default; enable by adding the following to `~/.claude/presence/settings.json`:

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

The next SessionStart pre-warms a 24 h cache (one anonymous HTTPS GET to `api.github.com`); the doctor then renders one line, e.g. `latest : v0.6.0 (you have v0.5.4) [checked 12h ago]`. Forced off under the `zerotrust` preset (no network egress under that posture). Run `/presence-doctor --refresh` to bypass the TTL when verifying a fresh tag.

Verify install

The fastest check is `./install.sh --verify` from the previous section. From inside Claude Code you can also run:

/presence-status

You should see your active preset, the project ID for the current repo, and the size of the model + telemetry stores. For a focused Zero-Trust checklist:

/presence-status --zerotrust

For a full diagnostic:

/presence-doctor

To auto-correct recoverable issues (perm drift, missing manifest, stale `.integrity-blocked` marker):

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

Presets

`presence` ships with four preset bundles. Switch any time:

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

Custom presets: drop a `.json` in `~/.claude/presence/presets/` and switch to it.

See `docs/zerotrust.md` for the Zero-Trust profile in detail and `CHANGELOG.md` for the per-version diff.

Uninstall

/plugin uninstall presence

Or, for local install:

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

State at `~/.claude/presence/` is preserved by default. Pass `--purge` to also remove state. Under the Zero-Trust preset, also use `/presence-reset --crypto` to rotate the keychain key and wipe encrypted state.

Privacy

• All state is local. Nothing is ever uploaded.
• No analytics, no telemetry-to-vendor, no remote calls.
• The `outcome-check` skill makes one optional `gh` call to read PR status if `gh` is on `$PATH` and authenticated; this hits GitHub's API directly, not any third party. Disable in preset.
• Under `zerotrust`, even that optional call is disabled.
• Composable redaction profiles for jurisdiction-relevant patterns (EU PII, US PII, PCI-DSS) ship in `presets/redaction/`. See `docs/compliance.md` for the honest scope (presence has no formal certification).

Architecture

See `docs/architecture.md` for the full design: what each hook does, how state is laid out, the XML context schema, and how to write a custom preset.

Documentation

Start at `docs/index.md` for a map. Highlights:

• `docs/architecture.md` - how the pieces fit together
• `docs/security.md` - threat model (T1 through T12)
• `docs/zerotrust.md` - the opt-in Zero-Trust profile
• `docs/compliance.md` - what presence does / does not do for regulated workloads (no certification framing)
• `docs/glossary.md` - definitions for project-specific terms
• `docs/recipes.md` - common preset customizations
• `docs/roadmap.md` - what we've deferred and why
• `SECURITY.md`, `CONTRIBUTING.md`, `bench/README.md`, `llms.txt`

Reporting bugs

Open a GitHub issue using the bug template. For security findings, do not file a public issue - follow the private disclosure process in `SECURITY.md`.

Disclaimer

`presence` is provided as is under the Apache License 2.0, without warranty of any kind, express or implied. The authors and copyright holders (Sara Star Quant LLC) and any contributors are not responsible for any damage, data loss, security incident, regression, lost productivity, or other adverse outcome arising from the installation or use of this plugin.

This project is not advice of any kind:

• Not legal advice. The security model documented in `docs/security.md` and `docs/zerotrust.md` is informational. It is not a compliance attestation, certification, or guarantee under any regulatory framework (GDPR, HIPAA, SOC 2, ISO 27001, etc.). If you operate in a regulated environment, consult qualified counsel before relying on this plugin's properties.
• Not security advice. The Zero-Trust preset reduces attack surface and adds layered controls (encryption at rest, audit log, fail-closed integrity, hard commit gates) but is not a substitute for proper threat modeling, penetration testing, or operational security review in your specific environment.
• Not engineering advice. The calibrated-confidence gate and the living project model are useful nudges, not proofs of correctness. They reduce one common failure mode (asserting completion without verification); they do not replace tests, code review, or your own judgment.

By installing or using `presence`, you accept full responsibility for:

• Reviewing the source before running it on your system or in any session that touches sensitive data.
• Verifying that the documented properties (no network egress, local-only state, redaction patterns, encryption format, etc.) actually match what your environment requires.
• Any downstream consequences of decisions made or claims accepted while presence was active in your sessions, including but not limited to: code committed, code reverted, settings changed, and inferences drawn from the project model or telemetry digest.

The full legal terms are in LICENSE. This README's Disclaimer section is an informational summary of the spirit of those terms; in any conflict, the LICENSE controls.

License

Apache-2.0, see LICENSE.