// documentation
token-oracle documentation
token-oracle forecasts when you will hit Claude Code / Grok token caps — offline from local logs, with optional browser-verified live overlay. No provider API keys required for the core path.
Site: oracle.muslewski.com · PyPI · npm shim · GitHub
Start here
| Path | For |
|---|---|
| Getting started | First hour: install → init → forecast / dash |
| Install | pipx, npm, source, library use |
| Configuration | Profiles, windows, caps, cost |
| CLI reference | Every day-one command |
Live & status surfaces
| Path | For |
|---|---|
| Live data | Browser-verified numbers (opt-in) |
| Server truth | 5h / weekly live windows |
| Statusline & tmux | Shell bar + tmux status-right |
| Integrations | Fleet and optional hooks |
Reference & fleet
| Path | For |
|---|---|
| Adapters & snapshot | forecast.json contract |
| Works with | herald, sage, atlas, armory, ferry |
Doctrine
- Offline-first — projections from logs on disk; live is opt-in.
- Honest states — missing data never invents a number.
- Snapshot is the contract — consumers read
forecast.json. - Loose coupling — oracle does not mutate sibling tool configs.
Internal specs/plans live in token-oracle-mind/ (Atlas), not under public docs/.