What the install script actually does.
npx tokken-cli install is a lot to ask of a stranger. Here is everything it installs, everything it sends, and how to take it all back out — with the source one click away.
Read it before you run it
The command on the homepage runs two shell scripts. Both are served as plain text from this site, so you can read every line before anything touches your machine: install.sh sets things up once, and collect.sh is what runs on the schedule afterwards. Together they are under 400 lines of bash, a good share of it comments.
npx tokken-cli install comes from tokken-cli on npm: a small launcher that runs this same install.sh, byte for byte, plus the check below. Nothing in it runs on a schedule; the collector it installs is the same collect.sh.
If you would rather run nothing you haven’t read, download the scripts, read them, and run the installer yourself. It behaves identically:
curl -fsSL tokken.site/install -o install.sh
curl -fsSL tokken.site/collect.sh -o collect.sh
less install.sh collect.sh # read both
TT_TOKEN=<your device token> bash install.shWhat it installs
One directory in your home folder and one scheduled job. No sudo, nothing system-wide, nothing added to your shell profile or PATH.
- Installs to
~/.token-tracker/- Contains
- config.env (your token, mode 600), collect.sh, state.env, collector.log
- Schedules with
- launchd on macOS (co.tokentracker.collector), cron on Linux
- Needs on your machine
- bash, curl, jq, and node — the readers run through npx
The schedule runs collect.sh every few minutes. On macOS a second, one-line launchd job (co.tokentracker.watchdog) checks hourly that the collector is still loaded and reloads it if not; it does nothing else.
collect.sh can replace itself, so that a bug in it can be fixed without asking you to paste anything into a terminal again. It only ever downloads from the same address it already sends to — the server names a version and a checksum, never a URL — and it installs nothing that fails the checksum, fails to parse, or fails a trial run.
Every new version must also be signed. The signing keys live offline, on the maintainer’s own machine and a backup — never on this server, on GitHub or with the hosting provider — and the collector carries the matching public keys. So even someone who took over this website could not push code to your machine: without a signature from one of those keys, the collector refuses the update and keeps the version it has. (The first install is the exception any installer has: it runs the script as you downloaded it — which is why both scripts are one click away above.)
If an installed update then fails to complete a sync three times, the device puts the old one back by itself. Set TT_NO_UPDATE=1 in config.env and it will never replace itself at all.
What it reads
The collector does not parse your AI tools’ logs itself. It runs ccusage, an open-source, widely used CLI, pinned to one exact version and invoked as ccusage daily --json --offline. ccusage reads the usage logs Claude Code already keeps on your disk and produces a per-day, per-model summary of token counts. --offline means ccusage itself makes no network calls; it prices from a bundled rate table.
Codex and Pi are read by a second open-source CLI, tokentracker-cli, also pinned to one exact version, because ccusage counts Codex sessions more than once. It only runs if one of those two tools has left session logs on your machine. We run one command, sync, which reads those tools’ own session logs and writes a summary to a file on your machine. We never run its init, which is what would add hooks to your tools’ configs, and we give it no account and no server address, so it has nothing to upload anything to. Its own usage reporting is switched off.
To be plain about what that means: both are programs from npm that run as you, so like any tool you install they can read what you can, your AI tools’ logs included — reading those logs is how they count tokens. What keeps that in check is that we pin one exact version of each, npm never lets a published version be changed afterwards, and both are open source, so the code that runs is the code anyone can read. A different version only reaches you through a collector update, under the rules above.
The collector keeps only that summary. It never reads a conversation, a file you were editing, or anything about the projects the tokens were spent on.
What it sends
One HTTPS request per run, to tokken.site/api/ingest, carrying a list of rows. Each row has exactly these fields and nothing else:
POST /api/ingest
Authorization: Bearer <your device token>
{
"rows": [
{
"tool": "claude-code",
"date": "2026-08-31",
"model": "claude-sonnet-5",
"input_tokens": 184203,
"output_tokens": 21877,
"cache_creation_tokens": 96410,
"cache_read_tokens": 2310556,
"cost_usd": 4.1273,
"accuracy": "exact"
}
]
}- Token counts per day, per model, per tool
- The dollar cost ccusage computes for those tokens
- Your device token, as a bearer header, so we know which device is reporting
- A health check: collector version, whether the reader worked, and a short error if it didn't — with your username, home folder and project names removed first
- Prompts, responses, or anything you or the model wrote
- Source code, file names, paths, or project names
- Your username, hostname, or environment variables
- Git history, shell history, or anything outside the usage logs
Two things are derived on our side of the request rather than sent. The hosting platform tags each request with the city it came from, which we round to about 11 km and use to place a pin on the map on the homepage; the IP address itself is used in memory for rate limiting and is never written anywhere. And if you told us your city at signup, that is used instead and the request’s location is ignored.
What an update can and can't change
Because the collector updates itself, you are trusting more than today’s script. So here is what we hold ourselves to, and how to hold us to less.
- Token counts only, for every tool. A tool added later sends the same fields shown above and nothing more — never prompts, code or file contents. If that list ever grows, it grows here first: a test fails if the collector and this page disagree.
- New tools can arrive through an update. That is how Codex and Pi support were added. To keep only the tools you have now, put
TT_TOOLS_PINNED=1inconfig.env; the collector then reads exactly theTT_TOOLSlist written there. - Or freeze it completely.
TT_NO_UPDATE=1stops the collector replacing itself. It will then only change if you run the installer again.
The device token
- It only authorises writes. A token can add usage rows for its own device. It cannot read anything back — not your data, not anyone else's.
- We store a hash, not the token. The raw token is shown once when you add a device and is kept only in config.env on that machine. Our database holds its SHA-256.
- Installing through your AI assistant shares it with that tool. The “Let your AI do it” option puts the install command — token included — into a prompt for Claude Code or Codex, so it passes through that assistant like anything else you paste. It can still only add rows for that one device; if that bothers you, use “Do it yourself”, or remove the device and add it again.
- Revoke it in one click. Removing a device on the Devices page deletes the token and every row it ever sent. The collector on that machine starts getting 401s and stops being able to report.
Uninstall
Removing the directory and the schedule is the whole uninstall. Nothing is left behind.
launchctl unload ~/Library/LaunchAgents/co.tokentracker.watchdog.plist
launchctl unload ~/Library/LaunchAgents/co.tokentracker.collector.plist
rm ~/Library/LaunchAgents/co.tokentracker.*.plist
rm -rf ~/.token-trackercrontab -l | grep -v '.token-tracker/collect.sh' | crontab -
rm -rf ~/.token-trackerThen remove the device from your Devices page if you also want its history gone from the dashboard.
The one-off check
/check runs a third script, check.sh, for anyone who wants their own numbers before installing anything — started with npx tokken-cli check. It runs the same two readers at the same pinned versions, through the collector’s own filters, then opens your browser.
- Installs nothing. No directory, no schedule, no token. It runs once and exits.
- Sends nothing. The totals ride after the
#in the link it opens, and browsers never send that part to a server. The page reads them, then wipes them from the address bar before analytics loads. - What the link holds: per day and model — the tool, the model name, token counts and the reported cost. No prompts, code, paths or project names.
- Sharing is the one exception, and only on a click. Share puts the numbers printed on your card — 30-day cost and tokens, your rank, your top model, which tools — into a public link so X and LinkedIn can show the card. Nothing else, and nothing is stored: the card is drawn from the link each time.
Found something?
If you spot a problem in any of these scripts or in how the service handles what they send, write to hello@tokken.site or DM @Abhishek_mg12 on X. What happens to the data once it arrives is covered in the privacy policy.