Context bloat
Reading one big log file quietly fills most of the context window.
0%local. Your prompts never leave your machine.
0typed REST endpoints, with Python and TypeScript SDKs.
0+agents read automatically. Any other agent: one API call.
0sfrom npx to your first dashboard.
Works with every agent
One dashboard. Every agent.
Four agents are read automatically from the logs they already keep. Anything else (Antigravity, Cursor, Copilot CLI, the agent you built) pushes one JSON record per request. Same charts, same debugger, side by side.
- Claude Codeauto
- Codex CLIauto
- Gemini CLIauto
- OpenCodeauto
- AntigravityAPI
- CursorAPI
- Your own agentAPI
Claude Code
~/.claude/projectsTranscripts + live hooksCodex CLI
~/.codex/sessionsPer-response usage recordsGemini CLI
~/.gemini/tmp/*/chatsChat logs, last write winsOpenCode
~/.local/share/opencodeIts SQLite db, read-onlyAny other agent
POST /api/v1/ingestAntigravity, Cursor, Copilot CLI, CI jobs, your own agentAntigravity encrypts its local conversations and doesn’t expose token usage, so it’s tracked by pushing usage, for example from headless runs. Token share above is sample data.
Demo
See it in action.
A real 287,000-token request, traced back to the log file that caused it. Then a quick tour of everything else, from install to API.
The problem
Building with LLMs, you’re flying blind.
Tokens are your budget, your latency and your context window. Every coding agent records them, then shows you almost none.
Mystery spikes
A session got slow and expensive. Which request did it?
Scattered usage
Usage is split across sessions, projects, models and IDEs.
Tool sprawl
Which MCP servers, skills and tools earn their keep? No idea.
Wrong totals
Naive transcript parsers count a request once per content block.
No feedback loop
You rewrote the prompt or CLAUDE.md. Did it actually help?
Numbers in these illustrations are examples, except the 2.5× over-count, which we measured on real Claude Code transcripts.
Interactive demo
Take it for a spin. Right here.
This is the real dashboard layout with sample data. Watch the guided tour, or click anything to take over.
Every request, every project, all time. Live as you work.
How it helps you debug
Debug any prompt in four steps.
Your agent shows you the answer. Know Your Tokens shows you the question: exactly what was sent, what each part cost, and whether your fix worked.
Requests · checkout-servicetokens per request
Example request · illustrative numbers
Evaluate
Score every prompt. Compare every project.
Sort requests by size, see what was cached, and watch each project’s tokens per request over time, so you know which prompts, habits and changes are worth keeping.
Prompt scorecardtokens per request (K)
- Fix the flaky checkout test24K94% cachedLean
- Add a loading skeleton to the cart41K91% cachedLean
- Explain this Terraform plan88K72% cachedHeavy
- Why does checkout fail with a gift card?312K41% cachedBloated
Cache hit rateinput tokens served from cache
0%
Cached tokens are cheaper and faster. Low rates flag prompts that break the cache.
Per projecttokens per request · 30 days
- checkout-service−38%
- web-app−9%
- infra+21%
0token types per request: input, output, cache read, cache write
0+ways to slice it: project, session, model, IDE, tool, skill, MCP…
0click from a spike to the full prompt behind it
Sample data.
Token calculator
How many tokens is that? Find out before you send it.
Paste a prompt, a file or a log. Everything runs in your browser. The app has the same calculator, plus your real usage priced at your own rates.
≈ 47tokens (prose)
- Characters
- 173
- Words
- 29
- Lines
- 4
Estimate (±15%). Inside the app, every count your agents record is exact.
Context window
System + toolsHistoryYour textOutput
23.5% of the window · plenty of room
Your rates, $ per million tokens
Type your provider’s rates to see a cost. We don’t ship prices: they depend on your plan.
Made for everyone who codes with AI agents
Better prompts start with seeing them.
Debugging prompts
From “why is this so slow?” to the exact cause in three clicks.
Your agent shows you the answer. Know Your Tokens shows you the question: the full context that was sent, what each part cost, and which tool result made it explode. Fix the pattern once and every future session gets cheaper and sharper.
Before312Ktokens · 41% cached
cat logs/checkout.logAfter24Ktokens · 93% cached
tail -n 200 logs/checkout.log | grep -i giftDevelopers
Stop guessing why a session got slow and expensive.
- Spot the prompt that blew the context
- See which files your agent keeps re-reading
- Learn what makes prompts cheap
Team leads
Usage you can actually reason about.
- Per project, per model, per client
- Exports for budgets and reviews
- OTLP into the dashboards you run
Platform & security
Observability without a data-sharing review.
- Runs on 127.0.0.1 only
- No telemetry of its own
- Retention and redaction built in
Tool & MCP builders
Know how your tools behave in the wild.
- Call counts per MCP server and tool
- Skills and plugins by trigger
- Typed API and SDKs for your own reports
Lives where your apps live
One click from your Dock. Or taskbar. Or launcher.
Install the dashboard as an app straight from the browser (“Install app” in the top bar), or let the CLI create a native launcher with its own icon.
$ knowyourtokens shortcut --dockCreates “Know Your Tokens.app” in ~/Applications and adds it to your Dock.
Get started
Sixty seconds. Three steps.
1
Install
$ npx knowyourtokensFinds your agents, sets up a private Python env (offering to install uv if it’s missing) and starts everything. Needs Node 18+.
2
Pin it
$ knowyourtokens shortcutAdds an app icon for your Dock, taskbar or launcher. Or click “Install app” in the dashboard.
3
Use any agent
$ claudeNothing changes in your workflow. The dashboard fills in live as you work, and history is backfilled.
npx knowyourtokensInstallation guide
Everything you need. Nothing you don’t.
Prerequisites
Node.js 18 or newerRequired
Runs the installer and the dashboard. Check with node --version. Get it from nodejs.org.
uv (or Python 3.10+)Installed for you
The backend is Python. If uv is missing, the installer explains why it needs it and asks before installing it. uv then downloads its own Python, so you don’t need one.
An AI coding agentAny of them
Claude Code, Codex CLI, Gemini CLI or OpenCode. Others can post usage to the ingest API.
~300 MB of diskOne time
For the private Python environment. Your usage data stays small (SQLite).
Install, step by step
- Install Node 18+ (if you don’t have it)
brew install node - Run the installer and answer “Y” when it offers uv
npx knowyourtokens - Optional: start at login, add a Dock icon
npx knowyourtokens autostart enable && npx knowyourtokens shortcut
The installer finds your agents, creates a private Python environment, installs hooks and starts the dashboard at http://localhost:5173. Re-running it is always safe.
npx knowyourtokens --yes- No questions: installs uv automatically if needed (for scripts and CI).
npx knowyourtokens --no-uv- Never install uv; use the Python 3.10+ already on your PATH.
npx knowyourtokens doctor- Checks every prerequisite, port, hook and service and tells you how to fix each one.
npx knowyourtokens@latest- Upgrade. Your data is kept, and old installs (~/.tokentelemetry) move to ~/.knowyourtokens on their own.
Troubleshooting
Start with diagnostics
Almost every problem shows up here, with the exact fix printed next to it.
Logs live in ~/.knowyourtokens/logs (backend.log, daemon.log, frontend.log). Set KNOWYOURTOKENS_DEBUG=1 to print full stack traces.
npx knowyourtokens doctor
“uv is not installed” or the uv download fails
Re-run and answer Y, or run the official installer yourself, then open a new terminal.
Behind a proxy, set HTTPS_PROXY first. Alternatives: winget install astral-sh.uv (Windows), brew install uv (macOS), pipx install uv. Or skip uv with --no-uv if you have Python 3.10+.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux
Windows: the backend never connects, or “access forbidden” (WinError 10013)
Hyper-V, WSL or Docker often reserve port ranges that include 8000. Know Your Tokens now picks the next free port automatically and remembers it; you can also choose one.
The first start on Windows can take a minute while Python compiles. If it still times out, allow Python through Windows Defender Firewall for private networks, and exclude ~/.knowyourtokens from real-time antivirus scanning.
netsh interface ipv4 show excludedportrange protocol=tcp $env:KNOWYOURTOKENS_BACKEND_PORT=8123; npx knowyourtokens start
Port already in use (EADDRINUSE)
Another program holds the port. Stop the old copy first; if the port belongs to something else, Know Your Tokens moves to a free one, or pin your own with KNOWYOURTOKENS_BACKEND_PORT / KNOWYOURTOKENS_DASHBOARD_PORT.
npx knowyourtokens stop && npx knowyourtokens start
Dashboard says “Can’t reach the backend”
Check status, then restart. A VPN or corporate proxy can intercept 127.0.0.1: add localhost and 127.0.0.1 to NO_PROXY.
npx knowyourtokens status npx knowyourtokens start
“Python 3.10+ not found”
Only when you used --no-uv. Install Python 3.10+ (python.org, or winget install Python.Python.3.12), or drop --no-uv so uv provides Python.
Permission denied (EACCES / EPERM)
Don’t run with sudo or as Administrator. On Windows, close terminals and editors holding files in ~/.knowyourtokens, pause antivirus or OneDrive sync for that folder, and try again.
No data shows up
Run your agent once after installing, then refresh. doctor shows whether hooks are installed; re-running the installer re-adds them. Existing history is backfilled automatically.
npx knowyourtokens doctor npx knowyourtokens install
Uninstall
Removes hooks, services, autostart and the app. Your data is kept unless you add --delete-data.
npx knowyourtokens uninstall --purge
Still stuck? Read the full troubleshooting guide or open an issue with the output of doctor.
How it works
Two capture paths, one local database
Hooks record events the instant they happen. A small daemon reads new transcript lines for exact usage and full text, and catches up on anything missed while it was off.
- Your agents write session logs, or push to the ingest API
- Both land in a local SQLite database
- A REST API on 127.0.0.1 serves the dashboard and SDKs
- Optional: OTLP metrics and webhooks to your own stack
01
Install
npx knowyourtokens sets up a Python env, finds Claude Code, Codex, Gemini CLI and OpenCode, and starts everything.
02
Use any agent
Nothing changes in your workflow. Logs are read, never written; anything else can push one JSON record per request.
03
Look, query, export
Open the dashboard, call the API, or stream metrics to the observability stack you already run.
Integrations
Plug every agent’s usage into anything
The dashboard is one client among many. Build cost reports, team rollups, Slack bots, or Grafana panels on the same API.
# Totals for June, in your local time zone
curl "http://127.0.0.1:8000/api/v1/usage/summary?start=2025-06-01&end=2025-06-30"
# Every request for one project, newest first (paginated)
curl "http://127.0.0.1:8000/api/v1/usage?project=my-repo&page_size=100"
# Stream everything as NDJSON
curl "http://127.0.0.1:8000/api/v1/reports/export?format=ndjson" > usage.ndjson
# Machine-readable contract
curl http://127.0.0.1:8000/openapi.json25 typed endpoints with a published OpenAPI document. Interactive docs at /docs while the backend runs.
Privacy & security
Your prompts are yours.
Know Your Tokens runs entirely on your computer. It sends nothing about itself to anyone. The only way data leaves is through an exporter you configure.
- 127.0.0.1 only. The API and dashboard never listen on your network.
- DNS-rebinding & CSRF protection. Host allowlist and Origin checks on every request and WebSocket.
- Least data. Tool output is never stored from hooks; likely API keys and tokens are redacted.
- You decide what is kept. Turn off full-text storage, or set retention for rows and text separately.
- Private file. The SQLite database is created readable only by you (0600).
# Keep 90 days of rows, 14 days of full text
export KNOWYOURTOKENS_RETENTION_DAYS=90
export KNOWYOURTOKENS_FULL_TEXT_RETENTION_DAYS=14
# Never store prompt/response text at all
export KNOWYOURTOKENS_STORE_FULL_TEXT=0
# Everything, gone
knowyourtokens uninstall --purge --delete-dataTech specs
- Captures
- Requests, tokens (input, output, cache read/write), sessions, projects, models, clients, tools, MCP servers, skills, plugins, subagents, hook events
- Accuracy
- Exact per-request usage from each agent’s own logs (Claude Code, Codex CLI, Gemini CLI, OpenCode) or the ingest API, de-duplicated per request. Attribution is estimated and always labelled
- Storage
- Local SQLite (WAL), versioned schema with automatic backed-up migrations, optional retention, 0600 permissions
- Interfaces
- Dashboard (installable app) · REST API with OpenAPI · Python & TypeScript SDKs · CSV/JSON/NDJSON export
- Integrations
- OpenTelemetry metrics (OTLP/HTTP) · HMAC-signed webhooks · all opt-in
- Security
- 127.0.0.1 only · DNS-rebinding and CSRF protection · strict CSP · secret redaction · no outbound calls by default
- Platforms
- Windows, macOS, Linux · Node 18+ · Python via uv (installed for you) or Python 3.10+ · start at login · app shortcuts
- License
- Apache 2.0: free for personal and commercial use, with credit
FAQ
Questions, answered
Yes. Apache 2.0 licensed: use it, fork it, embed it, ship it commercially. If you redistribute it or build on it, keep the NOTICE file that credits its creator, Sarvesh Talele. Contributions are welcome.
Know your tokens in 60 seconds.
One command installs the backend, the dashboard and the hooks. Undo it just as easily.