Skip to content

Privacy-first token analyzer for AI agent setups

Know exactly what your agents are eating.

Tolkin measures the standing context of your AI setup: MCP servers, instruction files, skills, cache health. Deterministic numbers, zero network egress, receipts for every claim.

brew install agnelnieves/tolkin/tolkin
Open the analyzerGitHub
tolkin
$ tolkin project --json | jq .totals
{
  "files_scanned": 593,
  "context_files": 22,
  "context_tokens": 44174,
  "savings_min": 774,
  "savings_max": 2201
}
593 files measured. nothing left this machine.
0.97522measured cache hit rate, on real session logs
$8.19won by the 1h TTL strategy in counterfactual replay
169sessions reconciled token-for-token
22MCP servers in the catalog, plus exact probe for yours

Features

Everything is measured.

Eight commands, one posture: deterministic output, honest labels, and nothing invented. The same Rust core runs in the CLI, the web analyzer, and the GitHub Action.

scan

Finds every agent config on the machine: a dozen clients, instruction files, hooks, workflow LLM detectors.

project

Gitignore-aware repo context audit by load profile, with --fail-on for CI.

audit

13 rules, 6 production-proven and 7 experimental. Lighthouse-style findings with severity and citations.

mcp

Cold, warm, and Tool-Search scenarios, with slim and swap recommendations per server.

cache

Measured hit rate, write churn, and a 5m vs 1h TTL counterfactual replayed on your own logs.

stats

A local, consented ledger of savings over time. Three honesty tiers, never blended.

report

A self-contained HTML savings report you can hand to anyone, tier labels included.

redact

Always-on secret redaction before anything else sees a byte.

Honesty tiers

Numbers that admit what they are.

Every figure Tolkin prints belongs to exactly one tier, and the tier is always printed next to it. No blending, no rounding up the confidence.

01

identified

"advisory estimate"

What audit, mcp, and project flag as reclaimable right now. An estimate, and labeled as one.

02

realized

"measured structure, estimated frequency"

The measured delta between ledger snapshots of the same project. Structural evidence of what you actually removed.

03

measured

"ground truth"

Actual spend from your own ingested session logs. Reconciled token-for-token before it is reported.

Model output is a fourth class, "model advisory (local)", and it never joins the tiers.

Local intelligence

A local model, when you want one. Never required.

tolkin optimize runs deterministically on its own. If a local OpenAI-compatible server is already running (mlx-lm, Ollama, LM Studio, llama-server) and you consent, it adds plain-language narration and skill lint on top. Nothing leaves the machine.

The model proposes, Rust verifies. Every model claim has to pass verification gates before it reaches your terminal; anything that fails is dropped and counted, not printed.

  • every digit in model output must exist in the deterministic input
  • every quoted span must exist verbatim in the source file
  • loopback only: 127.0.0.1 is enforced in code
  • output is labeled "model advisory (local)", never a tier

When no model is installed, optimize does not dead-end. It detects the machine's RAM and chip, recommends the blessed model for that tier with the download size and a per-machine time estimate, and asks one question before showing the setup guide.

tolkin optimize
$ tolkin optimize

  context files        22
  context tokens       44,174
  identified savings   774 to 2,201 tokens (advisory estimate)

No local model detected (checked 127.0.0.1 ports 8080, 11434, 1234).
The deterministic report above is complete without one.

Suggested model for this machine: mlx-community/Qwen3.5-4B-4bit (3.0 GB download)

Would you like to see how to install and set it up? [y/N]
setup, Apple silicon
brew install uv
uv tool install mlx-lm
mlx_lm.server --model mlx-community/Qwen3.5-4B-4bit --max-tokens 1200
tolkin optimize

Blessed models by machine

8GB
Qwen3.5-0.8B
16GB
Qwen3.5-4B
32GB
Qwen3.5-9B
48GB+
Qwen3.5-35B-A3B MoE

measured near 250 tok/s prefill on an M1 Max; estimates printed before any run

MCP exactness

Unknown MCP servers become measured, not guessed.

The catalog covers 22 known servers. For the internal one only your team runs, --probe speaks the real MCP handshake (initialize, then tools/list) to a server your own config already names, tokenizes the returned manifest, and caches it.

Probe once, commit .tolkin/mcp-manifests, and the whole team reports exact numbers. The cached manifest is date-stamped, secret-redacted, and flagged when it goes stale.

tolkin mcp --probe
$ tolkin mcp mcp.json --probe internal-docs --yes

probing internal-docs over the standard MCP handshake
manifest captured, redacted, cached at .tolkin/mcp-manifests/internal-docs.json

basis: measured (probed manifest, captured 2026-06-11) (exact; supersedes the catalog estimate)

Claimed vs measured

We measure vendor claims too.

Compression claims are often measured under different conditions than yours, and the conditions are rarely published. Tolkin runs the tools on a declared corpus, publishes the conditions, and reports what came out.

ToolClaimedMeasured
cavememabout 75% for prose11.72%
repomix --compressabout 70%45.47%
The full benchmark, methodology and all

declared fixtures, vendored licenses, reproducible runs

Privacy

Zero egress is the default, not a setting.

Three classes of network traffic exist, each user-controlled and documented down to the implementing source file. Everything else: no network calls, ever.

1

byok verify

Opt-in token verification: one endpoint, your key, your flag. Never runs on its own.

2

update check

One GET to the npm registry, either explicit (tolkin update) or consented at onboarding.

3

mcp probe

Speaks only to servers your own config already names. Per-server confirmation, refused in CI.

Kill switches

  • TOLKIN_NO_SIDECAR
  • TOLKIN_NO_UPDATE_CHECK
  • TOLKIN_NO_LEDGER
  • CI

The full posture, with every claim cross-referenced to the source file that implements it, lives in PRIVACY.md.

Distribution

Wherever your agents live.

brew install agnelnieves/tolkin/tolkin
npm install -g @tolkin/cli
bunx tolkin
GitHub Action
Delta gates and sticky PR comments: every pull request that touches agent context gets a before and after table.
Agent skills
Four skills (audit, slim, optimize, cache) for Claude Code, Cursor, Windsurf, Codex, and any client that reads SKILL.md.
Claude Code plugin
One marketplace install namespaces all four skills under /tolkin.
tolkin update
Knows your install channel: Homebrew users see brew upgrade, npm users see npm update.