606b86ed43
feat(gain): colored dashboard with efficiency meter and impact bars ( #129 )
...
* feat(gain): add colored dashboard with efficiency meter and impact bars
Upgrade `rtk gain` output with rich terminal visualization:
- Colored percentage cells (green ≥70%, yellow ≥40%, red <40%)
- Efficiency meter: ASCII progress bar with savings percentage
- Impact bars: proportional block charts per command
- Styled section headers (bold green)
- Command names in bright cyan
- History tier indicators (▲/■/•)
- Dynamic column widths for clean table alignment
- KPI-style key-value layout for summary metrics
All visual features are TTY-aware via std::io::IsTerminal — output
degrades gracefully to plain text when piped or redirected.
No new dependencies (uses existing `colored` crate).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com >
* Add dashboard visualization screenshot
Shows colored terminal output of `rtk gain -p` with:
- Project-scoped token savings header
- Efficiency meter with color gradient
- Per-command table with colored Avg% and Impact bars
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com >
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com >
2026-02-15 15:50:24 +01:00
8c67a2f1e7
docs: update for hook-first installation mode
...
## README.md Updates
**Quick Start section:**
- Clear 3-step process: verify → install hook → test
- Prominently recommend `rtk init -g` (hook-first mode)
- Explain 99.5% token savings (2000 → 10 tokens)
- Show alternative modes (--claude-md, local init)
**Configuration section:**
- New comparison table: 4 modes with token costs
- Migration instructions for existing users
- Clarify hook vs CLAUDE.md injection differences
**Auto-Rewrite Hook section:**
- Promote automated install (`rtk init -g`) as primary method
- Keep manual install as fallback
- Add verification step (`rtk init --show`)
## INSTALL.md Updates
**Project Initialization:**
- Recommend global hook-first setup (with rationale)
- Show token savings: 99.5% reduction
- Document local setup as alternative
- Add upgrade/migration guide for existing users
## TROUBLESHOOTING.md Updates
**RTK not working section:**
- Option A: Automated (`rtk init -g`) - recommended
- Option B: Manual install - fallback
- Clarify absolute path requirement in settings.json
- Add verification step
## Fixes Documentation Gaps
Before:
- ❌ No mode comparison
- ❌ No migration guide
- ❌ Manual install only
- ❌ Unclear token impact
After:
- ✅ Clear mode comparison with use cases
- ✅ Automatic migration documented
- ✅ Automated install prioritized
- ✅ Quantified token savings (99.5%)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-02-07 15:28:39 +01:00
521eb1b9bc
docs(tracking): complete API documentation + rustdoc comments
...
Add comprehensive documentation for tracking.rs public APIs:
**New Files:**
- docs/tracking.md (12 pages)
- Architecture & data flow
- All public APIs (12 methods, 7 types)
- Usage examples (basic, CI/CD, dashboards, Rust lib)
- JSON/CSV export schemas
- Database schema & migrations
- Integration examples (GitHub Actions, Python, Rust)
- Security, performance, troubleshooting
- claudedocs/TRACKING_DOCUMENTATION.md
- Documentation summary & metrics
**Updated Files:**
- src/tracking.rs
- Module-level docs (//!)
- Comprehensive doc comments (///) for all public APIs
- Examples with error handling
- Deprecation notices for legacy functions
- README.md
- Pointer to docs/tracking.md after rtk gain section
**Coverage:**
- 7 public structs documented
- 12 public methods documented
- 3 utility functions documented
- 20+ code examples
- 3 integration examples (CI/CD, dashboards, Rust lib)
- JSON/CSV/SQL schemas
**Testing:**
- All 6 tracking tests still pass
- 100% coverage maintained
Closes gap: CLI was documented, but public APIs were not.
Now fully documented for external integration (CI/CD, dashboards, Rust lib usage).
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-02-03 11:22:20 +01:00
00623cb80e
docs: point all documentation to upstream instead of fork
...
## Problem
Documentation incorrectly promoted the fork over upstream for installation,
creating confusion about which repository is the source of truth.
## Changes
### Installation Instructions
- **README.md**: Restored curl install pointing to upstream (pszymkowiak/rtk)
- **README.md**: Removed "Fork with All Features" section
- **INSTALL.md**: Added curl install, removed fork recommendation
- **TROUBLESHOOTING.md**: All installation paths → upstream
### Repository References
- **README.md**: Removed fork from repo list, issues → rtk-ai/rtk
- **CLAUDE.md**: Removed fork mention from project list
- **CHANGELOG.md**: Repository and issues → rtk-ai/rtk
- **ROADMAP.md**: Installation instructions → upstream curl
### Scripts
- **check-installation.sh**: Install instructions → upstream curl
## Result
All documentation now consistently points to upstream (rtk-ai/rtk, pszymkowiak/rtk)
as the source of truth for installation and issues.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-02-02 18:39:18 +01:00
e2e8be42a7
docs: clarify rtk name collision and fix installation confusion
...
## Problem
Users are accidentally installing the wrong "rtk" package:
- Rust Type Kit (reachingforthejack/rtk) - type generation tool
- Rust Token Killer (rtk-ai/rtk) - LLM token optimizer
This causes confusion when `rtk gain` doesn't exist after installation.
## Changes
### Documentation Updates
- **README.md**: Add prominent warning about name collision at top
- **README.md**: Fix installation instructions with mandatory verification
- **CLAUDE.md**: Add name collision warning with verification steps
- **INSTALL.md**: Clarify pre-installation checks and wrong package handling
### New Files
- **docs/TROUBLESHOOTING.md**: Comprehensive troubleshooting guide covering:
- Wrong rtk installed (Type Kit vs Token Killer)
- cargo install rtk pitfalls
- Missing commands (vitest, pnpm, etc.)
- PATH issues and compilation errors
- **scripts/check-installation.sh**: Automated diagnostic script that verifies:
- RTK installed and in PATH
- Correct version (Token Killer with `rtk gain`)
- Available features
- Claude Code integration status
- Auto-rewrite hook configuration
## Verification
After these changes, users can quickly diagnose installation issues:
```bash
bash scripts/check-installation.sh
```
Fixes installation confusion reported by multiple users.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-02-02 15:20:39 +01:00
76703ca3f5
feat: add comprehensive temporal audit system for token savings analytics
...
Implement day-by-day, week-by-week, and monthly breakdowns with JSON/CSV export
capabilities for in-depth token savings analysis and reporting.
New Features:
- Daily breakdown (--daily): Complete day-by-day statistics without 30-day limit
- Weekly breakdown (--weekly): Sunday-to-Saturday week aggregations with date ranges
- Monthly breakdown (--monthly): Calendar month aggregations (YYYY-MM format)
- Combined view (--all): All temporal breakdowns in single output
- JSON export (--format json): Structured data for APIs, dashboards, scripts
- CSV export (--format csv): Tabular data for Excel, Google Sheets, data science
Technical Implementation:
- src/tracking.rs: Add DayStats, WeekStats, MonthStats structures with Serialize
- src/tracking.rs: Implement get_all_days(), get_by_week(), get_by_month() SQL queries
- src/main.rs: Extend Commands::Gain with --daily, --weekly, --monthly, --all, --format flags
- src/gain.rs: Add print_daily_full(), print_weekly(), print_monthly() display functions
- src/gain.rs: Implement export_json() and export_csv() for data export
Documentation:
- docs/AUDIT_GUIDE.md: Comprehensive guide with examples, workflows, integrations
- README.md: Update Data section with new audit commands and export formats
- claudedocs/audit-feature-summary.md: Technical summary and implementation details
Database Scope:
- Global machine storage: ~/.local/share/rtk/history.db
- Shared across all projects, worktrees, and Claude sessions
- 90-day retention policy with automatic cleanup
- SQLite with indexed timestamp for fast aggregations
Use Cases:
- Trend analysis: identify daily/weekly patterns in token usage
- Cost reporting: monthly savings reports for budget tracking
- Data science: export CSV/JSON for pandas, R, Excel analysis
- Dashboards: integrate JSON export with Chart.js, D3.js, Grafana
- CI/CD: automated weekly/monthly savings reports via GitHub Actions
Examples:
rtk gain --daily # Day-by-day breakdown
rtk gain --weekly # Weekly aggregations
rtk gain --all # All breakdowns combined
rtk gain --all --format json | jq . # JSON export with jq
rtk gain --all --format csv # CSV for Excel/analysis
Backwards Compatibility:
- All existing flags (--graph, --history, --quota) preserved
- Default behavior unchanged (summary view)
- No database migration required
- Zero breaking changes
Performance:
- Efficient SQL aggregations with timestamp index
- No impact on rtk command execution speed
- Instant queries even with 90 days of data
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com >
2026-01-30 11:12:45 +01:00
heAdz0r