@tokelang-lite/claude-code-skill 1.0.0

package/skills/tokelang-stats/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: tokelang-stats
+description: >
+  Show savings for the current session — tokens compressed, % reduction, and an approximate
+  dollar figure at Anthropic's published input rate. Reads this session's local sidecar via
+  the bundled CLI; no network call. Counts only what the skill compresses (Task subagent
+  prompts + /tokelang-compress file runs).
+  Trigger: /tokelang-stats
+---
+
+# Session savings stats
+
+Reports what Tokelang has saved you in the current Claude Code session.
+
+## Trigger
+
+- `/tokelang-stats` — explicit
+- "show tokelang savings" — natural language
+
+## Process
+
+1. Resolve the current session id (Claude Code supplies it to the hooks; the sidecar is named for it).
+
+2. Run the bundled CLI over this session's sidecar — the file the hooks append a
+   `surface,orig_tokens,comp_tokens,unix_ts` line to on every compression event:
+   ```bash
+   "${CLAUDE_PLUGIN_ROOT}/bin/tokelang-cli" stats --transcript ~/.claude/.tokelang-session-<session_id>
+   ```
+   It emits JSON: `{events, original_tokens, compressed_tokens, tokens_saved, pct_saved}`. All token
+   counts are real cl100k (computed in-process; no network).
+
+3. Convert `tokens_saved` to an approximate dollar figure at the model's published input rate
+   (e.g. Sonnet 4.6 input $3/MTok) for display.
+
+4. Print summary:
+   ```
+   Tokelang — this session
+   Compression events:    14   (subagent prompts + any /tokelang-compress file runs)
+   Input tokens saved:    4,287 (32% reduction)
+   Estimated $ saved:     ~$0.013 (input $3/MTok)
+   ```
+
+> **Not counted** (be honest about scope): per-turn user input — the plugin can't rewrite it, so use
+> `tokelang-cli wrap` for that; **tool results** — Claude Code's PostToolUse hook is additive-only, so
+> the in-loop tool-result gap is a known v1.0.0 limitation; and model output — never post-processed.
+> Stats reflect only what the skill actually compresses.
+
+## Lifetime stats (statusline)
+
+The statusline shows **lifetime** cumulative savings across all your Claude Code sessions — different from this command which shows current-session only. Lifetime stats live in `~/.claude/.tokelang-lifetime.json` and update on every `Stop` hook.
+
+## Why both per-session AND lifetime?
+
+- Per-session — useful when debugging "did Tokelang actually compress my last turn?"
+- Lifetime — useful when justifying ROI ("$X.XX saved last month")
+
+## What this command does NOT do
+
+- Phone home (everything is computed locally from `$CLAUDE_TRANSCRIPT_PATH`)
+- Include the hosted API's compression stats (separate product)
+- Predict future savings (no forecasting)
+
+## Example
+
+```
+> /tokelang-stats
+
+Tokelang — this session
+Compression events:    9   (subagent prompts)
+Input tokens saved:    1,840 / 5,210 (35%)
+Estimated $ saved:     ~$0.006 (input $3/MTok)
+Lifetime savings:      tracked in ~/.claude/.tokelang-lifetime.json (shown in the statusline)
+```

package/skills/tokelang-telemetry/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: tokelang-telemetry
+description: >
+  Turn Tokelang's opt-in usage metrics on or off. OFF by default. When ON, only AGGREGATE
+  token-savings counts are sent (per session) — never prompt content, file paths, or session
+  ids. Toggling writes ~/.claude/.tokelang-telemetry.json. Trigger: /tokelang-telemetry [on|off]
+---
+
+# Telemetry (opt-in, off by default)
+
+Tokelang sends **nothing** unless you explicitly turn this on. When on, the Stop hook sends one
+small aggregate ping per session so the project can see real-world savings in the aggregate.
+
+## What is / isn't sent
+
+**Sent (aggregate only):** schema version, CLI version, level, coarse OS/arch, this session's
+`tokens_saved` + event count, and lifetime `tokens_saved` + session count, plus a random
+`anon_id` (generated locally at opt-in, for de-duplicating installs).
+
+**Never sent:** prompt text, responses, file paths, file names, session ids, repo info, or
+anything derived from your content. The session sidecar the ping is built from only ever stores
+`surface,orig_tokens,comp_tokens,timestamp` per event — there is no content in it to leak.
+
+Endpoint: `https://tokelang.com/v1/telemetry` (override with `TOKELANG_TELEMETRY_ENDPOINT`).
+The ping is best-effort: it needs `curl`, is capped at 3s, and is fired detached so it can
+never block or fail your session.
+
+## Trigger
+
+- `/tokelang-telemetry on` — opt in
+- `/tokelang-telemetry off` — opt out (the default state)
+- `/tokelang-telemetry` (no arg) — show current status and exactly what would be sent
+
+## Process
+
+Parse the argument (case-insensitive). The state lives in `~/.claude/.tokelang-telemetry.json`.
+
+### on
+Run this (preserves an existing `anon_id`, otherwise generates a fresh random one):
+
+```bash
+F="${HOME}/.claude/.tokelang-telemetry.json"
+AID="$(jq -r '.anon_id // empty' "$F" 2>/dev/null)"
+[ -z "$AID" ] && AID="$(cat /proc/sys/kernel/random/uuid 2>/dev/null || uuidgen 2>/dev/null || python3 -c 'import uuid;print(uuid.uuid4())' 2>/dev/null || echo "anon-$(date +%s)-$RANDOM")"
+mkdir -p "${HOME}/.claude"
+jq -n --arg aid "$AID" '{enabled:true, anon_id:$aid}' > "$F"
+echo "Telemetry ON. Aggregate token-savings metrics only — never prompt content. anon_id=$AID"
+```
+
+### off
+Run this (keeps the file but disables it, so the same `anon_id` is reused if you later re-enable):
+
+```bash
+F="${HOME}/.claude/.tokelang-telemetry.json"
+AID="$(jq -r '.anon_id // empty' "$F" 2>/dev/null)"
+mkdir -p "${HOME}/.claude"
+jq -n --arg aid "$AID" '{enabled:false} + (if $aid=="" then {} else {anon_id:$aid} end)' > "$F"
+echo "Telemetry OFF. Nothing will be sent."
+```
+
+(Equivalent: just delete `~/.claude/.tokelang-telemetry.json`.)
+
+### status (no arg)
+Read the file and report:
+
+```bash
+F="${HOME}/.claude/.tokelang-telemetry.json"
+if [ -f "$F" ] && [ "$(jq -r '.enabled // false' "$F" 2>/dev/null)" = "true" ]; then
+  echo "Telemetry: ON  (anon_id=$(jq -r '.anon_id // "?"' "$F"))"
+else
+  echo "Telemetry: OFF (default)"
+fi
+```
+
+Then summarize the "What is / isn't sent" section above so the user can decide.
+
+## Notes
+
+- This is independent of `tokelang.level`. Turning the skill off (`/tokelang-level off`) does not
+  change telemetry; telemetry is governed solely by this file.
+- No metrics are sent for sessions with zero compression events (the Stop hook exits early when
+  there is no sidecar).

package/statusline/savings.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Tokelang statusline reader
+# Invoked by Claude Code statusline.command setting.
+# Reads the suffix file written by stop.sh and prints to stdout.
+
+set -euo pipefail
+
+STATUSLINE_SUFFIX="${HOME}/.claude/.tokelang-statusline-suffix"
+
+if [[ -f "${STATUSLINE_SUFFIX}" ]]; then
+  cat "${STATUSLINE_SUFFIX}"
+else
+  # First-run: no data yet
+  echo "tokelang: tracking"
+fi