token-oracle 0.1.2

_{Live dashboard — staged multi-subscription forecast for Claude Code and Grok, with time left before each cap. No API keys; reads local logs, optionally verifies against the sites.}

Live usage in your status bar

Wire it once:

oracle statusline --install

Claude Code (and tmux) then shows a live headline such as:

◔ 5h 26% · wk 60% · $8 today

(The 5h/wk numbers come from the rate-limit header self-ingest; cost uses local ledger.)

Install

Run it instantly — no install, using a runner you probably already have:

npx token-oracle dash         # Node
bunx token-oracle dash        # Bun
uvx token-oracle dash         # uv

Or install the token-oracle command onto your PATH:

curl -fsSL https://raw.githubusercontent.com/muslewski/token-oracle/main/install.sh | sh
uv tool install token-oracle   # uv (isolated, fast)
pipx install token-oracle      # pipx (isolated)
pip install token-oracle       # pip

npx/bunx/uvx fetch and run the latest release on demand; the installers put it on your PATH. All routes are the same offline-first tool — see SETUP.md for live web data and configuration.

Quickstart

token-oracle init         # guided setup (or --preset max20 for non-interactive)
token-oracle forecast     # live forecast — time left before your cap
token-oracle report       # what you spent, day by day (tokens + cost + % of weekly cap)
token-oracle dash         # full-screen TUI — Past ledger / Present live / Future prophecy
token-oracle doctor       # check configuration + data sources

Config can live globally (~/.config/token-oracle/config.json) or per-project (.token-oracle.json walking up from the cwd). Run token-oracle --help for all subcommands.

How it works

token-oracle reads your agent's local usage logs, computes an observed token-consumption rate over a configurable sliding window, and estimates how long you have before you exhaust your current allowance or hit your plan cap. No provider API calls — purely offline inference from log files already on your machine. Ships with pro/max5/max20 plan presets and an offline USD pricing snapshot for cost estimates, both user-overridable via plan, cost_mode, and pricing config keys.

Supported sources (first-class agent harnesses):

Multi-subscription: put "profiles": {"claude": {...}, "grok": {...}} in config.json to track both Claude Code (Max20 etc) and Grok/SuperGrok Heavy simultaneously. oracle dash shows side-by-side with reset alarms.

Future tab (in oracle dash): per-window prophecy lines, observational cap ETA warnings, and a next-24h expected-burn sparkline from the hour-of-week profile — the projection math rendered, not just a single %.

Parts & options

All subcommands accept --config FILE. Without it, resolution is $TOKEN_ORACLE_CONFIG → .token-oracle.json (cwd walk-up) → XDG global.

Grok Build users: {"source": "grok"} (or with source_opts.sessions_dir) in config; then oracle tmux / statusline / forecast surface usage. Hooks in ~/.grok/hooks/ can drive oracle snapshot.

Full reference: token-oracle <subcommand> --help

CLI reference

token-oracle {forecast,report,snapshot,statusline,tmux,doctor,dash,init,clean} [OPTIONS]

token-oracle init       [--config FILE] [--preset NAME] [--force]
token-oracle forecast   [--config FILE] [--json]
token-oracle report     [--config FILE] [--days N] [--by day|week|model] [--json]
token-oracle snapshot   [--config FILE] [--out FILE]
token-oracle statusline [--config FILE]
token-oracle tmux       [--config FILE]
token-oracle doctor     [--config FILE]
token-oracle dash       [--config FILE]
token-oracle clean      [--config FILE] [--yes]

Adapters

Output adapters let token-oracle feed your status bar or terminal multiplexer (works for Grok, Claude, etc.):

• tmux — writes a tmux-formatted status-right fragment (e.g. set -g status-right '#(oracle tmux)')
• statusline — writes a plain-text/ANSI fragment for any status line

See ADAPTERS.md for setup and configuration. Grok users in tmux get token status in bottom bar directly.

Colors

The forecast bar uses colour thresholds on projected usage at window end (as a % of cap) to signal urgency:

Works with agentic-sage

agentic-sage is a companion JS tool. Division of labor: oracle owns tokens, cost, and forecasts; sage owns sessions, fleet coordination, and guidance. Point sage at oracle's snapshot:

{
  "tokenForecastPath": "~/.local/share/token-oracle/forecast.json"
}

oracle doctor detects sage and prints the exact link hint (or flags a stale snapshot). Enable "snapshot_writethrough": true so forecast/statusline/tmux keep the file fresh automatically.

Contributing

See CONTRIBUTING.md. In brief: fork → branch from main → pytest + ruff check + mypy → pull request.

License

MIT — Copyright (c) 2026 Mateusz Muślewski.