cctally 1.62.0 → 1.64.0

package/CHANGELOG.md

@@ -5,6 +5,16 @@ based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.64.0] - 2026-07-07
+
+### Added
+- cctally now sends an anonymous, opt-out install-count beat at most once a day so the project can gauge how many people actually use it. It is deliberately minimal and private: the only thing transmitted is a one-way token that rotates every month (derived from a random local id that never leaves your machine and cannot be recovered from the token), plus the cctally version and a coarse operating-system family (macos/linux/windows/other) — no IP, username, file paths, project names, or usage data — and nothing leaves your machine for at least 24 hours after first run, so you always have a window to opt out first. Run `cctally telemetry` to see the current state, why it is on or off, and exactly what would be sent; `cctally telemetry off` disables it (`cctally telemetry on` re-enables), `cctally telemetry reset` rotates your local id, and `cctally doctor` shows a read-only telemetry line. It is also disabled by `cctally config set telemetry.enabled false`, `CCTALLY_DISABLE_TELEMETRY=1`, the `DO_NOT_TRACK` convention, and automatically in development checkouts. Full transparency page — token construction, retention, and an honest threat model — is in [docs/telemetry.md](docs/telemetry.md).
+
+## [1.63.0] - 2026-07-07
+
+### Added
+- `cctally statusline --usage-only` renders just the subscription usage chip (`5h X% · 7d Y%`), dropping the model, cost, burn-rate, context, and reset-countdown segments — for users who want a small quota indicator in their prompt without the cost telemetry. Persist it with `cctally config set statusline.usage_only true`; `--no-usage-only` forces the full statusline when the config key is on. Contributed by @nathanm4 (public PR #3).
+
 ## [1.62.0] - 2026-07-06
 
 ### Changed

package/README.md

@@ -154,6 +154,12 @@ If you also use OpenAI's Codex CLI, `cctally codex daily / monthly / session` ar
 
 `cctally doctor` gives you a read-only health check - install, hooks, sign-in, database, data freshness, pricing, and safety - and the same status shows up in the dashboard. `cctally pricing-check` warns you when the built-in model pricing is getting stale, `cctally db` manages the local database, and `cctally update` keeps your install current. The local cache is always safe to delete or rebuild.
 
+## Privacy & telemetry
+
+cctally sends an anonymous, opt-out **install-count beat** — at most once a day — so the project can gauge how many people actually use it (npm and GitHub numbers are drowned in bots and mirrors). The entire payload is a one-way token that rotates every month (derived from a random local id that never leaves your machine and can't be recovered from the token), the cctally version, and a coarse OS family (`macos`/`linux`/`windows`/`other`). No identity, file paths, prompts, usage data, or stored IP — ever. Nothing leaves your machine for at least 24 hours after first run, so you always have a window to opt out first.
+
+Turn it off any time with `cctally telemetry off` (or `cctally config set telemetry.enabled false`, `CCTALLY_DISABLE_TELEMETRY=1`, or the community-standard `DO_NOT_TRACK=1`); it's also off automatically in dev checkouts. Run `cctally telemetry` to see the current state and exactly what would be sent. The full transparency page — token construction, retention, and an honest threat model — is [docs/telemetry.md](docs/telemetry.md).
+
 ## A faster, local-first ccusage
 
 `cctally` started as a local replacement for [`ccusage`](https://github.com/ryoppippi/ccusage) and stays compatible at the level of common flows: `cctally claude <cmd>` is a drop-in for `ccusage claude <cmd>` (and `cctally codex <cmd>` for `ccusage codex <cmd>`), with the flat forms (`cctally daily`, `cctally codex-daily`, …) kept as aliases. Paste your ccusage commands verbatim - then reach for the dashboard, forecast, trend, conversation viewer, and alerts that ccusage doesn't have.
@@ -176,6 +182,7 @@ It's also fast. Pricing is built in and computed in-process from a local SQLite
 - [Configuration](docs/configuration.md): `config.json` shape and week-start rules.
 - [Architecture](docs/architecture.md): data flow, caches, week boundaries.
 - [Runtime data](docs/runtime-data.md): what lives in `~/.local/share/cctally/`.
+- [Telemetry](docs/telemetry.md): the anonymous install-count beat, in full — and how to opt out.
 - [Command reference](docs/commands/): one page per subcommand.
 
 ## License

package/bin/_cctally_config.py

@@ -309,6 +309,7 @@ ALLOWED_CONFIG_KEYS = (
     "statusline.visual_burn_rate",
     "statusline.cost_source",
     "statusline.cctally_extensions",
+    "statusline.usage_only",
     "budget.weekly_usd",
     "budget.alerts_enabled",
     "budget.alert_thresholds",
@@ -317,6 +318,7 @@ ALLOWED_CONFIG_KEYS = (
     "budget.projects",
     "budget.project_alerts_enabled",
     "budget.codex",
+    "telemetry.enabled",
 )
 
 
@@ -379,6 +381,25 @@ def _validate_statusline_cctally_extensions(value):
     )
 
 
+def _validate_statusline_usage_only(value):
+    """Validate ``statusline.usage_only``.
+
+    Accepts booleans (preferred) or canonical truthy/falsy strings
+    (``true``/``false``/``yes``/``no``/``on``/``off``/``1``/``0``).
+    """
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        lo = value.strip().lower()
+        if lo in ("true", "yes", "on", "1"):
+            return True
+        if lo in ("false", "no", "off", "0"):
+            return False
+    raise ValueError(
+        f"statusline.usage_only must be boolean (got {value!r})"
+    )
+
+
 def cmd_config(args: argparse.Namespace) -> int:
     """Get/set/unset persisted user preferences in config.json.
 
@@ -520,6 +541,25 @@ def _config_known_value(config: dict, key: str) -> "object":
             except ValueError:
                 return True
         return True
+    if key == "telemetry.enabled":
+        # Boolean opt-OUT (anonymous install-count telemetry, spec 2026-07-07).
+        # Default TRUE — absence is ON. A hand-edited junk value surfaces the
+        # True default. Mirrors dashboard.live_tail exactly, under a top-level
+        # `telemetry` block instead of `dashboard`.
+        block = config.get("telemetry") if isinstance(config, dict) else None
+        if not isinstance(block, dict):
+            block = {}
+        stored = block.get("enabled")
+        if stored is None:
+            return True
+        if isinstance(stored, bool):
+            return stored
+        if isinstance(stored, str):
+            try:
+                return c._normalize_alerts_enabled_value(stored)
+            except ValueError:
+                return True
+        return True
     if key in ("update.check.enabled", "update.check.ttl_hours"):
         # Defaults mirror `_is_update_check_due` (True / 24 hours).
         # Hand-edited junk surfaces as the default — matches dashboard.bind.
@@ -544,6 +584,7 @@ def _config_known_value(config: dict, key: str) -> "object":
         "statusline.visual_burn_rate",
         "statusline.cost_source",
         "statusline.cctally_extensions",
+        "statusline.usage_only",
     ):
         sl_block = config.get("statusline") if isinstance(config, dict) else None
         if not isinstance(sl_block, dict):
@@ -554,6 +595,7 @@ def _config_known_value(config: dict, key: str) -> "object":
             "visual_burn_rate": "off",
             "cost_source": "auto",
             "cctally_extensions": True,
+            "usage_only": False,
         }
         if stored is None:
             return defaults[inner]
@@ -561,6 +603,7 @@ def _config_known_value(config: dict, key: str) -> "object":
             "visual_burn_rate": _validate_statusline_visual_burn_rate,
             "cost_source": _validate_statusline_cost_source,
             "cctally_extensions": _validate_statusline_cctally_extensions,
+            "usage_only": _validate_statusline_usage_only,
         }[inner]
         try:
             return validator(stored)
@@ -983,16 +1026,52 @@ def _cmd_config_set(args: argparse.Namespace) -> int:
         else:
             print(f"dashboard.live_tail={'true' if canonical else 'false'}")
         return 0
+    if key == "telemetry.enabled":
+        # Anonymous install-count telemetry opt-out (spec 2026-07-07). Mirror
+        # dashboard.live_tail exactly: validate the bool first, then
+        # read-modify-write under config_writer_lock with _load_config_unlocked
+        # (load_config under the lock self-deadlocks). Preserves any sibling
+        # telemetry.* keys. Re-message the shared normalizer's ValueError with
+        # the actual key name.
+        try:
+            canonical = c._normalize_alerts_enabled_value(raw)
+        except ValueError:
+            print(
+                f"cctally: invalid boolean value for telemetry.enabled: "
+                f"{raw!r} (expected true|false|yes|no|1|0|on|off)",
+                file=sys.stderr,
+            )
+            return 2
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            existing = config.get("telemetry")
+            if existing is not None and not isinstance(existing, dict):
+                print(
+                    "cctally: telemetry config error: telemetry must be an object",
+                    file=sys.stderr,
+                )
+                return 2
+            block = dict(existing or {})
+            block["enabled"] = canonical
+            config["telemetry"] = block
+            save_config(config)
+        if getattr(args, "emit_json", False):
+            print(json.dumps({"telemetry": {"enabled": canonical}}, indent=2))
+        else:
+            print(f"telemetry.enabled={'true' if canonical else 'false'}")
+        return 0
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",
         "statusline.cctally_extensions",
+        "statusline.usage_only",
     ):
         inner_key = key.split(".", 1)[1]
         validator = {
             "visual_burn_rate": _validate_statusline_visual_burn_rate,
             "cost_source": _validate_statusline_cost_source,
             "cctally_extensions": _validate_statusline_cctally_extensions,
+            "usage_only": _validate_statusline_usage_only,
         }[inner_key]
         try:
             normalized = validator(raw)
@@ -1386,10 +1465,25 @@ def _cmd_config_unset(args: argparse.Namespace) -> int:
                 save_config(config)
             # idempotent: silent on missing key
         return 0
+    if key == "telemetry.enabled":
+        # Mirror the dashboard.live_tail unset branch: drop only the enabled
+        # leaf; if the telemetry block ends up empty, drop the parent too.
+        # Unsetting restores the True (opt-out) default at read time.
+        with config_writer_lock():
+            config = _load_config_unlocked()
+            block = config.get("telemetry")
+            if isinstance(block, dict) and "enabled" in block:
+                del block["enabled"]
+                if not block:
+                    config.pop("telemetry", None)
+                save_config(config)
+            # idempotent: silent on missing key
+        return 0
     if key in (
         "statusline.visual_burn_rate",
         "statusline.cost_source",
         "statusline.cctally_extensions",
+        "statusline.usage_only",
     ):
         inner_key = key.split(".", 1)[1]
         with config_writer_lock():

package/bin/_cctally_core.py

@@ -69,6 +69,8 @@ def _init_paths_from_env() -> None:
     global UPDATE_LOCK_PATH, UPDATE_LOG_PATH, UPDATE_LOG_ROTATED_PATH
     global UPDATE_CHECK_LAST_FETCH_PATH, CLAUDE_SETTINGS_PATH
     global CLAUDE_PROJECTS_DIR
+    global TELEMETRY_INSTALL_ID_PATH, TELEMETRY_LAST_BEAT_PATH
+    global TELEMETRY_NOTICE_SHOWN_PATH, TELEMETRY_FIRST_SEEN_PATH
 
     home = pathlib.Path.home()
 
@@ -124,6 +126,14 @@ def _init_paths_from_env() -> None:
     UPDATE_LOG_ROTATED_PATH = APP_DIR / "update.log.1"
     UPDATE_CHECK_LAST_FETCH_PATH = APP_DIR / "update-check.last-fetch"
 
+    # Anonymous install-count telemetry markers (see spec 2026-07-07).
+    # All four derive from APP_DIR and are re-bound here so a redirected
+    # APP_DIR (tests, dev-instance isolation) carries them along.
+    TELEMETRY_INSTALL_ID_PATH = APP_DIR / "install_id"
+    TELEMETRY_LAST_BEAT_PATH = APP_DIR / "telemetry.last-beat"
+    TELEMETRY_NOTICE_SHOWN_PATH = APP_DIR / "telemetry.notice-shown"
+    TELEMETRY_FIRST_SEEN_PATH = APP_DIR / "telemetry.first-seen"
+
     CLAUDE_SETTINGS_PATH = home / ".claude" / "settings.json"
 
     # Claude session JSONL root. Production path is `~/.claude/projects`;
@@ -189,6 +199,25 @@ def _real_prod_data_dir() -> pathlib.Path:
 _init_paths_from_env()
 
 
+# === Telemetry constants (non-path; see spec 2026-07-07) =============
+#
+# These are static (not APP_DIR-derived) so they live outside
+# `_init_paths_from_env()`. The kernel `bin/_cctally_telemetry.py` reads
+# them at call time via its `_core()` accessor.
+#
+# Public, non-secret domain-separation constant folded into the monthly
+# rotating token (SHA-256, truncated to 32 hex). It only namespaces
+# cctally's token from any other consumer of the same install_id — it is
+# NOT a secret and leaking it discloses nothing about the install.
+TELEMETRY_PEPPER = "cctally-install-count-v1"
+# Default beat endpoint; overridable for tests via CCTALLY_TELEMETRY_ENDPOINT.
+TELEMETRY_ENDPOINT_DEFAULT = "https://cctally-telemetry.cctally.workers.dev/beat"
+# Send at most one beat per this many seconds (mtime-gated on the beat marker).
+TELEMETRY_BEAT_THROTTLE_SECONDS = 24 * 3600
+# Wait this long after first eligibility before sending the first beat.
+TELEMETRY_FIRST_BEAT_GRACE_SECONDS = 24 * 3600
+
+
 def _resolve_claude_projects_dirs() -> list[pathlib.Path]:
     """Return Claude Code projects dirs that exist on disk, env-aware.
 

package/bin/_cctally_doctor.py

@@ -416,6 +416,26 @@ def doctor_gather_state(
     except (json.JSONDecodeError, OSError):
         pass
 
+    # ── Telemetry (anonymous install-count, spec 2026-07-07) ─────────
+    # Resolve the opt-out state via the pure kernel predicate — it reads env
+    # + config + the dev-checkout fact and NEVER mints an install_id / touches
+    # any marker (read-only H1 invariant). Uses the same raw config read as the
+    # safety block so doctor never auto-creates config.json; a missing/corrupt
+    # config degrades to `{}` (env/dev precedence still resolves correctly).
+    telemetry_enabled = True
+    telemetry_reason = "enabled"
+    try:
+        raw_tele_cfg: dict = {}
+        if _cctally_core.CONFIG_PATH.exists():
+            loaded = json.loads(_cctally_core.CONFIG_PATH.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                raw_tele_cfg = loaded
+        telemetry_enabled, telemetry_reason = c.resolve_telemetry_state(raw_tele_cfg)
+    except Exception:
+        # Fail-soft: any read/parse/resolution error degrades to the enabled
+        # default (the check renders OK regardless — it never FAILs/WARNs).
+        telemetry_enabled, telemetry_reason = (True, "enabled")
+
     # config.json — RAW READ, never load_config(). load_config()
     # auto-creates on first run AND silently falls back to defaults
     # on corruption — both behaviors would hide diagnostic state
@@ -518,6 +538,10 @@ def doctor_gather_state(
         is_dev_checkout=_cctally_core._is_dev_checkout(),
         # Preview channel (CCTALLY_CHANNEL=preview): surfaced in install.mode.
         channel=("preview" if _cctally_core.is_preview_channel() else "prod"),
+        # Anonymous install-count telemetry (spec 2026-07-07): read-only
+        # opt-out state, resolved above without minting an install_id.
+        telemetry_enabled=telemetry_enabled,
+        telemetry_reason=telemetry_reason,
         # Pricing-freshness check (spec §5.1): trailing-30d coverage gaps.
         pricing_coverage=pricing_coverage,
         # Conversation-sessions rollup consistency (#217 S1 / U9).

package/bin/_cctally_parser.py

@@ -868,6 +868,21 @@ def _build_statusline_parser(subparsers, name, *, help_text, xref):
         action="store_false",
         help="Suppress cctally 5h%%/7d%% segment.",
     )
+    p.add_argument(
+        "--usage-only",
+        dest="usage_only",
+        action="store_true",
+        default=None,
+        help="Render only subscription usage percentages, e.g. "
+             "`5h 36%% · 7d 35%%` (config key statusline.usage_only).",
+    )
+    p.add_argument(
+        "--no-usage-only",
+        dest="usage_only",
+        action="store_false",
+        help="Render the full statusline even when statusline.usage_only "
+             "is enabled in config.",
+    )
     p.add_argument(
         "--config",
         dest="config",
@@ -2210,6 +2225,47 @@ def build_parser() -> argparse.ArgumentParser:
     cfg_unset.add_argument("key", help="Config key")
     cfg_unset.set_defaults(func=c.cmd_config)
 
+    # ---- telemetry (anonymous install-count opt-out, spec 2026-07-07) ----
+    tele_p = sub.add_parser(
+        "telemetry",
+        help="Show or change anonymous install-count telemetry",
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent("""\
+            Anonymous install-count telemetry: what it sends, and how to opt out.
+
+            cctally sends, at most once a day, a minimal beat: a one-way
+            month-rotating token (never your install id), the client version,
+            and a coarse OS family (macos/linux/windows/other). No IP, no
+            username, no paths, no session content ever leaves the machine.
+
+            Actions:
+              (none)   Show the current state, resolved reason, what gets sent,
+                       and the token that would be used this month.
+              on       Enable telemetry (sets telemetry.enabled = true).
+              off      Disable telemetry (sets telemetry.enabled = false).
+              reset    Discard the local install id and mint a fresh one.
+
+            It is also disabled by CCTALLY_DISABLE_TELEMETRY=1, the DO_NOT_TRACK
+            convention, and in dev checkouts.
+
+            Examples:
+              cctally telemetry
+              cctally telemetry --json
+              cctally telemetry off
+              cctally telemetry on
+              cctally telemetry reset
+        """),
+    )
+    tele_p.add_argument(
+        "action", nargs="?", choices=("on", "off", "reset"),
+        help="on|off|reset (omit to show current status).",
+    )
+    tele_p.add_argument(
+        "--json", dest="json", action="store_true",
+        help="Emit the status as JSON (status output only).",
+    )
+    tele_p.set_defaults(func=c.cmd_telemetry)
+
     # ---- alerts (threshold-actions Task 6) ----
     p_alerts = sub.add_parser(
         "alerts",
@@ -2634,6 +2690,26 @@ def build_parser() -> argparse.ArgumentParser:
     )
     uc.set_defaults(func=c.cmd_update_check_internal)
 
+    # ---- _telemetry-beat (internal — hidden, detached anonymous install-count worker) ----
+    tb = sub.add_parser(
+        "_telemetry-beat",
+        help=argparse.SUPPRESS,
+        formatter_class=CLIHelpFormatter,
+        description=textwrap.dedent(
+            """\
+            Internal subcommand: detached anonymous install-count beat
+            worker, spawned broad-but-throttled from
+            `_post_command_update_hooks` (spec 2026-07-07). A dedicated
+            worker, decoupled from `_update-check` — it touches only the
+            telemetry markers, never update-check state. Honours every
+            opt-out (CCTALLY_DISABLE_TELEMETRY / DO_NOT_TRACK / config /
+            dev checkout) via `resolve_telemetry_state`. Always returns 0;
+            failures are swallowed.
+            """
+        ),
+    )
+    tb.set_defaults(func=c.cmd_telemetry_beat_internal)
+
     # ---- repair-symlinks (internal — hidden; npm-postinstall self-heal, issue #114) ----
     rs = sub.add_parser(
         "repair-symlinks",

package/bin/_cctally_setup.py

@@ -2138,7 +2138,25 @@ def _setup_install(args: argparse.Namespace) -> int:
     out.append("    cctally tui                # terminal dashboard")
     out.append("    cctally setup --status     # verify install state")
 
+    # Install-time telemetry disclosure (spec 2026-07-07 §4). Text summary
+    # only — the --json envelope carries a structured `telemetry` field
+    # instead (never prose). Shown unconditionally as a factual disclosure of
+    # the on-by-default, opt-out install-count beat; the opt-out command +
+    # docs link are always surfaced so the fact is discoverable even when the
+    # interactive first-run notice never fires (headless / statusline-only).
+    out.append("")
+    out.append("cctally counts anonymous active installs to gauge real usage.")
+    out.append("What's sent: a rotating, un-linkable token + version + OS family.")
+    out.append("No identity, no paths, no usage data, no IP stored. Auto-expires monthly.")
+    out.append("Opt out anytime:  cctally telemetry off   (or CCTALLY_DISABLE_TELEMETRY=1)")
+    out.append("How it works:     https://github.com/omrikais/cctally/blob/main/docs/telemetry.md")
+
     if getattr(args, "json", False):
+        # JSON-safe telemetry disclosure (spec 2026-07-07 §4): a structured
+        # field, never prose. Resolved READ-ONLY via `resolve_telemetry_state`
+        # (side-effect-free — mints no install_id, writes no config), so the
+        # envelope reports the opt-out state without arming telemetry.
+        tele_enabled, tele_reason = c.resolve_telemetry_state(c.load_config())
         envelope = {
             "schema_version": 1,
             "mode": "install",
@@ -2174,6 +2192,10 @@ def _setup_install(args: argparse.Namespace) -> int:
                 "session_cache_rows": bootstrap_rows,
                 "oauth_status": bootstrap_oauth_status,
             },
+            "telemetry": {
+                "enabled": tele_enabled,
+                "reason": tele_reason,
+            },
             "warnings_count": warnings,
             "exit_code": 0,
         }

package/bin/_cctally_statusline.py

@@ -218,6 +218,14 @@ def cmd_statusline(args: argparse.Namespace) -> int:
         )
         ext_on = True
 
+    usage_only = _resolve(args.usage_only, "usage_only", False)
+    if not isinstance(usage_only, bool):
+        warn_once(
+            f"cctally statusline: invalid statusline.usage_only="
+            f"{usage_only!r}; using False"
+        )
+        usage_only = False
+
     tz_name = _resolve_statusline_tz(getattr(args, "timezone", None), cfg, warn_once)
 
     # Color: explicit CLI > NO_COLOR env > TTY detect.
@@ -232,6 +240,7 @@ def cmd_statusline(args: argparse.Namespace) -> int:
         context_low_threshold=int(args.context_low_threshold),
         context_medium_threshold=int(args.context_medium_threshold),
         cctally_extensions=bool(ext_on),
+        usage_only=bool(usage_only),
         color=bool(color),
         display_tz_name=tz_name,
         debug=bool(args.debug),
@@ -634,4 +643,3 @@ def _build_statusline_injections(warn_once):
         warn_once=warn_once,
     )
 
-

package/bin/_cctally_telemetry.py

@@ -0,0 +1,362 @@
+"""Anonymous install-count telemetry kernel (see spec 2026-07-07).
+
+Pure-ish: state resolution, token derivation, and payload construction are
+side-effect-free; only the beat path mints an ``install_id`` / touches the
+on-disk markers / makes a network call. Stdlib only.
+
+Privacy posture (spec 2026-07-07):
+  - No IP, no username, no path, no session content ever leaves the machine.
+  - The only durable identifier is a random UUID ``install_id`` stored 0600
+    under APP_DIR; it is NEVER transmitted. What we send is a per-month
+    rotating token ``sha256(install_id:YYYY-MM:pepper)[:32]`` — one-way and
+    unlinkable across months, so the server can de-dupe within a month
+    without ever seeing the id.
+  - Fully opt-out: ``CCTALLY_DISABLE_TELEMETRY``, the ``DO_NOT_TRACK``
+    convention, dev checkouts, and a ``telemetry.enabled = false`` config
+    key each disable it (see ``resolve_telemetry_state``).
+  - Network errors are swallowed — telemetry never affects the user's UX.
+
+Cross-module symbols (``_is_dev_checkout``, ``resolve_client_version``,
+``resolve_os_family``, ``_release_read_latest_release_version``) are reached
+through the call-time ``_cctally()`` accessor so tests' ``monkeypatch`` on the
+``cctally`` module namespace propagates into these bodies. Path/constant
+reads go through the ``_core()`` accessor so a redirected APP_DIR (tests,
+dev-instance isolation) is honored.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import hashlib
+import json
+import os
+import platform
+import sys
+import uuid
+import urllib.request
+
+
+def _cctally():
+    """Resolve the current ``cctally`` module at call-time (spec §5.5)."""
+    return sys.modules["cctally"]
+
+
+def _core():
+    import _cctally_core
+    return _cctally_core
+
+
+def _truthy_env(name: str) -> bool:
+    """A ``1``/``true``/``yes``/any-non-empty env value is truthy; unset,
+    empty, ``0``, ``false``, ``no`` are falsey."""
+    v = os.environ.get(name)
+    return v is not None and v.strip().lower() not in ("", "0", "false", "no")
+
+
+def resolve_telemetry_state(config: dict) -> tuple[bool, str]:
+    """Return ``(enabled, reason)`` — side-effect-free.
+
+    Precedence (first match wins): env opt-out, DO_NOT_TRACK, dev checkout,
+    config opt-out, else enabled. Never mints or touches any file.
+    """
+    c = _cctally()
+    if _truthy_env("CCTALLY_DISABLE_TELEMETRY"):
+        return (False, "env-disabled")
+    if _truthy_env("DO_NOT_TRACK"):
+        return (False, "do-not-track")
+    if c._is_dev_checkout():
+        return (False, "dev-checkout")
+    tele = (config or {}).get("telemetry") or {}
+    if tele.get("enabled") is False:
+        return (False, "config-disabled")
+    return (True, "enabled")
+
+
+def current_period(now: _dt.datetime | None = None) -> str:
+    """Current rotation period as ``"YYYY-MM"`` in UTC."""
+    now = now or _dt.datetime.now(_dt.timezone.utc)
+    return now.astimezone(_dt.timezone.utc).strftime("%Y-%m")
+
+
+def telemetry_token(install_id: str, period: str) -> str:
+    """One-way, month-rotating token: ``sha256(id:period:pepper)[:32]``.
+
+    Deterministic within a period, unlinkable across periods, and never
+    reveals ``install_id``."""
+    pepper = _core().TELEMETRY_PEPPER
+    raw = f"{install_id}:{period}:{pepper}".encode("utf-8")
+    return hashlib.sha256(raw).hexdigest()[:32]
+
+
+def read_install_id() -> str | None:
+    """Read the persisted install_id, or ``None`` if absent/empty. Never mints."""
+    p = _core().TELEMETRY_INSTALL_ID_PATH
+    try:
+        return p.read_text(encoding="utf-8").strip() or None
+    except OSError:
+        return None
+
+
+def ensure_install_id() -> str:
+    """Return the install_id, minting a random UUID at 0600 if missing."""
+    p = _core().TELEMETRY_INSTALL_ID_PATH
+    existing = read_install_id()
+    if existing:
+        return existing
+    p.parent.mkdir(parents=True, exist_ok=True)
+    iid = str(uuid.uuid4())
+    # Atomically create at 0600 (O_EXCL) rather than write-then-chmod, so the
+    # id file is never briefly world-readable in the umask window. install_id
+    # is a non-secret, resettable UUID that never leaves the machine, but 0600
+    # matches the cache-db sidecar-hardening posture. On a create race the
+    # loser gets FileExistsError and reads the winner's value.
+    try:
+        fd = os.open(p, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except FileExistsError:
+        return read_install_id() or iid
+    except OSError:
+        # Any other open failure: fall back to a best-effort plain write.
+        p.write_text(iid + "\n", encoding="utf-8")
+        return iid
+    try:
+        os.write(fd, (iid + "\n").encode("utf-8"))
+    finally:
+        os.close(fd)
+    return iid
+
+
+def reset_install_id() -> str:
+    """Discard any existing install_id and mint a fresh one."""
+    p = _core().TELEMETRY_INSTALL_ID_PATH
+    try:
+        p.unlink()
+    except OSError:
+        pass
+    return ensure_install_id()
+
+
+def resolve_client_version() -> str:
+    """The stamped client semver, or ``"unknown"`` when unstamped."""
+    c = _cctally()
+    cur = c._release_read_latest_release_version()
+    return cur[0] if cur else "unknown"
+
+
+def resolve_os_family() -> str:
+    """Coarse OS family: ``macos`` | ``linux`` | ``windows`` | ``other``."""
+    s = platform.system().lower()
+    return {"darwin": "macos", "linux": "linux", "windows": "windows"}.get(s, "other")
+
+
+def build_beat_payload(install_id: str, *, now: _dt.datetime | None = None) -> dict:
+    """The minimal beat body: ``{t, v, os}`` — token, client version, OS family.
+
+    Version/OS are read through the ``cctally`` accessor so a test's
+    ``monkeypatch.setattr(cctally, "resolve_client_version", ...)`` drives the
+    output (the re-export lives on the ``cctally`` module, not this kernel's
+    namespace)."""
+    c = _cctally()
+    return {
+        "t": telemetry_token(install_id, current_period(now)),
+        "v": c.resolve_client_version(),
+        "os": c.resolve_os_family(),
+    }
+
+
+def _marker_age_seconds(path, now: _dt.datetime | None = None) -> float | None:
+    """Seconds since ``path``'s mtime, or ``None`` when the marker is absent."""
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        return None
+    now = now or _dt.datetime.now(_dt.timezone.utc)
+    return now.timestamp() - mtime
+
+
+def telemetry_beat_due(now=None) -> bool:
+    """True when no beat has been *attempted* within the throttle window.
+
+    The last-beat marker records the last beat ATTEMPT (not just the last
+    successful send): ``do_telemetry_beat`` stamps it on every non-disabled
+    run — arm, grace, sent, or failed — so this predicate bounds the parent
+    spawn gate to at most one worker per window regardless of outcome (a
+    network outage / undeployed endpoint can't churn re-spawns)."""
+    age = _marker_age_seconds(_core().TELEMETRY_LAST_BEAT_PATH, now)
+    return age is None or age >= _core().TELEMETRY_BEAT_THROTTLE_SECONDS
+
+
+def first_beat_grace_elapsed(now=None) -> bool:
+    """True once the first-seen marker is at least the grace window old."""
+    age = _marker_age_seconds(_core().TELEMETRY_FIRST_SEEN_PATH, now)
+    return age is not None and age >= _core().TELEMETRY_FIRST_BEAT_GRACE_SECONDS
+
+
+def _touch(path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.touch()
+
+
+def mark_first_seen(now=None) -> None:
+    """Arm the first-seen marker once; subsequent calls are no-ops so the
+    grace window is measured from genuine first eligibility."""
+    p = _core().TELEMETRY_FIRST_SEEN_PATH
+    if _marker_age_seconds(p) is None:
+        _touch(p)
+
+
+def touch_last_beat(now=None) -> None:
+    """Stamp the last-beat-attempt marker to now (resets the throttle window).
+
+    Called at the top of every non-disabled ``do_telemetry_beat`` run so the
+    marker tracks the last ATTEMPT, not just the last successful send."""
+    _touch(_core().TELEMETRY_LAST_BEAT_PATH)
+
+
+def notice_already_shown() -> bool:
+    return _core().TELEMETRY_NOTICE_SHOWN_PATH.exists()
+
+
+def mark_notice_shown() -> None:
+    _touch(_core().TELEMETRY_NOTICE_SHOWN_PATH)
+
+
+def _endpoint() -> str:
+    return os.environ.get("CCTALLY_TELEMETRY_ENDPOINT") or _core().TELEMETRY_ENDPOINT_DEFAULT
+
+
+def do_telemetry_beat(config: dict, *, now=None, endpoint=None) -> str:
+    """Orchestrate arm -> grace -> beat. Returns a status string:
+
+    ``disabled:<reason>`` (opt-out), ``armed`` (first eligibility recorded),
+    ``grace`` (still inside the first-beat grace window), ``sent`` (POST
+    succeeded), or ``failed`` (network error, swallowed).
+
+    Throttling to at most one beat per window is enforced at the PARENT
+    spawn gate (``_post_command_update_hooks``), which only spawns this
+    worker when ``telemetry_beat_due()`` is True. To make that bound hold
+    regardless of outcome, the last-beat-attempt marker is stamped FIRST —
+    immediately after the opt-out check, before the arm/grace/send branches
+    (mirroring ``_do_update_check``'s touch-the-marker-first crash-safety
+    pattern). Without this, the marker was stamped only on a successful
+    send, so the parent gate stayed True through the entire 24h grace
+    window and through any sustained outage (e.g. the endpoint not yet
+    deployed) — re-spawning a fresh detached worker on EVERY command,
+    including hot paths (statusline/record-usage/hook-tick).
+
+    Only the network POST is wrapped, so this swallows connection / DNS /
+    HTTP / timeout errors from the beat send (returning ``failed``); it is
+    not a blanket "never raises" — a defect in the pure marker/id helpers
+    would still surface (and the ``_telemetry-beat`` worker wraps the whole
+    call in its own try/except as belt-and-suspenders)."""
+    enabled, reason = resolve_telemetry_state(config)
+    if not enabled:
+        return f"disabled:{reason}"
+    # Stamp the last-beat-attempt marker FIRST (crash-safe, outcome-
+    # independent) so the parent spawn gate is bounded to <=1 worker per
+    # throttle window whether this run arms, waits out grace, sends, or
+    # fails. The internal ``telemetry_beat_due`` re-check that used to sit
+    # below the grace branch is intentionally gone: the marker was just
+    # touched, so it would always read fresh here.
+    touch_last_beat(now)
+    # Arm on first eligibility; do NOT beat until the grace window elapses.
+    if _marker_age_seconds(_core().TELEMETRY_FIRST_SEEN_PATH) is None:
+        mark_first_seen(now)
+        ensure_install_id()
+        return "armed"
+    if not first_beat_grace_elapsed(now):
+        return "grace"
+    iid = ensure_install_id()
+    payload = build_beat_payload(iid, now=now)
+    try:
+        req = urllib.request.Request(
+            endpoint or _endpoint(),
+            data=json.dumps(payload).encode("utf-8"),
+            headers={
+                "Content-Type": "application/json",
+                "User-Agent": f"cctally-telemetry/{payload['v']}",
+            },
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=3):
+            pass
+        # NOTE: the marker was already stamped at the top of this function
+        # (touch-first), so no second touch is needed on the success path.
+        return "sent"
+    except Exception:
+        return "failed"  # swallow — telemetry never affects UX
+
+
+def _config_set_ns(key: str, value: str) -> argparse.Namespace:
+    """Synthesize the ``argparse.Namespace`` ``cmd_config``'s ``set`` path
+    consumes (``action``/``key``/``value``/``emit_json``). Routing ``on``/``off``
+    through the real config setter keeps a single validation + locking
+    chokepoint rather than re-implementing the read-modify-write here."""
+    return argparse.Namespace(action="set", key=key, value=value, emit_json=False)
+
+
+def cmd_telemetry(args) -> int:
+    """`cctally telemetry [on|off|reset]` + bare status (`--json`).
+
+    ``on``/``off`` flip the ``telemetry.enabled`` config key through the real
+    ``cmd_config`` setter (its bool validation + atomic write). ``reset`` mints
+    a fresh ``install_id``. The bare/status path is strictly READ-ONLY — it
+    resolves the opt-out state from a RAW guarded ``config.json`` read (NOT
+    ``load_config()``, which would auto-create config.json on a fresh install)
+    and previews the month token WITHOUT ever minting an id (it calls
+    ``read_install_id``, never ``ensure_install_id``). It writes nothing.
+    """
+    c = _cctally()
+    action = getattr(args, "action", None)
+    if action == "off":
+        return c.cmd_config(_config_set_ns("telemetry.enabled", "false"))
+    if action == "on":
+        return c.cmd_config(_config_set_ns("telemetry.enabled", "true"))
+    if action == "reset":
+        reset_install_id()
+        print("telemetry: install id reset")
+        return 0
+
+    # bare / status — strictly read-only. Resolve the opt-out state from a
+    # RAW guarded config read (mirroring _cctally_doctor's telemetry gather),
+    # NOT load_config(): load_config() calls ensure_dirs() and auto-creates
+    # config.json on a fresh install, which would contradict the documented
+    # "strictly read-only" / "never mints an install_id, writes config, or
+    # sends a beat" contract (docs/telemetry.md, docs/commands/telemetry.md).
+    # A missing/corrupt config degrades to `{}` (env/dev precedence still
+    # resolves correctly).
+    raw_config: dict = {}
+    try:
+        cfg_path = _core().CONFIG_PATH
+        if cfg_path.exists():
+            loaded = json.loads(cfg_path.read_text(encoding="utf-8"))
+            if isinstance(loaded, dict):
+                raw_config = loaded
+    except Exception:
+        raw_config = {}
+    enabled, reason = resolve_telemetry_state(raw_config)
+    iid = read_install_id()
+    period = current_period()
+    token = telemetry_token(iid, period) if iid else None
+    info = {
+        "enabled": enabled,
+        "reason": reason,
+        "version": c.resolve_client_version(),
+        "os": c.resolve_os_family(),
+        "period": period,
+        "token_preview": token,
+        "fields": ["token", "version", "os"],
+    }
+    if getattr(args, "json", False):
+        print(json.dumps(info))
+        return 0
+    print(f"telemetry: {'enabled' if enabled else 'disabled'} ({reason})")
+    print(
+        f"  sends: rotating monthly token + version ({info['version']}) "
+        f"+ os ({info['os']})"
+    )
+    print(f"  token this month: {token or '(not yet armed)'}")
+    print(
+        "  opt out: cctally telemetry off  |  "
+        "CCTALLY_DISABLE_TELEMETRY=1  |  DO_NOT_TRACK=1"
+    )
+    return 0

package/bin/_cctally_update.py

@@ -1118,18 +1118,21 @@ def _do_update_check() -> None:
         c._save_update_state(state)
 
 
-def _spawn_background_update_check() -> None:
-    """Fire-and-forget the hidden `_update-check` worker.
-
-    Detached `subprocess.Popen` with `start_new_session=True` so a
-    parent exit (the user closes the shell) doesn't propagate SIGHUP
-    to the child. stdin/stdout/stderr are all `/dev/null` so the child
-    can't accidentally pollute the parent's terminal. Exceptions are
-    swallowed: a failed spawn must not break the parent command.
+def _spawn_detached(command: str) -> None:
+    """Fire-and-forget a hidden self-subcommand as a detached worker.
+
+    Detached `subprocess.Popen` with `start_new_session=True` so a parent
+    exit (the user closes the shell) doesn't propagate SIGHUP to the child;
+    stdin/stdout/stderr all `/dev/null` so the child can't pollute the
+    parent's terminal; exceptions swallowed so a failed spawn can't break
+    the parent command. Shared launch boilerplate for both dedicated
+    background workers below — `_update-check` and `_telemetry-beat` stay
+    deliberately separate spawns (spec review finding #1) and share only
+    this Popen shape.
     """
     try:
         subprocess.Popen(
-            [sys.executable, os.path.realpath(sys.argv[0]), "_update-check"],
+            [sys.executable, os.path.realpath(sys.argv[0]), command],
             stdin=subprocess.DEVNULL,
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
@@ -1141,6 +1144,11 @@ def _spawn_background_update_check() -> None:
         pass
 
 
+def _spawn_background_update_check() -> None:
+    """Fire-and-forget the hidden ``_update-check`` worker (spec §3.6)."""
+    _spawn_detached("_update-check")
+
+
 def cmd_update_check_internal(args) -> int:
     """Hidden ``_update-check`` subcommand handler (spec §3.6).
 
@@ -1167,6 +1175,37 @@ def cmd_update_check_internal(args) -> int:
     return 0
 
 
+def _spawn_background_telemetry_beat() -> None:
+    """Fire-and-forget the hidden ``_telemetry-beat`` worker.
+
+    A DEDICATED detached worker, deliberately separate from
+    ``_update-check`` (spec review finding #1): the anonymous install-count
+    beat must never share a process, throttle marker, or failure mode with
+    the update check. Only the launch boilerplate is shared, via
+    ``_spawn_detached``."""
+    _spawn_detached("_telemetry-beat")
+
+
+def cmd_telemetry_beat_internal(args) -> int:
+    """Hidden ``_telemetry-beat`` subcommand handler.
+
+    The detached anonymous-install-count worker. It does the beat and
+    NOTHING else — critically it must NOT read or write any update-check
+    state (spec review finding #1: a dedicated worker fully decoupled
+    from ``_update-check``). Always returns 0 so the parent's
+    spawn-and-forget contract holds. The try/except wraps both the
+    ``load_config`` read and ``do_telemetry_beat`` (which only guarantees
+    the network POST is swallowed, not that pure helper defects can't
+    raise), and its return value is unused."""
+    c = _cctally()
+    try:
+        config = c.load_config()
+        c.do_telemetry_beat(config)
+    except Exception:
+        pass
+    return 0
+
+
 # === User-facing `cctally update` (spec §4) ===
 # `cmd_update` routes by mode flag. Mode flags are mutually exclusive
 # (argparse enforces it; the dispatcher's redundant check is defense in

package/bin/_lib_doctor.py

@@ -169,6 +169,14 @@ class DoctorState:
     # from the env; surfaced in the install.mode check. Defaulted (placed last)
     # so existing constructors stay valid and the prod path is unchanged.
     channel: str = "prod"
+    # Anonymous install-count telemetry (spec 2026-07-07): the resolved opt-out
+    # state + precedence reason from `resolve_telemetry_state`, computed by
+    # `doctor_gather_state` WITHOUT minting an install_id (read-only H1). Drives
+    # the always-OK `telemetry.state` check — a diagnostic surface, never a
+    # health failure. Defaulted (placed last) so existing constructors stay
+    # valid and default to the enabled (opt-out) posture.
+    telemetry_enabled: bool = True
+    telemetry_reason: str = "enabled"
 
 
 @dataclasses.dataclass(frozen=True)
@@ -1178,6 +1186,27 @@ def _check_safety_update_available(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_telemetry(s: DoctorState) -> CheckResult:
+    """Anonymous install-count telemetry opt-out state (spec 2026-07-07).
+
+    A read-only DIAGNOSTIC surface — "is telemetry on, and if off, why" — that
+    is ALWAYS ``ok``, never WARN/FAIL. Being disabled (env kill switch,
+    DO_NOT_TRACK, a dev checkout, or ``telemetry.enabled = false``) is a valid
+    user choice, not a health problem, so this check must never change doctor's
+    severity counts or exit code. The gather layer resolves `enabled`/`reason`
+    via `resolve_telemetry_state` WITHOUT minting an install_id.
+    """
+    enabled = bool(s.telemetry_enabled)
+    reason = s.telemetry_reason
+    return CheckResult(
+        id="telemetry.state", title="State",
+        severity="ok",
+        summary=f"{'enabled' if enabled else 'disabled'} ({reason})",
+        remediation=None,
+        details={"enabled": enabled, "reason": reason},
+    )
+
+
 # Each entry is (category_id, category_title, ((check_id, evaluator_fn_name), ...)).
 # The dotted check_id is the stable JSON-contract ID (spec §5.2) AND the
 # fingerprint identity-slice key (spec §5.5). When an evaluator raises,
@@ -1226,6 +1255,9 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("safety.update_suppress", "_check_safety_update_suppress"),
         ("safety.update_available", "_check_safety_update_available"),
     )),
+    ("telemetry", "Telemetry", (
+        ("telemetry.state", "_check_telemetry"),
+    )),
 )
 
 

package/bin/_lib_statusline.py

@@ -54,6 +54,7 @@ class StatuslineArgs:
     context_low_threshold: int
     context_medium_threshold: int
     cctally_extensions: bool
+    usage_only: bool
     color: bool  # ANSI on/off after auto-detect resolved
     display_tz_name: str  # IANA name; resolved upstream via
                           # get_display_tz_pref(cfg) — defaults to
@@ -372,6 +373,8 @@ def resolve_cctally_extensions(
     inp: StatuslineInput,
     now: datetime,
     inj: StatuslineInjections,
+    *,
+    include_countdowns: bool = True,
 ) -> Optional[str]:
     """Segment 5 — cctally-only `5h X% (...) · 7d Y% (...)`.
 
@@ -411,12 +414,12 @@ def resolve_cctally_extensions(
     parts = []
     if five_pct is not None:
         s = f"5h {int(round(five_pct))}%"
-        if five_resets is not None:
+        if include_countdowns and five_resets is not None:
             s += f" ({_fmt_countdown(five_resets - now_epoch)})"
         parts.append(s)
     if seven_pct is not None:
         s = f"7d {int(round(seven_pct))}%"
-        if seven_resets is not None:
+        if include_countdowns and seven_resets is not None:
             s += f" ({_fmt_countdown(seven_resets - now_epoch)})"
         parts.append(s)
     return " · ".join(parts)
@@ -443,6 +446,19 @@ def _wrap_color(text: str, color: Optional[str], enable: bool) -> str:
 _PERCENT_INT_RE = re.compile(r"(\d+)%")
 
 
+def _colorize_usage_segment(ext: str, args: StatuslineArgs) -> str:
+    """Color a 5h/7d usage segment using the cctally percent bands."""
+    nums = [int(x) for x in _PERCENT_INT_RE.findall(ext)]
+    mx = max(nums) if nums else 0
+    if mx < 60:
+        color = "green"
+    elif mx < 85:
+        color = "yellow"
+    else:
+        color = "red"
+    return _wrap_color(ext, color, args.color)
+
+
 def render_statusline(
     inp: StatuslineInput,
     args: StatuslineArgs,
@@ -453,6 +469,12 @@ def render_statusline(
     None segments (currently only segment 5). See spec §1 for the exact
     layout and §3 for the data flow.
     """
+    if args.usage_only:
+        ext = resolve_cctally_extensions(
+            inp, now, inj, include_countdowns=False
+        )
+        return "" if ext is None else _colorize_usage_segment(ext, args)
+
     seg1 = resolve_model_segment(inp)
 
     # Segment 2: 💰 ... session / ... today / ... block (Xh Ym left)
@@ -486,17 +508,7 @@ def render_statusline(
     if args.cctally_extensions:
         ext = resolve_cctally_extensions(inp, now, inj)
         if ext is not None:
-            # Color by the higher of (5h%, 7d%) using cctally bands:
-            # <60 green, <85 yellow, >=85 red.
-            nums = [int(x) for x in _PERCENT_INT_RE.findall(ext)]
-            mx = max(nums) if nums else 0
-            if mx < 60:
-                color = "green"
-            elif mx < 85:
-                color = "yellow"
-            else:
-                color = "red"
-            seg5 = _wrap_color(ext, color, args.color)
+            seg5 = _colorize_usage_segment(ext, args)
 
     segs = [seg1, seg2, seg3, seg4]
     if seg5 is not None:

package/bin/cctally

@@ -214,6 +214,10 @@ make_week_ref = _cctally_core.make_week_ref
 _get_latest_row_for_week = _cctally_core._get_latest_row_for_week
 _reset_aware_floor = _cctally_core._reset_aware_floor
 get_latest_usage_for_week = _cctally_core.get_latest_usage_for_week
+# Re-exported so the telemetry kernel's ``c._is_dev_checkout()`` accessor
+# call resolves on the ``cctally`` module (and tests can monkeypatch it
+# there). The canonical definition lives in _cctally_core.
+_is_dev_checkout = _cctally_core._is_dev_checkout
 
 # === Path constants — re-exported from _cctally_core ================
 #
@@ -982,6 +986,8 @@ _is_update_check_due = _cctally_update._is_update_check_due
 _do_update_check = _cctally_update._do_update_check
 _spawn_background_update_check = _cctally_update._spawn_background_update_check
 cmd_update_check_internal = _cctally_update.cmd_update_check_internal
+_spawn_background_telemetry_beat = _cctally_update._spawn_background_telemetry_beat
+cmd_telemetry_beat_internal = _cctally_update.cmd_telemetry_beat_internal
 SKIP_USE_STATE_LATEST = _cctally_update.SKIP_USE_STATE_LATEST
 _format_update_command = _cctally_update._format_update_command
 _prerelease_note = _cctally_update._prerelease_note
@@ -1009,6 +1015,36 @@ _should_show_update_banner = _cctally_update._should_show_update_banner
 _format_update_banner = _cctally_update._format_update_banner
 
 
+# Anonymous install-count telemetry kernel (spec 2026-07-07). Eagerly
+# re-exported so tests reach the pure functions via the ``cctally``
+# namespace (mirroring the ``_check_npm_latest_version`` re-export above)
+# and so the kernel's moved bodies that call ``c.resolve_client_version``
+# / ``c.resolve_os_family`` / ``c._release_read_latest_release_version``
+# through the ``_cctally()`` accessor pick up any test monkeypatch on the
+# cctally module. Path constants (TELEMETRY_INSTALL_ID_PATH etc.) live on
+# _cctally_core and are read via ``_core()`` at call time; tests patch
+# them through ``monkeypatch.setattr(_cctally_core, "X", v)`` (conftest's
+# ``redirect_paths()`` covers the set).
+_cctally_telemetry = _load_sibling("_cctally_telemetry")
+resolve_telemetry_state = _cctally_telemetry.resolve_telemetry_state
+telemetry_token = _cctally_telemetry.telemetry_token
+current_period = _cctally_telemetry.current_period
+resolve_client_version = _cctally_telemetry.resolve_client_version
+resolve_os_family = _cctally_telemetry.resolve_os_family
+build_beat_payload = _cctally_telemetry.build_beat_payload
+read_install_id = _cctally_telemetry.read_install_id
+ensure_install_id = _cctally_telemetry.ensure_install_id
+reset_install_id = _cctally_telemetry.reset_install_id
+do_telemetry_beat = _cctally_telemetry.do_telemetry_beat
+telemetry_beat_due = _cctally_telemetry.telemetry_beat_due
+first_beat_grace_elapsed = _cctally_telemetry.first_beat_grace_elapsed
+mark_first_seen = _cctally_telemetry.mark_first_seen
+touch_last_beat = _cctally_telemetry.touch_last_beat
+notice_already_shown = _cctally_telemetry.notice_already_shown
+mark_notice_shown = _cctally_telemetry.mark_notice_shown
+cmd_telemetry = _cctally_telemetry.cmd_telemetry
+
+
 # Phase F #22: ``bin/_cctally_dashboard.py`` is loaded eagerly per spec §4.8
 # carve-out — ``tests/test_dashboard_*.py`` and ``tests/test_share_*.py``
 # reach into ~25 dashboard symbols via ``ns["X"]`` direct-dict reads and
@@ -2853,6 +2889,20 @@ def _post_command_update_hooks(command: str | None, args) -> None:
         # (it runs before the wrapper sets CCTALLY_DATA_DIR, so APP_DIR is
         # still cctally-dev at this point). Same rationale class as doctor.
         return
+    if command in ("_update-check", "_telemetry-beat"):
+        # Both hidden workers are detached and have already done their one job
+        # in their own command handler; neither must re-enter this hook.
+        # Without the guard the ``_update-check`` worker would fall through to
+        # the telemetry gate below and (throttle-bounded) spawn a
+        # ``_telemetry-beat`` — a worker spawning another worker. And
+        # ``do_telemetry_beat`` stamps its throttle marker FIRST on every
+        # non-disabled run (arm/grace/sent/failed), so ``telemetry_beat_due()``
+        # already reads False right after a worker run and the parent gate is
+        # bounded to <=1 spawn/window regardless — this early-return is the
+        # belt-and-suspenders that keeps the two dedicated workers symmetric
+        # and fully hook-free (an internal worker never needs banners or
+        # background spawns anyway).
+        return
     # Self-heal: reconcile current_version with the running binary's
     # CHANGELOG. Cheap (one CHANGELOG read, write only on the first
     # command after a manual upgrade). Runs before load_config so a
@@ -2865,6 +2915,54 @@ def _post_command_update_hooks(command: str | None, args) -> None:
         sys.stderr.write(_format_update_banner(state) + "\n")
     if _is_update_check_due(config):
         _spawn_background_update_check()
+    # Anonymous install-count telemetry (spec 2026-07-07). Broad-but-
+    # throttled, placed after the same early-returns that guard the update
+    # check so it inherits every side-effect skip (read-only/no-mutation
+    # commands, the CCTALLY_DISABLE_UPDATE_CHECK test seam, and the
+    # ``_telemetry-beat`` self-re-entry guard above). The env kill switches
+    # (CCTALLY_DISABLE_TELEMETRY / DO_NOT_TRACK), the config opt-out, and
+    # the dev-checkout guard all live inside ``resolve_telemetry_state`` —
+    # do not re-check them here.
+    enabled, _reason = resolve_telemetry_state(config)
+    if enabled and telemetry_beat_due():
+        _spawn_background_telemetry_beat()
+    _maybe_print_telemetry_notice(command, config)
+
+
+def _maybe_print_telemetry_notice(command: str | None, config) -> None:
+    """One-time interactive notice that anonymous install-count telemetry
+    is active (spec review finding #2). Banner-gated (NOT beat-gated): it
+    prints once to an interactive stderr and, once marked, never again.
+    Fully best-effort — the whole body is wrapped so any failure is
+    swallowed and can't perturb the parent command.
+
+    Gates (all must hold to print):
+      - telemetry enabled (opt-outs / config / dev-checkout suppress it);
+      - not already shown (the ``TELEMETRY_NOTICE_SHOWN`` marker);
+      - command not in ``_BANNER_SUPPRESSED_COMMANDS`` — the same quiet
+        set the update banner honours (record-usage / hook-tick / blocks /
+        etc.), so machine-consumed one-liners stay clean;
+      - stderr is a real TTY — never pollute piped or redirected output.
+    """
+    try:
+        enabled, _reason = resolve_telemetry_state(config)
+        if not enabled or notice_already_shown():
+            return
+        if command in _BANNER_SUPPRESSED_COMMANDS:
+            return
+        if not (sys.stderr and sys.stderr.isatty()):
+            return
+        docs = "https://github.com/omrikais/cctally/blob/main/docs/telemetry.md"
+        sys.stderr.write(
+            "cctally counts anonymous active installs to gauge real usage.\n"
+            "What's sent: a rotating, un-linkable token + version + OS family.\n"
+            "No identity, no paths, no usage data, no IP stored. Auto-expires monthly.\n"
+            "Opt out anytime:  cctally telemetry off   (or CCTALLY_DISABLE_TELEMETRY=1)\n"
+            f"How it works:     {docs}\n"
+        )
+        mark_notice_shown()
+    except Exception:
+        pass
 
 
 if __name__ == "__main__":

package/bin/cctally-npm-postinstall.js

@@ -36,5 +36,9 @@ process.stdout.write(
   '  cctally setup\n' +
   '\nThis installs additive Claude Code hooks (~/.claude/settings.json)\n' +
   'and bootstraps the local SQLite cache (~/.local/share/cctally/).\n' +
+  '\ncctally counts anonymous active installs (a rotating monthly token +\n' +
+  'version + OS family; no identity, paths, or usage data). Opt out with\n' +
+  '`cctally telemetry off`, CCTALLY_DISABLE_TELEMETRY=1, or DO_NOT_TRACK=1.\n' +
+  'How it works: https://github.com/omrikais/cctally/blob/main/docs/telemetry.md\n' +
   '\nDetails: https://github.com/omrikais/cctally#installation\n\n'
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cctally",
-  "version": "1.62.0",
+  "version": "1.64.0",
   "description": "Claude Code usage tracker and local dashboard for Pro/Max subscription limits - weekly cost-per-percent trend, quota forecasts, threshold alerts. ccusage-compatible.",
   "homepage": "https://github.com/omrikais/cctally",
   "repository": {
@@ -41,6 +41,7 @@
     "bin/_cctally_share.py",
     "bin/_cctally_statusline.py",
     "bin/_cctally_sync_week.py",
+    "bin/_cctally_telemetry.py",
     "bin/_cctally_tui.py",
     "bin/_cctally_update.py",
     "bin/_cctally_weekrefs.py",