TokenKlaw

Save tokens across AI coding agents.

TokenKlaw is a local-first token-saving layer between your coding agent and model provider. It cuts repeated context, duplicate logs, and redundant prompts before they burn budget.

Created by Paul Hartmann (@janpaul80)
Website: token.klaw.at

One-command install

macOS / Linux / WSL

curl -fsSL https://token.klaw.at/install.sh | bash

GitHub raw fallback:

curl -fsSL https://raw.githubusercontent.com/janpaul80/tokenklaw/main/install.sh | bash

Windows PowerShell

irm https://token.klaw.at/install.ps1 | iex

GitHub raw fallback:

irm https://raw.githubusercontent.com/janpaul80/tokenklaw/main/install.ps1 | iex

Runtime example:

curl -fsSL https://raw.githubusercontent.com/janpaul80/tokenklaw/main/install.sh | bash -s -- --runtime claude

See full installer docs: docs/ONE_LINE_INSTALL.md

Works with: Claude Code, Codex CLI, Roo Code, Cursor, Cline, Continue, Gemini / Antigravity, OpenClaw, Hermes, and future adapters.

Navigation

Claude Code Integration Now Working • Overview • Quick Start (Activation) • Install • Benchmarks • Platforms • CLI Examples • Roadmap

Claude Code Integration Now Working

TokenKlaw is now validated as a real plugin-style runtime integration inside Claude Code.

Confirmed:

/tokenklaw is recognized
/tk is recognized
plugin-style install architecture is working
TokenKlaw activation mode runs inside Claude Code with clean activation behavior

Activation behavior (clean final output style):

TokenKlaw active.

Install flow:

tokenklaw install claude

Generated Claude plugin structure:

~/.claude/.claude-plugin/plugin.json
~/.claude/.claude-plugin/marketplace.json
~/.claude/commands/tokenklaw.toml
~/.claude/commands/tk.toml
~/.claude/skills/tokenklaw/SKILL.md
~/.claude/hooks/tokenklaw.pre-response.md
~/.claude/CLAUDE.md
~/.claude/tokenklaw/*

Proof media placeholders (to be replaced with real assets)

docs/media/claude-command-recognition.png (Claude recognizes /tokenklaw)
docs/media/claude-activation-response.png (clean activation response)
docs/media/claude-install-flow.gif (install + activate walkthrough)
docs/media/claude-plugin-tree.png (generated plugin structure)

Product architecture direction

TokenKlaw is evolving into:

universal runtime installer
plugin activation layer
token optimization runtime
context compression system
multi-agent activation framework

Overview

TokenKlaw sits in the request path:

Agent -> TokenKlaw -> Fingerprint + Context Reduction + Cache -> Provider

What it does in practice:

fingerprints requests to detect repeats
strips noisy or duplicated context
caches deterministic results
tracks usage and savings

Before / After

1) React rerender debugging

Without TokenKlaw

Sure! Let me explain your React issue in detail. The component re-renders on every state
change because you're creating a new inline object reference each render. React compares by
reference, so this object is always "different". Consider useMemo, stable callbacks, and
prop drilling analysis...
[1,280 tokens]

With TokenKlaw

Rerender is caused by a new inline object ref each render.
Fix: memoize the object with useMemo and pass stable props.
[312 tokens]

Saved: 75%

2) Auth middleware bug summary

Without TokenKlaw

Your middleware checks auth headers in multiple branches and logs full request objects.
Here is a full breakdown of each branch, response mode, and error path...
[2,050 tokens]

With TokenKlaw

Duplicate auth checks in middleware.
Consolidate to one guard, avoid full request logging, short-circuit on missing token.
[640 tokens]

Saved: 69%

3) Repeated repo analysis (same question, second run)

Without TokenKlaw

Full architecture walkthrough regenerated from scratch.
[12,000 tokens]

With TokenKlaw

Cache hit: previous response reused.
[0 provider tokens]

Saved: up to 100% on repeat calls

Token chart (example repeated-context workflow)

Before           ████████████████████ 12,000
After TokenKlaw  ██████                3,480
Saved            71%

Quick start (activation-first)

Install TokenKlaw locally.
Install into your agent:

tokenklaw install claude
# or: tokenklaw install codex|roo|cline|continue|gemini|all

Inside your agent chat, activate token-saving mode:

/tokenklaw
# alias:
/tk

Expected activation response:

TokenKlaw active.
Context reduction: on
Duplicate detection: on
Cache guidance: on
Verbose replies: reduced
Token-saving mode: enabled

To disable or inspect mode:

/tokenklaw off
/tokenklaw stats

Install

Requirements

Recommended Node.js: 20 LTS or 22 LTS
pnpm via corepack
On Windows, native modules may require Visual Studio Build Tools

Note: Node 24 can fail on Windows when building better-sqlite3 from source.

From source (PowerShell)

git clone https://github.com/janpaul80/tokenklaw.git
cd tokenklaw
corepack enable
corepack prepare pnpm@latest --activate
pnpm install
pnpm build
pnpm doctor

From source (WSL / Linux / macOS)

git clone https://github.com/janpaul80/tokenklaw.git
cd tokenklaw
corepack enable
corepack prepare pnpm@latest --activate
pnpm install
pnpm build
pnpm doctor

npm (coming soon)

npm install -g tokenklaw

Benchmarks

Example repeated-context scenarios (illustrative, workflow-dependent):

Task	Without	With TokenKlaw	Saved
Repeated repo analysis	12,000	3,480	71%
Duplicate logs in debug flow	8,500	4,200	50%
Repeated stack trace explanation	5,200	2,100	60%
Cache hit on exact repeat	6,000	0 provider tokens	up to 100%

Platform support

Current runtime support

Platform	Status
Claude Code	working (plugin‑style integration validated)
Codex CLI	experimental
Roo Code	experimental
Cursor	experimental
Cline	experimental
Continue	experimental
Gemini / Antigravity	experimental
OpenClaw	experimental
Hermes	experimental

Future scaffold

Platform	Status
Windsurf	scaffold
OpenDevin	scaffold
Aider	scaffold
Opencode	scaffold

CLI examples

Run

tokenklaw run "explain this repo architecture"

provider: anthropic
fingerprint: 4e4f2f6a...
cache: miss
input_tokens: 2381
output_tokens: 1099
estimated_cost_usd: 0.0214
saved_tokens_estimate: 0

Run again (same request)

tokenklaw run "explain this repo architecture"

provider: anthropic
fingerprint: 4e4f2f6a...
cache: hit
input_tokens: 0 provider tokens
output_tokens: cached
estimated_cost_usd: 0.0000
saved_tokens_estimate: 2381

Stats

tokenklaw stats

requests_total: 147
cache_hit_rate: 42.2%
input_tokens_baseline: 418,220
input_tokens_actual: 161,570
estimated_tokens_saved: 256,650
estimated_reduction: 61.4%

Inspect

tokenklaw inspect --limit 5

#   ts                  provider   cache   input   output   saved
1   2025-07-16T10:41Z   openai     hit     0       cached   1810
2   2025-07-16T10:39Z   openai     miss    1810    420      0
3   2025-07-16T10:31Z   anthropic  hit     0       cached   2381
4   2025-07-16T10:28Z   anthropic  miss    2381    1099     0
5   2025-07-16T10:22Z   openai     miss    1220    360      0

Screenshots

Description	Image
Claude dropdown with full TokenKlaw command suite
`/tokenklaw` activation response
`/tokenklaw-help` command list
One‑command install (`tokenklaw install claude`)
Full activation workflow (install → activate → dropdown)

┌──────────────┐
│ AI Agent     │
└──────┬───────┘
       │ request
       v
┌──────────────┐
│ TokenKlaw    │
│ - fingerprint│
│ - reduction  │
│ - cache      │
└──────┬───────┘
       │ optimized request
       v
┌──────────────┐
│ Provider API │
│ OpenAI / etc │
└──────────────┘

Troubleshooting install issues

If pnpm install fails on better-sqlite3:

Use Node 20 LTS or Node 22 LTS
Install Visual Studio Build Tools with Desktop development with C++
Retry pnpm install
If Windows native build still fails, try running in WSL/Linux

Roadmap

ship stable CLI command surface (run, stats, inspect)
expand provider adapters beyond skeleton implementations
publish npm package
add adapter-specific benchmark harness
harden cache invalidation + policy controls

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
.claude		.claude
.tokenklaw		.tokenklaw
apps		apps
docs		docs
packages		packages
tmp		tmp
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
README.md		README.md
TODO.md		TODO.md
install.ps1		install.ps1
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

TokenKlaw

One-command install

macOS / Linux / WSL

Windows PowerShell

Navigation

Claude Code Integration Now Working

Proof media placeholders (to be replaced with real assets)

Product architecture direction

Overview

Before / After

1) React rerender debugging

2) Auth middleware bug summary

3) Repeated repo analysis (same question, second run)

Token chart (example repeated-context workflow)

Quick start (activation-first)

Install

Requirements

From source (PowerShell)

From source (WSL / Linux / macOS)

npm (coming soon)

Benchmarks

Platform support

Current runtime support

Future scaffold

CLI examples

Run

Run again (same request)

Stats

Inspect

Screenshots

Troubleshooting install issues

Roadmap

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages