telemetrydeck-analytics
A Claude Code plugin (and skill) that lets agents work with TelemetryDeck product analytics. Ask in plain English, get a real query, a real table, and an honest caveat.
How it works
Once the plugin is installed, Claude knows there's an analytics skill sitting behind the /telemetrydeck-analytics:* slash commands and a CLI called tdq on PATH.
When you ask something ambient — "is the Pro share growing?", "why aren't signals arriving?", "how did last week compare to the week before?" — the analytics skill auto-invokes. Claude picks the right entry point (tdq dau, tdq groupby license, tdq query - with hand-written TQL, …), runs it, and hands you back a markdown table with the opt-in-cohort caveat attached.
When you want a specific one-shot, the namespaced slash commands do the right thing directly: /telemetrydeck-analytics:doctor for a health check, /telemetrydeck-analytics:dau --last 30d, /telemetrydeck-analytics:report "how is retention trending?", and so on.
Under the hood it's a stdlib-only Python CLI that talks to TelemetryDeck's v3 API. Secrets live in your OS-native secret store (macOS Keychain, Linux libsecret, Windows/file fallback with a loud warning) — never in a .env. A progressive-disclosure TQL reference tree means Claude reads the exact sub-page it needs instead of pasting a full spec into context.
Installation
Claude Code
The repo doubles as its own single-plugin marketplace. Register it, then install:
/plugin marketplace add agenkin/telemetrydeck-analytics
/plugin install telemetrydeck-analytics@telemetrydeck-analytics
Or non-interactively:
claude plugin marketplace add agenkin/telemetrydeck-analytics
claude plugin install telemetrydeck-analytics@telemetrydeck-analytics
skills.sh
Pulls the skill files including the bundled tdq.py — Claude uses it automatically via the $SKILL_DIR fallback. No slash commands and no tdq on PATH, but all queries work:
npx skills add agenkin/telemetrydeck-analytics
Local checkout (for development)
git clone https://github.com/agenkin/telemetrydeck-analytics
claude plugin marketplace add ./telemetrydeck-analytics
claude plugin install telemetrydeck-analytics@telemetrydeck-analytics
First-run setup
Inside a Claude Code session, run:
/telemetrydeck-analytics:setup
Claude walks you through email + password, mints a bearer, then shows a numbered picker of every app visible on your account. Pick one and you're done. Secrets land in your OS-native secret store (macOS Keychain / Linux libsecret / file fallback); nothing touches your repo.
Prefer to do it from your shell? The tdq CLI exposes the same flow — it's on PATH once the plugin is enabled:
tdq login # same interactive flow
tdq apps add <uuid> # register another app later
tdq apps use <name|uuid|index> # switch current app
The Basic Workflow
-
setup — First run. Login, discover apps, pick the current one. Or run /telemetrydeck-analytics:setup.
-
doctor — Before asking real questions, verify the round-trip. Asserts non-empty rows and points at TDQ_RAW=1 on failure.
-
ask — Ask Claude a product-analytics question in plain English. The analytics skill auto-invokes.
-
narrow — When the answer needs something specific, reach for a focused command: :dau, :mau, :groupby <dim>, :events, :signals, :query.
-
report — For a compact markdown writeup (top-line, method, result, interpretation, caveats), use /telemetrydeck-analytics:report <question>.
-
iterate — If a query comes back empty or suspicious, re-run with TDQ_RAW=1 to see the raw HTTP response, or run tdq test to verify the API shape hasn't drifted.
What's Inside
Slash commands
Setup + ops
- setup — Interactive first-run login and app picker.
- doctor — End-to-end health check. Asserts non-empty rows, surfaces a clear remediation path on failure.
- apps — List, switch, add, or remove registered apps (supports UUID / name / 1-based index).
Metrics
- dau — Daily active users. Uses
userCount on a day granularity, not the deprecated cardinality.
- mau — Monthly active users over the last N calendar months.
- groupby — Break down count or users by any dimension (license, version,
isAppStore, platform, custom payload keys).
Schema + raw
- events — Schema discovery: merged 7-day and 30-day event counts so you can see what's firing.
- signals — Top-N events, raw pipeline triage.
- query — Run arbitrary TQL from a file or stdin. Claude consults
skills/analytics/tql/index.md first.
Narrative
- report — Turn a question into a compact markdown report: top-line, method, result, interpretation, caveats.
The tdq CLI
