wehub/rtk-ai--rtk
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 12:01:57 +08:00
commit 9dda3e2451
399 changed files with 118131 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide/resources/telemetry.md
+168
View File
@@ -0,0 +1,168 @@
---
title: Telemetry & Privacy
description: What RTK collects, how to opt out, and your GDPR rights
sidebar:
order: 3
---
# 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`.
## Data Collector
**Entity**: `RTK AI Labs`
**Contact**: contact@rtk-ai.app
## Why we collect telemetry
Without telemetry, we have no visibility into:
- 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 value RTK delivers to users (token savings in $ terms)
- 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
1. **Once per day** (23-hour interval), RTK sends a single HTTPS POST to our telemetry endpoint
2. The ping runs in a **background thread** and never blocks the CLI (2-second timeout)
3. A marker file prevents duplicate pings within the interval
4. 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% savings — these need filters |
| `parse_failures_24h` | `3` | Filter fragility — high count means filters are breaking |
| `low_savings_commands` | `["rtk docker ps:25%"]` | Commands averaging <30% savings — filters to improve |
| `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` | `36.0` | Estimated dollar value saved (at ~$3/Mtok input pricing, Claude Sonnet) |
### 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.
```bash
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):
```bash
export RTK_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
1. 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.
2. If the server is unreachable, the CLI prints your full device hash and fallback instructions to email contact@rtk-ai.app for manual erasure.
3. 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")
docs/guide/resources/troubleshooting.md
+184
View File
@@ -0,0 +1,184 @@
---
title: Troubleshooting
description: Common RTK issues and how to fix them
sidebar:
order: 2
---
# Troubleshooting
## `rtk gain` says "not a rtk command"
**Symptom:**
```bash
$ rtk gain
rtk: 'gain' is not a rtk command. See 'rtk --help'.
```
**Cause:** You installed **Rust Type Kit** (`reachingforthejack/rtk`) instead of **Rust Token Killer** (`rtk-ai/rtk`). They share the same binary name.
**Fix:**
```bash
cargo uninstall rtk
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
rtk gain # should now show token savings stats
```
## How to tell which rtk you have
| If `rtk gain`... | You have |
|------------------|----------|
| Shows token savings dashboard | Rust Token Killer ✅ |
| Returns "not a rtk command" | Rust Type Kit ❌ |
## AI assistant not using RTK
**Symptom:** Claude Code (or another agent) runs `cargo test` instead of `rtk cargo test`.
**Checklist:**
1. Verify RTK is installed:
```bash
rtk --version
rtk gain
```
2. Initialize the hook:
```bash
rtk init --global # Claude Code
rtk init --global --cursor # Cursor
rtk init --global --opencode # OpenCode
```
3. Restart your AI assistant.
4. Verify hook status:
```bash
rtk init --show
```
5. Check `settings.json` has the hook registered (Claude Code):
```bash
cat ~/.claude/settings.json | grep rtk
```
## RTK not found after `cargo install`
**Symptom:**
```bash
$ rtk --version
zsh: command not found: rtk
```
**Cause:** `~/.cargo/bin` is not in your PATH.
**Fix:**
For bash (`~/.bashrc`) or zsh (`~/.zshrc`):
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
For fish (`~/.config/fish/config.fish`):
```fish
set -gx PATH $HOME/.cargo/bin $PATH
```
Then reload:
```bash
source ~/.zshrc # or ~/.bashrc
rtk --version
```
## RTK on Windows
### Double-clicking rtk.exe does nothing
**Symptom:** You double-click `rtk.exe`, a terminal flashes and closes instantly.
**Cause:** RTK is a command-line tool. With no arguments, it prints usage and exits. The console window opens and closes before you can read anything.
**Fix:** Open a terminal first, then run RTK from there:
- Press `Win+R`, type `cmd`, press Enter
- Or open PowerShell or Windows Terminal
- Then run: `rtk --version`
### Hook not working (no auto-rewrite)
**Symptom:** `rtk init -g` shows "Falling back to --claude-md mode" on Windows.
**Cause:** The auto-rewrite hook (`rtk-rewrite.sh`) requires a Unix shell. Native Windows doesn't have one.
**Fix:** Use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) for full hook support:
```bash
# Inside WSL
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
rtk init -g # full hook mode works in WSL
```
On native Windows, RTK falls back to CLAUDE.md injection. Your AI assistant gets RTK instructions but won't auto-rewrite commands. It can still use RTK manually: `rtk cargo test`, `rtk git status`, etc.
### Node.js tools not found
**Symptom:**
```
rtk vitest --run
Error: program not found
```
**Cause:** On Windows, Node.js tools are installed as `.CMD`/`.BAT` wrappers. Older RTK versions couldn't find them.
**Fix:** Update to RTK v0.23.1+:
```bash
cargo install --git https://github.com/rtk-ai/rtk
rtk --version # should be 0.23.1+
```
## Compilation error during installation
```bash
rustup update stable
rustup default stable
cargo clean
cargo build --release
cargo install --path . --force
```
Minimum required Rust version: 1.70+.
## OpenCode not using RTK
```bash
rtk init --global --opencode
# restart OpenCode
rtk init --show # should show "OpenCode: plugin installed"
```
## `cargo install rtk` installs the wrong package
If Rust Type Kit is published to crates.io under the name `rtk`, `cargo install rtk` may install the wrong one.
Always use the explicit URL:
```bash
cargo install --git https://github.com/rtk-ai/rtk
```
## Run the diagnostic script
From the RTK repository root:
```bash
bash scripts/check-installation.sh
```
Checks:
- RTK installed and in PATH
- Correct version (Token Killer, not Type Kit)
- Available features
- Claude Code integration
- Hook status
## Still stuck?
Open an issue: https://github.com/rtk-ai/rtk/issues
docs/guide/resources/what-rtk-covers.md
+157
View File
@@ -0,0 +1,157 @@
---
title: What RTK Optimizes
description: Commands and ecosystems automatically optimized by RTK with typical token savings
sidebar:
order: 1
---
# What RTK Optimizes
Once RTK is installed with a hook, these commands are automatically intercepted and filtered. You run them normally — the hook rewrites them transparently before execution.
Typical savings: 60-99%.
## Git
| Command | Savings | What changes |
|---------|---------|--------------|
| `git status` | 75-93% | Compact stat format, grouped by state |
| `git log` | 80-92% | Hash + author + subject only |
| `git diff` | 70% | Context reduced, headers stripped |
| `git show` | 70% | Same as diff |
| `git stash list` | 75% | Compact one-line per entry |
## GitHub CLI
| Command | Savings | What changes |
|---------|---------|--------------|
| `gh pr view` | 87% | Removes ASCII art and verbose metadata |
| `gh pr checks` | 79% | Status + name only, failures highlighted |
| `gh run list` | 82% | Compact workflow run summary |
| `gh issue view` | 80% | Body only, no decoration |
## Graphite (Stacked PRs)
| Command | Savings | What changes |
|---------|---------|--------------|
| `gt log` | 75% | Stack summary only |
| `gt status` | 70% | Current branch context |
## Cargo / Rust
| Command | Savings | What changes |
|---------|---------|--------------|
| `cargo test` | 90% | Failures only, passed tests suppressed |
| `cargo nextest` | 90% | Same as test |
| `cargo build` | 80% | Errors and warnings only |
| `cargo check` | 80% | Errors and warnings only |
| `cargo clippy` | 80% | Lint warnings grouped by file |
## JavaScript / TypeScript
| Command | Savings | What changes |
|---------|---------|--------------|
| `jest` | 94-99% | Failures only |
| `vitest` | 94-99% | Failures only |
| `tsc` | 75% | Type errors grouped by file |
| `eslint` | 84% | Violations grouped by rule |
| `pnpm list` | 70-90% | Compact dependency tree |
| `pnpm outdated` | 70% | Package + current + latest only |
| `next build` | 80% | Route summary + errors only |
| `prisma migrate` | 75% | Migration status only |
| `playwright test` | 90% | Failures + trace links only |
## Python
| Command | Savings | What changes |
|---------|---------|--------------|
| `pytest` | 80-90% | Failures only |
| `ruff check` | 75% | Violations grouped by file |
| `mypy` | 75% | Type errors grouped by file |
| `pip install` | 70% | Installed packages only, progress stripped |
## Go
| Command | Savings | What changes |
|---------|---------|--------------|
| `go test` | 80-90% | Failures only |
| `golangci-lint run` | 75% | Violations grouped by file |
| `go build` | 75% | Errors only |
## Ruby
| Command | Savings | What changes |
|---------|---------|--------------|
| `rspec` | 80-90% | Failures only |
| `rubocop` | 75% | Offenses grouped by file |
| `rake` | 70% | Task output, build errors highlighted |
## .NET
| Command | Savings | What changes |
|---------|---------|--------------|
| `dotnet build` | 80% | Errors and warnings only |
| `dotnet test` | 85-90% | Failures only |
| `dotnet format` | 75% | Changed files only |
## Docker / Kubernetes
| Command | Savings | What changes |
|---------|---------|--------------|
| `docker ps` | 65% | Essential columns (name, image, status, port) |
| `docker images` | 60% | Name + tag + size only |
| `docker logs` | 70% | Deduplicated, last N lines |
| `docker compose up` | 75% | Service status, errors highlighted |
| `kubectl get pods` | 65% | Name + status + restarts only |
| `kubectl logs` | 70% | Deduplicated entries |
## Files and Search
| Command | Savings | What changes |
|---------|---------|--------------|
| `ls` | 80% | Tree format with file counts |
| `find` | 75% | Tree format |
| `grep` | 70% | Truncated lines, grouped by file |
| `diff` | 65% | Context reduced |
| `wc` | 60% | Compact counts |
| `cat` / `head` / `tail <file>` | 60-80% | Smart file reading via `rtk read` |
| `rtk smart <file>` | 85% | 2-line heuristic code summary (signatures only) |
## Cloud and Data
| Command | Savings | What changes |
|---------|---------|--------------|
| `aws` | 70% | JSON condensed, relevant fields only |
| `psql` | 65% | Query results without decoration |
| `curl` | 60% | Response body only, headers stripped |
## Global flags
These flags apply to all RTK commands and can push savings even higher:
| Flag | Description |
|------|-------------|
| `--ultra-compact` | ASCII icons, inline format — extra token reduction on top of normal filtering |
| `-v` / `--verbose` | Show filtering details on stderr (`-v`, `-vv`, `-vvv` for increasing detail) |
```bash
# Ultra-compact: even smaller output
rtk git log --ultra-compact
# Debug: see what RTK is doing
rtk git status -vvv
```
:::note
Use `--ultra-compact` (long form) rather than `-u` when working with Git commands. Git's own `-u` flag means `--set-upstream` and the short form can cause confusion.
:::
## Commands that are not rewritten
If a command isn't in the list above, RTK runs it through passthrough — the output reaches the LLM unchanged. You can explicitly track unsupported commands:
```bash
rtk proxy make install # runs make install, tracks usage, no filtering
```
To check which commands were missed opportunities: `rtk discover`.