Telemetry

SessionFS collects anonymous usage telemetry to help us understand adoption and improve the product. This page is the full disclosure.

What is sent

Six funnel events, each carrying four fields and nothing else:

Event	When	Fields
install	First time SessionFS runs on a machine	install_id, version, os, event_ts
init_completed	sfs init wizard finishes successfully	install_id, version, os, event_ts
first_capture	First session ever captured (daemon or sfs recapture)	install_id, version, os, event_ts
first_magic	First memory read (resume, MCP search/recall/ask)	install_id, version, os, event_ts
heartbeat	Daemon is alive (at most once per 24h)	install_id, version, os, event_ts
capture_degraded	Reserved — not yet emitted	install_id, version, os, event_ts, tool

Fields

Field	Description
install_id	Random UUID4 hex, generated once at ~/.sessionfs/install_id. Not derived from any identifying data.
version	SessionFS version string (e.g. 0.29.11)
os	darwin, linux, or windows
event	One of the six event names above
event_ts	ISO-8601 UTC timestamp of the event
tool	Only sent with capture_degraded — the AI tool name (≤50 chars)

The payload is posted to https://api.sessionfs.dev/api/v1/telemetry with no authentication. The server records the event and returns {"status": "ok"}.

What is NEVER sent

• File paths, workspace paths, or project names
• Session content, messages, or tool calls
• Email addresses, user names, or hostnames
• API keys, tokens, or credentials
• Git remotes, branch names, or commit SHAs
• Environment variable values

A server-side _contains_pii() guard rejects any payload that contains an email-like or IP-address-like string. The emitter never includes any of the above fields in the first place.

Where telemetry goes

Payloads are POSTed to the configured API server. For the hosted product that is api.sessionfs.dev; if you set SESSIONFS_API_URL (self-hosted), telemetry goes to your own server, not to SessionFS.

A long-running daemon picks up a config-file opt-out on its next config reload or within 24 hours (the daily heartbeat re-reads the config); sfs daemon restart applies it immediately. The env-var opt-out applies to any process started after it is set.

Opting out

Two independent opt-outs, either of which disables all telemetry:

1. Environment variable

export SFS_NO_TELEMETRY=1

Any non-empty value disables telemetry. This takes precedence over the config file and is checked before any thread spawn or network attempt.

2. Config file

In ~/.sessionfs/config.toml:

[telemetry]
enabled = false

Set enabled = true (or remove the block) to re-enable. Missing key defaults to enabled.

Marketplace install counts (signed-in only)

Separate from the anonymous telemetry above: when you are signed in, the CLI and the daemon count installs of packages from the hosted SessionFS Marketplace, so publishers and organization admins see real usage.

What is sent: POST /api/v1/marketplace/versions/{version_id}/events with your API key, carrying only the event (install from sfs skill add or a pull / daemon install, uninstall from sfs skill remove, active when sfs skill pull or the daemon’s skill reconcile finds the package still installed, translation_failure when a package cannot be translated for a tool), the target tools, the source (download or reconcile), and optionally a project_id used only to pick the organization. No paths, session content or package files; local and git packages are never counted.

Account and organization linkage: the server keeps a SHA-256 of your account (or service key) id for a 30-day de-duplication window (one count per account, version, tool, event and day), then deletes it, and otherwise stores daily totals only. Each total records the consuming organization: an org-private package counts toward its own organization, a personal package toward none, and a public package toward your project’s (or default / only) organization. Only that organization’s owners and admins see its totals. Publishers see aggregates only, with counts under 10 shown as <10, and never which organizations installs came from.

Shown before anything is sent. Install counts have their own one-time notice (marker ~/.sessionfs/telemetry-markers/skill-usage-disclosure-shown, separate from the telemetry notice, so people who saw the telemetry notice before install counts existed are still told). The first interactive sfs skill command on a terminal that would send a count prints the notice first; the first-run telemetry notice and sfs init / sfs daemon start also show it. Until it has been shown, nothing is sent, including from the daemon and non-terminal runs, unless you set SFS_SKILL_USAGE_REPORTING=1 explicitly. The opt-outs below always win.

The daemon: while signed in, its periodic skill reconcile sends install / active counts for assigned packages, at most one active per package and tool per day.

Opting out: SFS_SKILL_USAGE_REPORTING=0 (or false, off, no) stops only these counts; either telemetry opt-out (SFS_NO_TELEMETRY or [telemetry] enabled = false) also stops them. A failed or disabled count never affects the command.

Data retention

Telemetry events are stored server-side in the telemetry_events table. We retain them indefinitely for aggregate trend analysis. No personal data is linked to install IDs.

Questions

Open an issue at github.com/sessionfs/sessionfs or email support@sessionfs.dev.