rtk-ai / rtk-ai/rtk

feat(gain): built-in live savings dashboard (--serve / --watch)

Open
#3,191 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:cli enhancement help wanted priority:low
Dominant language
Rust
Stars
81.1k
Forks
5.1k
Avg merge
4d 21h
Merged PRs (30d)
35

Description

Summary

Add a built-in, zero-dependency way to watch token savings live instead of
re-running rtk gain by hand. Builds on two existing requests:

  • #947 — feat(gain): add --watch mode for continuous dashboard refresh
  • #2764 — feat(gain): add --json output mode for rtk gain (scripting/dashboards)

Proposed CLI:

rtk gain --serve [--port N] [--bind 127.0.0.1]   # tiny local web dashboard
rtk gain --watch                                  # in-terminal live view (no network)

Why

  • rtk gain is a one-shot snapshot — no continuous view of savings accumulating
    across an agent session.
  • --json (#2764) is the data layer; --watch/--serve is the view. A dashboard
    unifies both.

Design (aligned with RTK philosophy)

  • Zero new dependencies. --serve uses std::net::TcpListener + embedded HTML
    (no axum/warp/actix). --watch uses in-terminal redraw. Single binary preserved.
  • Same data source. Reads tracking.db (the SQLite store rtk gain already
    queries) — no new schema, no new write path.
  • Fail-open / never blocks. If the port is taken or binding fails, print a clear
    message and fall back to normal text output. Never interferes with the agent.
  • No telemetry. 100% local, same as today.
  • Lightweight view. Static HTML, auto-refresh via <meta http-equiv=refresh>, no
    JS framework. KPI cards + per-command / per-project / daily breakdowns + recent
    table. JSON API at /api/stats for Grafana etc.

Proof of concept

A reference implementation (stdlib Python, serves the panels above, reads RTK's
SQLite directly) confirms the data model is sufficient and the surface is small.
This issue proposes bringing an equivalent view into the Rust binary so no
external script is needed.

Open question for maintainers

Which flavor is preferred?

  1. rtk gain --serve (web, local-only) — easiest to share/screenshot, needs a port.
  2. rtk gain --watch (TUI) — most philosophically aligned (no network surface).
  3. Both.

Happy to help implement whichever is picked. Thanks for the great tool!

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing rtk gain implementation and its queries against tracking.db, then review #947 and #2764 plus the referenced Python proof of concept. Ask maintainers to choose --serve, --watch, or both before implementation. Done means the selected dashboard works in the Rust binary without new dependencies and preserves the stated fail-open behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, sqlite
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.