RTK was documented as delivering "60-90% token savings", which reads as a
cost reduction. What RTK actually reduces is bash output bytes. Those are
one contributor to input tokens, which are themselves only part of a bill
that also counts output tokens, so the reduction dilutes at every step.
- add docs/guide/resources/savings-explained.md as the canonical explainer:
the savings chain, both estimators, and what RTK does not reduce
- rescope the headline claim across README (7 languages), the guide, hook
rules, agent definitions and module READMEs
- relabel per-command tables as bash output reduction, keeping every figure
- document that reported tokens are estimates: rtk gain uses bytes/4
(src/core/tracking.rs), filter tests use split_whitespace().count().
Neither is a real tokenizer, so ratios hold but absolute counts do not
Remove figures that had no source: the $3/Mtok constant and its $36
example, the +/-10% tokenization accuracy claim, the 99.5% hook-install
figure, the invented session tables in README and INSTALL, and the 30-50%
parser range.
CHANGELOG is untouched. Shipped release notes stay as a historical record.
What RTK collects, how to opt out, and your GDPR rights
order
4
Telemetry & Privacy
RTK collects anonymous, aggregate usage metrics once per day to help improve the product. Telemetry is disabled by default and requires explicit consent during rtk init or rtk telemetry enable.
Which commands are used most and need the best filters
Which filters are underperforming and need improvement
Which ecosystems to prioritize for new filter development
How much bash output RTK removes before it reaches the model
Whether users stay engaged over time or churn after trying RTK
This data directly drives our roadmap. For example, if telemetry shows that 40% of users run Python commands but only 10% of our filters cover Python, we know where to invest next.
How it works
Once per day (23-hour interval), RTK sends a single HTTPS POST to our telemetry endpoint
The ping runs in a background thread and never blocks the CLI (2-second timeout)
A marker file prevents duplicate pings within the interval
If the server is unreachable, the ping is silently dropped — no retries, no queue
What is collected
Identity (anonymous)
Field
Example
Purpose
device_hash
a3f8c9... (64 hex chars)
Count unique installations. SHA-256 of a per-device random salt stored locally (~/.local/share/rtk/.device_salt). Not reversible. No hostname or username included.
Environment
Field
Example
Purpose
version
0.34.1
Track adoption of new versions
os
macos
Know which platforms to support and test
arch
aarch64
Prioritize ARM vs x86 builds
install_method
homebrew
Understand distribution channels (homebrew/cargo/script/nix)
Usage volume
Field
Example
Purpose
commands_24h
142
Daily activity level
commands_total
32888
Lifetime usage — segment light vs heavy users
top_commands
["git", "cargo", "ls"]
Most popular tools (names only, max 5)
tokens_saved_24h
450000
Daily value delivered
tokens_saved_total
96500000
Lifetime value delivered
savings_pct
72.5
Overall effectiveness
Quality (filter improvement)
Field
Example
Purpose
passthrough_top
["git:15", "npm:8"]
Top 5 commands with 0% bash output reduction — these need filters
parse_failures_24h
3
Filter fragility — high count means filters are breaking
low_savings_commands
["rtk <cmd>:25%"]
Commands averaging <30% bash output reduction — filters to improve. The example is a placeholder, not a measured value
avg_savings_per_command
68.5
Unweighted average (vs global which is volume-biased)
Ecosystem distribution
Field
Example
Purpose
ecosystem_mix
{"git": 45, "cargo": 20, "js": 15}
Category percentages — where to invest filter development
Retention (engagement)
Field
Example
Purpose
first_seen_days
45
Installation age in days
active_days_30d
22
Days with at least 1 command in last 30 days — measures stickiness
Economics
Field
Example
Purpose
tokens_saved_30d
12000000
30-day token savings for trend analysis
estimated_savings_usd_30d
—
A USD value derived from the estimated tokens saved and a fixed internal constant. It is not a measured cost and does not reflect any provider's pricing
Adoption
Field
Example
Purpose
hook_type
claude
Which AI agent hook is installed (claude/gemini/codex/cursor/none)
custom_toml_filters
3
Number of user-created TOML filter files — DSL adoption
Configuration (user maturity)
Field
Example
Purpose
has_config_toml
true
Whether user has customized RTK config
exclude_commands_count
2
Commands excluded from rewriting — high count may indicate frustration
projects_count
5
Distinct project paths — multi-project = power user
Feature adoption
Field
Example
Purpose
meta_usage
{"gain": 5, "discover": 2}
Which RTK features are actually used
What is NOT collected
Source code or file contents
Full command lines or arguments (only tool names like "git", "cargo")
File paths or directory structures
Secrets, API keys, or environment variable values
Repository names or URLs
Personally identifiable information
IP addresses (not stored in telemetry pings; stored temporarily in erasure audit log for accountability, anonymized after 6 months)
Consent
Telemetry requires explicit opt-in consent (GDPR Art. 6, 7). Consent is requested during rtk init or via rtk telemetry enable. Without consent, no data is sent.
rtk telemetry status # Check current consent state
rtk telemetry enable# Give consent (interactive prompt)
rtk telemetry disable # Withdraw consent
rtk telemetry forget # Withdraw consent + delete local data + request server erasure
Environment variable override (blocks telemetry regardless of consent):
exportRTK_TELEMETRY_DISABLED=1
Retention Policy
Server-side: telemetry records are retained for a maximum of 12 months, then automatically purged.
Server-side (erasure log): IP addresses in the erasure audit log are anonymized after 6 months (GDPR — IP is personal data).
Client-side: the local SQLite database (~/.local/share/rtk/history.db) retains data for 90 days by default (configurable via tracking.history_days in config.toml). Deleted entirely by rtk telemetry forget.
Your Rights (GDPR)
Under the EU General Data Protection Regulation, you have the right to:
Access your data: rtk telemetry status shows your device hash; the telemetry payload is fully documented above.
Rectification: since data is anonymous and aggregate, rectification is not applicable.
Erasure (Art. 17): run rtk telemetry forget to delete local data and send an erasure request to the server. Alternatively, email contact@rtk-ai.app with your device hash.
Restriction of processing: rtk telemetry disable stops all data collection immediately.
Portability: the local SQLite database at ~/.local/share/rtk/history.db contains all locally stored data.
Objection: rtk telemetry disable or export RTK_TELEMETRY_DISABLED=1.
Erasure Procedure
Run rtk telemetry forget — this disables telemetry, deletes your device salt, ping marker, and local tracking database (history.db), then sends an erasure request to the server.
If the server is unreachable, the CLI prints your full device hash and fallback instructions to email contact@rtk-ai.app for manual erasure.
You can also email contact@rtk-ai.app directly to request manual erasure.
Data Handling
All communications use HTTPS (TLS)
Data is used exclusively for RTK product improvement
No data is sold or shared with third parties
Aggregate statistics may be published (e.g. "70% of RTK users are on macOS")
Adrien Eppling
a1673f7428