Subtracker (stc)

A fast, zero-dependency, responsive terminal dashboard for tracking AI subscription quotas and usage in real-time.

---

Features

• Zero External Dependencies — Single standalone native binary compiled in Rust with Ratatui.
• Multi-Provider Support — Monitors quotas and rate limits across:
  • Codex (ChatGPT / GitHub Copilot): 5-hour rolling limit, weekly limit, and reset countdowns.
  • OpenCode: Session count, cumulative cost ($), input tokens, and output tokens.
  • Google Antigravity: Gemini and Claude/GPT 5-hour and weekly quotas.
• Adaptive Responsive Scaling — Seamlessly adjusts layout density across Wide (desktop), Compact, and Narrow (split-pane/mobile) terminal windows with zero clipping.
• Live Background Polling — Automatically refreshes usage every 60 seconds with live spinners and relative timestamps (● updated just now).
• TrueColor & NO_COLOR Support — Clean visual aesthetics with semantic health colors and provider accents; respects the NO_COLOR standard.

---

Installation

Option 1: Via Cargo (crates.io) — Recommended

If you have Rust installed, install subtracker directly from crates.io:

cargo install subtracker

This compiles and places the stc binary into your Cargo bin directory (~/.cargo/bin).

---

Option 2: Pre-compiled Binaries (macOS & Windows)

Download the standalone binary directly from the latest GitHub Releases:

macOS (Apple Silicon M1/M2/M3/M4):

curl -sSL https://github.com/Morfusee/subtracker-cli/releases/latest/download/stc-aarch64-apple-darwin.tar.gz | tar -xz
sudo mv stc /usr/local/bin/

macOS (Intel):

curl -sSL https://github.com/Morfusee/subtracker-cli/releases/latest/download/stc-x86_64-apple-darwin.tar.gz | tar -xz
sudo mv stc /usr/local/bin/

Windows (PowerShell):

Download stc.exe and move it to a folder in your PATH:

Invoke-WebRequest -Uri "https://github.com/Morfusee/subtracker-cli/releases/latest/download/stc.exe" -OutFile "$HOME\.cargo\bin\stc.exe"

---

Option 3: Build from Source

git clone https://github.com/Morfusee/subtracker-cli.git
cd subtracker-cli
cargo build --release

The compiled binary will be located at:

• macOS / Linux: target/release/stc
• Windows: target\release\stc.exe

---

Usage & Keyboard Controls

Launch Subtracker by running:

stc

Key	Action
r	Trigger an immediate manual refresh across all providers
q	Quit Subtracker and cleanly restore the terminal
Ctrl+C	Exit immediately

---

Supported Providers

1. Codex

Subtracker reads your authenticated Codex session from ~/.codex/auth.json and queries the ChatGPT Codex usage endpoint.

If your session has expired, simply log in again via:

codex login

2. OpenCode

Subtracker reads your API credentials from ~/.local/share/opencode/auth.json (or OS equivalent) and queries the OpenCode Go subscription usage API:

• Sessions count
• Total monthly cost
• Input & Output token counters

3. Antigravity

Subtracker connects to the local Antigravity CLI via:

agy -p "/usage" --output-format json

---

Layout & Responsive Modes

Subtracker automatically calculates the available terminal geometry and dynamically adjusts layout density:

Mode	Width	Behavior
Wide (P3/W)	≥ 100 cols	Full desktop fidelity; side-by-side stats grid and expanded progress bars.
Compact (P2/C)	70..99 cols	Balanced layout; inline quota metrics and stacked stats.
Narrow (P1/N)	< 70 cols	Dedicated 2-line layout per quota (Line 1: label, Line 2: bar + reset) preventing label squishing.

On height-constrained windows (< 24 rows), the ASCII header is automatically hidden to ensure all provider cards and spacing remain intact with zero truncation.

---

License

This project is licensed under the MIT License.