TokLog
htopfor your LLM spend — proxy-only.
TokLog is a local-first HTTP proxy for LLM spend visibility and control.
Route OpenAI-, Anthropic-, and Gemini-compatible traffic through a local proxy. TokLog logs usage locally, attributes cost by model/provider/program/tag, and turns raw traffic into actionable waste reports.
No hosted backend. No account. No prompt egress by default.
Install
pip install toklog
tl proxy setup
tl proxy start --background
After setup, clients that support base URL overrides can route through TokLog with no app-specific SDK integration.
What it does
- Proxy-based capture — intercepts LLM traffic at the HTTP layer
- Cross-language — works with Python, TypeScript, Go, curl, and anything else that can point at a base URL
- Cross-provider — OpenAI, Anthropic, Gemini
- Local logs — normalized JSONL logs under
~/.toklog/logs/ - Spend reports — model, provider, endpoint, program, and tag breakdowns
- Waste detection — highlights expensive patterns worth fixing first
- Shareable output — terminal and exported reports
Core commands
tl report
Full spend breakdown — models, processes, context composition, waste detectors.
tl report # last 7 days
tl report --last 30d
tl gain
Cumulative savings opportunities — shows how much waste each detector has found since install.
tl gain
tl doctor
Health check — verifies config, proxy, env vars, logging, and traffic.
tl doctor
tl share
Generate a self-contained HTML report you can share — no server needed.
tl share # save to ~/.toklog/reports/
tl share --open # save and open in browser
tl proxy status
Check if the proxy daemon is running and where it's listening.
tl proxy status
Other commands
tl proxy setup # interactive setup wizard
tl proxy start --background
tl proxy stop
tl tail # live stream of logged calls
tl categories # list detected call categories
tl pricing # show model pricing table
tl reset # clear all logs and config
Budget Kill Switch
Set a daily spend limit. When the budget is exceeded, the proxy returns HTTP 429 immediately — no upstream request is made.
Enable it
CLI flag (takes precedence over config):
tl proxy start --budget 10.00
Or set it in ~/.toklog/config.json:
{
"proxy": {
"budget_usd": 10.00
}
}
What happens at the limit
Requests get a 429 Too Many Requests response with a JSON error body:
{
"error": {
"message": "Daily budget of $10.00 exceeded",
"type": "budget_exceeded"
}
}
No tokens are consumed. No upstream contact is made.
Monitoring
tl proxy status # shows current spend vs budget limit
tl report # includes budget bar and rejection warnings
Behavior notes
- Resets at midnight local time
- No budget configured = no enforcement (fully backward compatible)
- GET requests (e.g.
/v1/models) are never blocked
License
TBFUL-1.0 — free for non-commercial and small-scale use. Commercial license required above $10k annual LLM spend.
Metadata
Release files for toklog 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| toklog-0.3.1.tar.gz | 151.8 kB | Without provenance | Details for toklog-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| toklog-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for toklog-0.3.1-py3-none-any.whl |
Total release size: 326.0 kB
Release files / toklog-0.3.1.tar.gz
| Download URL | toklog-0.3.1.tar.gz |
|---|---|
| Size | 151.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b1d66ac02e719a39f1b71240388d41d697a985c9650a55b6448ab22a5b6d75c1
|
|
BLAKE2b-256 checksum How to use checksums |
349cfcc22adb9ba388153accd4fd582d4a572bf4dbb9ab974006fa1ba94b5b45
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / toklog-0.3.1-py3-none-any.whl
| Download URL | toklog-0.3.1-py3-none-any.whl |
|---|---|
| Size | 174.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6887df03ea378ca6a9211da38dab4b569f1b4c874d458297747b881783c194a7
|
|
BLAKE2b-256 checksum How to use checksums |
da5d78fd754131d7405779af8f072f037db9180690a3f7c80a791018982b57f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for toklog 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.