tokengraph 0.1.0 → 0.2.0

package/LICENSE

@@ -19,36 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-Third-party notices
-
-The agent and model-maker marks in packages/core (agent-logos.ts, maker-logos.ts),
-which the published bundle includes, are adapted from Lobe Icons
-(https://github.com/lobehub/lobe-icons), used under the MIT License:
-
-  MIT License
-
-  Copyright (c) 2023 LobeHub
-
-  Permission is hereby granted, free of charge, to any person obtaining a copy
-  of this software and associated documentation files (the "Software"), to deal
-  in the Software without restriction, including without limitation the rights
-  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-  copies of the Software, and to permit persons to whom the Software is
-  furnished to do so, subject to the following conditions:
-
-  The above copyright notice and this permission notice shall be included in all
-  copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-  SOFTWARE.
-
-The product names and marks themselves belong to their owners and are used only
-to identify the tools tokengraph reads.

package/README.md

@@ -19,7 +19,11 @@
 </p>
 
 <p align="center">
-  <b>English</b> · <a href="https://github.com/altindalorcun/tokengraph/blob/main/README.zh-CN.md">简体中文</a> · <a href="https://github.com/altindalorcun/tokengraph/blob/main/README.ja.md">日本語</a> · <a href="https://github.com/altindalorcun/tokengraph/blob/main/README.ko.md">한국어</a> · <a href="https://github.com/altindalorcun/tokengraph/blob/main/README.tr.md">Türkçe</a>
+  <a href="https://tokengraph.app">Website</a> · <a href="https://tokengraph.app/docs/">Docs</a> · <a href="https://www.npmjs.com/package/tokengraph">npm</a>
+</p>
+
+<p align="center">
+  <b>English</b> · <a href="https://github.com/altindalorcun/tokengraph/blob/main/README.tr.md">Türkçe</a>
 </p>
 
 <p align="center">
@@ -29,6 +33,10 @@
   </picture>
 </p>
 
+<p align="center">
+  <img alt="The tokengraph terminal view: typing npx tokengraph opens a year heatmap, then the Insights and Setup tabs" src="https://raw.githubusercontent.com/altindalorcun/tokengraph/main/docs/assets/demo.gif" width="720">
+</p>
+
 ## Quick start
 
 ```bash
@@ -103,15 +111,16 @@ re-reading a big cached context would drown a day of real work. It measures work
 | | |
 | --- | --- |
 | **What leaves your machine** | To a public gist on your account: the SVG graphs (daily token totals and the names of the model families they are coloured by) and a README with the embed snippet and a link. To a secret gist on your account: one file per machine with its daily token counts per agent, model and pricing tier, a random machine id, a label such as `darwin-3f2a1c`, a hashed machine fingerprint, the CLI version and the time of the last update; if you use the Cursor fetch, also your Cursor account's daily counts per model under a hashed account key; and a short README. Both only after `tokengraph login`, and only when tokengraph publishes (`sync`, a hook, the schedule, `login`, or `readme --colors`). `sync --local`, `story`, `status`, `export` and `import` never do, and `view` does only when you pick Sync (or login, or graph colours) in it. |
-| **What stays on this machine** | Which hour of the day you used each agent. tokengraph keeps weighted tokens per local hour in `state.json` for the busiest-hour card, the "When you code" chart and `export --hours`; they are never put in a machine file, the data gist, the graph or a story card. Hours exist only for days your agents' logs still hold. |
-| **What tokengraph fetches** | Only for Cursor, and only while it is on (the default once Cursor is signed in; `tokengraph cursor off` stops it): `sync` reads Cursor's own sign-in token from Cursor's local database (read-only, that one row) and asks cursor.com for your own usage export, the file the Cursor dashboard's export button gives you. The token goes to cursor.com only, is held in memory for the request and is never stored, printed or logged. What is kept is the usage rows (timestamps, model names, token counts). `sync --local` never does. |
+| **What stays on this machine** | Which project you used each agent on: tokengraph notes the folder each session ran in, keeps it in `state.json` to total usage per project (and in `cursor-events.jsonl` for Cursor turns, and in `config.json` for a project you named), and never puts a project name or a path in a machine file, a gist, the graph or a story card. `export --projects` writes project names only when you ask for that file. Which hour of the day you used each agent. tokengraph keeps weighted tokens per local hour in `state.json` for the busiest-hour card, the "When you code" chart and `export --hours`; they are never put in a machine file, the data gist, the graph or a story card. Hours exist only for days your agents' logs still hold. |
+| **What tokengraph fetches** | Only for Cursor, and only while it is on (the default once Cursor is signed in; `tokengraph cursor off` stops it): `sync` reads Cursor's own sign-in token from Cursor's local database (read-only, that one row) and asks cursor.com for your own usage export, the file the Cursor dashboard's export button gives you. The token goes to cursor.com only, is held in memory for the request and is never stored, printed or logged. What is kept is the usage rows (timestamps, model names, token counts). `sync --local` never does. Separately, the terminal view asks the npm registry (`registry.npmjs.org`) for the latest tokengraph version, at most once a day, so it can tell you when an update is out. That request carries no usage data; like any download it shows npm your IP address and the tokengraph version you run. `tokengraph update off` stops it. |
 | **What never does** | Prompts, answers, code, file names, paths. Nothing is sent to any tokengraph server: there is none. |
 | **How to remove it** | `tokengraph logout` forgets the login on this machine. Delete the two gists on [gist.github.com](https://gist.github.com) to remove what was published. |
 
 A secret gist is unlisted, not private: anyone who has its URL can read it. It holds the fields
 listed above and never a hostname, a user name or an e-mail address. Until you run `tokengraph login`,
-nothing is published; the only network call before that is the Cursor fetch to cursor.com, and only
-when Cursor is signed in on the machine and you run `sync` (`tokengraph cursor off` turns it off).
+nothing is published; the only network calls before that are the view's daily version check to the
+npm registry (`tokengraph update off` turns it off) and the Cursor fetch to cursor.com, and that one
+only when Cursor is signed in on the machine and you run `sync` (`tokengraph cursor off` turns it off).
 
 ## Supported agents
 
@@ -140,22 +149,24 @@ not supported, because its local history rounds token counts.
 
 ## Commands
 
-Every command takes `--help`. An unknown option is an error.
+Every command takes `--help`. An unknown option is an error. The full guide is at [tokengraph.app/docs](https://tokengraph.app/docs/).
 
 | Command | What it does |
 | --- | --- |
-| `tokengraph [view]` | Opens the live terminal view: year heatmap, models, agents, streaks, a "When you code" chart of the hours you work in (← → picks an hour), and a Setup tab to manage hooks, the hourly schedule, sync, Cursor, export and story without leaving the view. `:` or Ctrl-K opens a command palette; each action shows its CLI equivalent. `--print` prints a static snapshot, `--no-motion` skips animations, `--no-live` stops rescanning while open, `--theme auto\|dark\|light`. The default command in a terminal. |
+| `tokengraph [view]` | Opens the live terminal view: year heatmap, models, agents, streaks, a "When you code" chart of the hours you work in (← → picks an hour), and a Setup tab to manage hooks, the hourly schedule, sync, Cursor, export and story without leaving the view. The Projects tab shows tokens and estimated cost per project, with its models and agents. `:` or Ctrl-K opens a command palette; each action shows its CLI equivalent. `--print` prints a static snapshot, `--no-motion` skips animations, `--no-live` stops rescanning while open, `--theme auto\|dark\|light`. The default command in a terminal. |
 | `tokengraph login` | Connects GitHub, publishes your graph to your own gist, prints the README snippet. Uses your GitHub CLI login if you have one (`--gh`), or a one-time code you approve in the browser (`--device`, `--no-open`). Asks for gist access only. |
 | `tokengraph logout` | Forgets the GitHub login on this machine. Local data and your gists stay. |
 | `tokengraph sync` | Reads every agent's logs into the ledger and, when logged in, publishes. With Cursor signed in it first fetches your Cursor usage from cursor.com (at most once an hour). `--since <days>` sets how far back to read (default 90), `--local` never touches the network. |
+| `tokengraph projects` | Shows tokens, share and estimated cost per project on this machine; `--range 7d\|30d\|90d\|1y\|all`, `--json`. `projects show <name>` adds its models, agents and folders. A project is a git repository, or the folder a session ran in when there is none. `projects name <name-or-folder> <new-name>` renames one, and folders with the same name count as one project, so that is also how you merge them; `--reset` removes a name. |
 | `tokengraph readme` | Prints the README snippet and copies it. `--compact`, `--colors model\|single`. |
 | `tokengraph story` | Draws story cards, saves the PNGs (to your Downloads folder unless `--out <dir>`) and offers to send them to your phone. `--template skyline\|receipt\|sticker\|all`, `--range today\|7d\|30d\|1y`, `--no-cost`, `--qr` / `--no-qr`, `--no-preview`, `--handle <name>` (default: your GitHub login, or your computer's user name when you are not logged in). |
 | `tokengraph status [--json]` | Shows the GitHub account, the ledger, your machines, which background syncs are installed and healthy, the folders each agent is read from (and which exist), and how long Claude Code, Gemini CLI and Qwen Code keep their logs, with a warning when a short retention puts history at risk. `--json` prints it as one JSON object for scripts and AI agents; it includes the secret gist's address and local paths, so don't paste it in public. |
 | `tokengraph install-hook --agent <claude-code\|cursor\|codex\|gemini-cli>` | Makes that agent start a background sync when it finishes. `--remove` uninstalls it, `--dry-run` shows what would change. For Claude Code, `--event SessionEnd\|Stop\|SubagentStop` picks the hook event (default `SessionEnd`). |
 | `tokengraph schedule` | Installs an hourly background sync: launchd on macOS, cron on Linux, Task Scheduler on Windows. `schedule --remove` turns it off, `--dry-run` shows what would be installed. |
-| `tokengraph export` | Writes your daily usage as CSV or JSON, one row per day, agent, model and pricing tier, with weighted tokens and estimated cost. `--format csv\|json`, `--out <file>`, `--since <date>`, `--all-machines`. `--hours` writes one row per day, local hour and agent instead (date, hour, source, weighted tokens; this machine only). Reads the ledger only. |
+| `tokengraph export` | Writes your daily usage as CSV or JSON, one row per day, agent, model and pricing tier, with weighted tokens and estimated cost. `--format csv\|json`, `--out <file>`, `--since <date>`, `--all-machines`. `--hours` writes one row per day, local hour and agent instead (date, hour, source, weighted tokens; this machine only). `--projects` adds a `project` column with one row per day, project, agent, model and tier; it holds the name, never the path, and covers this machine only. Reads the ledger only. |
 | `tokengraph cursor fetch\|on\|off` | Fetches your Cursor usage from cursor.com now (ignoring the hourly pause), or turns the automatic fetch on or off. `tokengraph import cursor --fetch` does the same as `cursor fetch`. `status` shows its state. If Cursor's sign-in has expired, open Cursor once. |
 | `tokengraph import cursor <file.csv>` | Adds Cursor history by hand, for when fetching is off: download the usage CSV from the Cursor dashboard (Usage, export CSV) and pass it here. 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. Never publishes. |
+| `tokengraph update` | Installs the latest version with npm, after showing the command and asking (`--yes` skips the question). The terminal view checks once a day in the background and, when a new version is out, says so in its status bar and updates on `u`, then reopens. Offline it stays silent. A copy run through `npx`, or installed some other way, is left alone and you get the command to run. `update off` stops the daily check, as do `TOKENGRAPH_NO_UPDATE_CHECK=1` and `NO_UPDATE_NOTIFIER=1`; it never runs in CI. |
 | `tokengraph uninstall` | Removes the Claude Code, Cursor, Codex and Gemini CLI hooks and the hourly schedule. `--purge` also deletes tokengraph's own files in `~/.tokengraph` (ledger, login, logs, the Cursor event, import and fetched-account files) and keeps anything else there, `--yes` skips the question, `--dry-run` changes nothing. Your gists are never touched. |
 
 Hooks and the schedule store the path of the installed program, so install tokengraph globally
@@ -171,6 +182,12 @@ nothing twice.
 
 ## FAQ
 
+**How is this different from ccusage or tokscale?** Both are good tools. [ccusage](https://github.com/ryoppippi/ccusage)
+is the one for detailed daily, weekly, monthly and session reports in your terminal.
+[tokscale](https://github.com/junhoyeo/tokscale) has a public leaderboard and profiles, which you join by logging in and
+submitting your usage. tokengraph is for showing your year on your GitHub profile: the graph lives in your own gist,
+several machines merge through your own secret gist, and there is no tokengraph server or account.
+
 **Why gists?** They are free, they belong to you, 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.
@@ -186,7 +203,11 @@ model whose vendor does not publish one (retired models, previews without a pric
 **Why weighted tokens?** Raw totals are mostly cache reads, which are cheap and large. Counting
 them at a tenth keeps the graph about work done. The formula is under [How it works](#how-it-works).
 
-**Does it work offline?** Yes. `view`, `story`, `status`, `export`, `import <file>` and `sync --local` work without the network. `view` publishes only if you pick Sync (or login / colours) in it.
+**Can I see how much one project cost?** Yes: the Projects tab or `tokengraph projects`. Numbers start from the logs still on your disk when you first run this version, and Claude Code deletes its logs after 30 days by default. Usage with no known project, such as cursor.com's account history, is shown as Not assigned, so the total still matches. The cost is an estimate at public list prices, not what a subscription plan charges.
+
+**Can a team use it?** There is no team view and no server, but `tokengraph export --projects` gives each person a file with project names and no paths, and you can combine those files however you like.
+
+**Does it work offline?** Yes. `view`, `story`, `status`, `export`, `import <file>` and `sync --local` work without the network. `view` publishes only if you pick Sync (or login / colours) in it, and skips its update check silently when there is no connection.
 Only publishing needs GitHub, and the Cursor fetch (`sync`, `cursor fetch`) needs cursor.com.
 
 **How do I stop?** `tokengraph uninstall` removes the Claude Code, Cursor, Codex and Gemini CLI hooks and the hourly
@@ -210,3 +231,5 @@ If tokengraph made your profile better, a ⭐ helps other people find it.
 
 MIT, see [LICENSE](https://github.com/altindalorcun/tokengraph/blob/main/LICENSE). Bundled third-party components: see
 [THIRD-PARTY-NOTICES.md](https://github.com/altindalorcun/tokengraph/blob/main/packages/cli/THIRD-PARTY-NOTICES.md).
+
+tokengraph is a [goldenbranch.dev](https://goldenbranch.dev) project.

package/THIRD-PARTY-NOTICES.md

@@ -29,6 +29,7 @@ tokengraph itself is MIT licensed (see `LICENSE`).
 | unicode-trie | 2.0.0 | MIT | https://github.com/devongovett/unicode-trie |
 | fflate | 0.7.3 | MIT | https://github.com/101arrowz/fflate |
 | cssesc (inside satori's `dist`) | 3.0.0 | MIT | https://github.com/mathiasbynens/cssesc |
+| Lobe Icons (agent and model-maker marks, adapted) | as adapted in `packages/core` | MIT | https://github.com/lobehub/lobe-icons |
 | css-color-keywords | 1.0.0 | ISC | https://github.com/sonicdoe/css-color-keywords |
 | IBM Plex Sans and IBM Plex Mono | as shipped in `assets/fonts` | OFL-1.1 | https://github.com/IBM/plex |
 | Rust crates in the WebAssembly binaries | see [the list below](#rust-crates-compiled-into-the-webassembly-binaries) | MIT, Apache-2.0, BSD-3-Clause, Zlib, MPL-2.0 | see the list below |
@@ -1005,6 +1006,38 @@ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ```
 
+### Lobe Icons
+
+Source: https://github.com/lobehub/lobe-icons
+
+The agent and model-maker marks in `packages/core` (`agent-logos.ts`, `maker-logos.ts`), which `bundle/bin.js`
+includes, are adapted from Lobe Icons. The product names and marks themselves belong to their owners and are used only
+to identify the tools tokengraph reads.
+
+```text
+MIT License
+
+Copyright (c) 2023 LobeHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## ISC licensed components
 
 ### css-color-keywords 1.0.0