Everything the tokengraph CLI does, from the first npx tokengraph to the last option. Written for version 0.1.0; every command also takes --help.
tokengraph needs Node.js 22 or newer (22.13 or newer to read OpenCode, Kilo CLI, Copilot CLI and Goose, which keep their usage in a database, and for the Cursor fetch). It runs on macOS and Linux, and on Windows with rough edges. Try it without installing anything:
npx tokengraphThat opens the terminal view of every agent it finds on this machine. Nothing is sent anywhere, and nothing needs logging in. When you want the graph on your GitHub profile, and story cards for your phone:
npx tokengraph loginnpx tokengraph storyTo keep the graph current without thinking about it, install it once and turn on the hourly sync:
npm install -g tokengraph && tokengraph scheduletokengraph (or tokengraph view) opens a live view in your terminal. It reads the logs on this machine only and rescans while it is open. It has five tabs:
h manages the hooks of the agents that have one.← → or the mouse picks an hour and shows its share); your busiest weekday; and the last 12 months.The command palette (: or Ctrl-K) has the same actions plus the tabs and the view’s own commands; type to filter it. The view publishes only when you pick an action that does (sync, login or graph colours); opening and rescanning never touch the network.
tokengraph view --print prints a static snapshot instead (the tiles, the heatmap, the top five models and your busiest hour), which is also what you get when the output is not a terminal. See view for the other options.
tokengraph login connects GitHub and publishes your graph. If the GitHub CLI is logged in, it offers to use that login; otherwise it shows a one-time code to approve at github.com/login/device. Either way it asks for gist access only. It then publishes the graph to a public gist on your GitHub, copies the README snippet to your clipboard and, in a terminal, offers to turn on the hourly sync.
Paste the snippet into your profile README (the repository named after your GitHub login). tokengraph readme prints it again at any time:
<a href="https://github.com/altindalorcun/tokengraph">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://gist.githubusercontent.com/octocat/a1b2c3d4e5f6a7b8c9d0/raw/tokengraph-dark.svg">
<img alt="My AI coding token usage, made with tokengraph" src="https://gist.githubusercontent.com/octocat/a1b2c3d4e5f6a7b8c9d0/raw/tokengraph-light.svg">
</picture>
</a>The graph switches between light and dark with the reader’s GitHub theme, and every sync updates the same gist, so the snippet never changes. It shows the last 52 weeks, one square a day, with a strip of five figures: today, your streak (and longest streak), your best day, active days, and the family that led the most days. Shades are measured against your own busy and quiet days, not a fixed scale.
Each day takes the colour of the model family that did most of that day’s work. Models that fit none of the families count as “Other models”.
tokengraph readme --colors single draws the graph in one colour instead (the fifth figure becomes the average active day), and --colors model switches back. Both republish. --compact prints a snippet for a smaller graph without labels and legends.
tokengraph sync reads every agent’s logs into the local ledger and, when you are logged in, publishes. It reads the last 90 days by default (--since 400 reaches further back), and --local never touches the network. You rarely need to run it yourself, because two kinds of background sync run it for you:
tokengraph schedule installs an hourly sync: launchd on macOS, cron on Linux, Task Scheduler on Windows. It is the only background sync for Cline, OpenCode, Kilo CLI, Copilot CLI, pi, Qwen Code and Goose, which have no hook. tokengraph schedule --remove turns it off.
Four agents can start a background sync themselves when they finish:
Install one with tokengraph install-hook --agent <name>, preview it with --dry-run and remove it with --remove. tokengraph status shows which hooks and schedule are installed and whether they have run.
Every agent is read from its default folder plus any folder its environment variable names (such as $CLAUDE_CONFIG_DIR or $CODEX_HOME). tokengraph remembers such a folder the first time a command runs with it set, so the hourly sync and the hooks, which do not get your shell’s environment, still read it. tokengraph status lists the folders it scans and whether they exist.
tokengraph story draws three cards sized for Instagram and TikTok stories and saves them as PNG files in your Downloads folder:
Skyline. Your weeks as a city of towers, with the latest day lit up.
Receipt. A receipt of the models you ran, one line each.
Sticker. A transparent sticker with the total, to lay over a photo.
It asks which period to cover: today, 7 days, 30 days or 12 months. --range today|7d|30d|1y skips the question, --template draws only one card, and --no-cost leaves the estimated cost off.
After saving, it offers to send them to your phone with a QR code. Scan it with your phone on the same Wi-Fi and save the cards to Photos from the page that opens. Your computer serves the files to your phone itself, from memory and under a random address, until every card is saved or after 10 idle minutes. Nothing is uploaded anywhere. --qr skips the question and --no-qr only saves the files.
tokengraph reads the usage counters the agents already write to disk, never your prompts or answers. Each day’s number is a weighted token count:
weighted tokens = input + output + cache writes + 0.1 × cache readsCache reads cost a fraction of fresh input, so they count a tenth. Without that, one long session re-reading a big cached context would drown a day of real work. It measures work, not a bill.
The view, story cards and export show an estimated cost at public API list prices, from a dated price table. It is not what you were billed, which depends on your plan. Claude, GPT and the o-series, Gemini, Grok and Cursor’s Composer are priced. Open-weight models (DeepSeek, Qwen, Llama, Mistral, MiniMax and the like) and models whose vendor publishes no price are left unpriced: never counted as $0, so a total is a lower bound.
Eleven agents, each read from its own files on this machine. Aider is not supported, because its local history rounds token counts. New agents arrive as adapter pull requests (opens in a new tab).
~/.claude/projects and transcripts (also $CLAUDE_CONFIG_DIR), and the Code and Cowork sessions of the Claude desktop apptokengraph install-hook --agent claude-code syncs when a session ends~/.codex/sessions and archived_sessions (also $CODEX_HOME)tokengraph install-hook --agent codex syncs after a turn, at most every 10 minutesnotify setting that is not its own.tokengraph install-hook --agent cursor, then restart Cursor~/.gemini/tmp/*/chats, and ~/.cache/.gemini/tmp from the macOS sandbox (also under $GEMINI_CLI_HOME)tokengraph install-hook --agent gemini-cli syncs when a session ends; the schedule also covers itsaoudrizwan.claude-dev/tasks in VS Code-family editors (VS Code, Cursor, VSCodium, Windsurf, Positron, Trae, Kiro, Antigravity and others, remote servers included), and ~/.cline/datatokengraph schedule~/.local/share/opencode/opencode*.db and the older storage/ folder (also $XDG_DATA_HOME; $OPENCODE_DB adds one database)tokengraph schedule~/.local/share/kilo/kilo*.db (also $XDG_DATA_HOME; $KILO_DB adds one database)tokengraph schedule~/.copilot/session-store.db (also $COPILOT_HOME)tokengraph schedule~/.pi/agent/sessions (also $PI_CODING_AGENT_DIR and $PI_CODING_AGENT_SESSION_DIR)tokengraph schedule~/.qwen/projects (chats and background subagents) and Qwen Code’s own usage ledger in ~/.qwen/usage (also under $QWEN_HOME and $QWEN_RUNTIME_DIR)tokengraph schedule/branch copy earlier requests, which are counted once.~/.local/share/goose/sessions/sessions.db (also $XDG_DATA_HOME or $GOOSE_PATH_ROOT; %APPDATA%\Block\goose\data on Windows)tokengraph scheduleCursor keeps no usable token counts on disk, so tokengraph has three ways to get them:
tokengraph sync fetches your own usage history from cursor.com, the same file cursor.com’s Export CSV button gives you, at most once an hour. It covers every machine, the editor, the CLI and cloud agents, so it is counted once however many machines fetch it. The first fetch reads your whole history.tokengraph install-hook --agent cursor (then restart Cursor) records each turn on this machine as it happens, to fill the hours before cursor.com has them.tokengraph import cursor <file.csv>, on one machine only.Log in on each machine with the same GitHub login. Each machine writes its own file, machine-<id>.json, to a secret gist on your GitHub. When one syncs, the graph is built from its own ledger plus every other machine’s file, summed per day and model, so a laptop and a desktop show up as one graph.
The same files are a backup: after a reinstall or a wiped ~/.tokengraph, tokengraph login recognises the machine, restores its history and counts nothing twice. tokengraph export --all-machines adds the other machines to an export.
Your usage stays on this machine until you run tokengraph login. After that, publishing (a sync, a hook, the schedule, login, readme --colors, or the same actions in the terminal view) writes to two gists on your own GitHub:
darwin-3f2a1c, a hashed machine fingerprint, the CLI version and the time of the last update; with the Cursor fetch, also your Cursor account’s daily counts per model under a hashed account key.Which hour of the day you work stays on this machine: it is used by the view and export --hours and never published. Prompts, answers, code, file names and paths are never read. There is no tokengraph server. The privacy page has the details.
The one other thing that goes over the network is the Cursor fetch, which reads your own usage from cursor.com while Cursor is logged in and is off with tokengraph cursor off.
tokengraph uninstall removes the hooks and the hourly schedule; add --purge to also delete tokengraph’s own files in ~/.tokengraph. Then npm uninstall -g tokengraph.tokengraph logout forgets the GitHub login on this machine.Every command takes --help, and an unknown option is an error. tokengraph --version prints the version.
Opens the live terminal view of your usage. It reads local data only, and publishes only when you pick an action that does in its Setup tab or command palette (sync, login or graph colours). It is what plain tokengraph runs in a terminal.
Reads every agent’s local data into the ledger (~/.tokengraph/state.json) and, when you are logged in, publishes your graph to your gist. When Cursor is logged in on this machine, it first fetches your Cursor usage from cursor.com, at most once an hour. Hooks and the schedule run this same command in the background.
Connects GitHub so your graph can be published to your own gist, publishes it once and prints the README snippet. If the GitHub CLI is logged in it offers to use that login, otherwise you approve a one-time code in the browser. It asks for gist access only, and in a terminal it offers to turn on the hourly sync.
Prints the snippet that puts your graph in a GitHub README and copies it to the clipboard.
Forgets the GitHub login and gist ids on this machine. The local ledger and the machine id are kept, and your gists stay on GitHub.
Shows the GitHub login, the local ledger, your machines, the Cursor fetch, which hooks and schedule are installed and whether they ran, the folders each agent is read from (and which exist), and how long Claude Code, Gemini CLI and Qwen Code keep their logs.
Makes an agent start a background sync when it finishes, so your graph stays current.
Runs a sync every hour in the background: launchd on macOS, cron on Linux, Task Scheduler on Windows. It covers the agents that have no hook, and the Cursor fetch.
Draws your usage as Instagram and TikTok story cards, saves them as PNG files and can send them to your phone with a QR code. Reads local data only.
Writes your usage from the local ledger, one row per day, agent, model and pricing tier, with weighted tokens and the estimated cost. It never publishes; run tokengraph sync --local first for the newest numbers.
Controls the Cursor fetch from cursor.com. It is on by default when Cursor is logged in on this machine.
Adds Cursor history from a usage CSV you download from cursor.com yourself (Usage, then Export CSV), for when the fetch is off. Importing the same or an overlapping file twice adds nothing twice. Import on one machine only: machines are added together, so the same file on two machines counts twice. import cursor --fetch does the same as cursor fetch.
Removes everything tokengraph installed on this machine: the Claude Code, Cursor, Codex and Gemini CLI hooks and the hourly schedule. Your gists and your agents’ own data are never touched.
They are free, they are yours, GitHub serves and caches the images, and there is no server for anyone to run, trust or shut down. If tokengraph disappears tomorrow, your graph keeps working.
Yes. view, story, status, export, import <file> and sync --local never use the network. Only publishing needs GitHub, and the Cursor fetch needs cursor.com.
Cache reads count a tenth, and the estimated cost uses list prices, not your plan. Some agents also leave calls out of their logs (see the notes under Supported agents).
tokengraph export writes CSV or JSON, one row per day, agent, model and pricing tier, with weighted tokens and the estimated cost. --hours writes hour-of-day rows instead.
Paths, hooks and the hourly Task Scheduler job are written for Windows, but tokengraph is developed on macOS and Linux, so expect rough edges and please open an issue (opens in a new tab).