tkr

Token-optimized CLI proxy for LLM development workflows.

tkr filters and compresses command output before it reaches an LLM context window. It cuts 60–90% of tokens off common dev operations (build, test, git, package managers) so your AI assistant spends its context on signal, not noise.

New: agent mesh + on-chain payments

tkr now ships a peer-messaging mesh for agents and a payment layer that lets agents pay each other on Base (Ethereum L2). Public broker live at tkr.prysm.sh.

# 1. mint an invite (owner key signs it)
tkr mesh invite-mint --slug demo \
  --broker-url wss://tkr.prysm.sh/api/v1/mesh/ws \
  --owner-key-file ~/.tkr/owner.env

# 2. share the URL — anyone runs:
tkr mesh join <invite-url>

# 3. send / receive E2E-encrypted DMs
tkr mesh tail demo                  # listen
tkr mesh send demo --to <addr> --recipient-pubkey <pub> 'hello'

Identity is a secp256k1 keypair (same shape as an Ethereum wallet) — your mesh address and your on-chain wallet address are the same string. DMs are end-to-end encrypted (ECDH + AES-256-GCM); the broker only sees ciphertext.

Payments (Phase 3)

MeshEscrow.sol runs payment channels: payer opens, recipient claims with EIP-712 receipts, payer reclaims unspent funds after a deadline. Source: contracts/src/MeshEscrow.sol (17 forge tests, all green).

tkr pay receipt-issue --session-id 0x... --cumulative N \
  --chain-id 8453 --contract <MeshEscrow-addr> --key-file ~/.tkr/key.env
tkr pay claim --receipt receipt.json \
  --rpc-url https://mainnet.base.org --key-file ~/.tkr/key.env

The off-chain Rust digest (Receipt::issue) and the on-chain Solidity digest (MeshEscrow.receiptDigest()) match byte-for-byte — same EIP-712 domain, same signature, same ECDSA recovery. Verified end-to-end on a Base-mainnet anvil fork.

Crates: tkr-mesh (client), tkr-server (broker + dashboard), contracts/ (Solidity + foundry).

What's different

• Plugin contract v2 — structured plugin lifecycle (on_load, on_command_begin, on_line, on_command_end), typed capability grants, and vault-backed storage. See docs/superpowers/specs/2026-04-28-tkr-plugin-contract-v2-design.md for the full spec.
• Encrypted vault — all plugin state lives in ~/.tkr/vault/ encrypted with age (XChaCha20-Poly1305); master key in ~/.tkr/vault/.tkr-vault.key (0600), with one-time migration from legacy OS-keychain installs. Manage with tkr vault {status,init,unseal,seal,rotate,export,import,audit}.
• Plugin architecture — core is thin; filters and analytics are independent plugins on a shared bus (cli.invoke routes to plugins that declare CLI subcommands).
• Noise analytics & suggestions — tkr gain, tkr suggest, and tkr watch read vault-backed analytics. Optional embeddings (cargo build --features embeddings) improves clustering for repeated noisy lines during tkr suggest; without it, ranking uses signatures only.
• Live dashboard — tkr watch opens a ratatui TUI showing real-time token savings
• Hooks — tkr hook claude for Claude Code Bash hooks; tkr hook universal for the same JSON reply shape plus a top-level "command" field for other wrappers.
• Apache-2.0 licensed — no telemetry, no upstream

Install

Homebrew (macOS / Linux)

brew tap einyx/tkr
brew install tkr

Curl-to-bash

curl -fsSL https://raw.githubusercontent.com/einyx/tkr/main/install.sh | bash

Windows (x86_64)

Download tkr-x86_64-pc-windows-msvc.tar.gz from Releases. Extract tkr.exe using Git Bash, Windows 11 tar, or another tar you already use; add that directory to PATH, then run tkr from PowerShell or CMD. After a manual install, tkr update pulls the matching tkr-<rust-target-triple>.tar.gz asset from GitHub Releases.

From source

Requires Rust 1.88+ (see rust-toolchain.toml). Install rustup, then rustup toolchain install 1.88.0 (or rely on rust-toolchain.toml once rustup’s cargo is on PATH).

macOS: Homebrew hides rustup

Homebrew puts /opt/homebrew/bin first. Brew’s cargo does not read rust-toolchain.toml — you stay on an older rustc even inside this repo.

1. Put rustup before Homebrew in PATH. In ~/.zshrc, after brew shellenv, add:

   export PATH="$HOME/.cargo/bin:$PATH"
   

2. Reload the shell (new terminal or exec zsh), then check:

   command -v cargo
   

   You want $HOME/.cargo/bin/cargo, not /opt/homebrew/bin/cargo.

3. Optional: brew unlink rust (or brew uninstall rust) if you installed Rust via Homebrew and no longer need it.

4. Without touching PATH, build from this repo with:

   ./scripts/rustup-cargo build --release
   

Then clone and build (use ./scripts/rustup-cargo instead of cargo if command -v cargo still shows Homebrew):

git clone https://github.com/einyx/tkr
cd tkr
cargo build --release

Install into ~/.cargo/bin from the repo root (--locked uses the workspace Cargo.lock).

If cargo --version works but rustc --version is still 1.87, you are on Homebrew’s cargo — cargo install … will always fail MSRV. Use either:

make install

or:

./scripts/install-tkr

Both invoke ~/.cargo/bin/cargo directly (same as ./scripts/rustup-cargo install --path crates/tkr --locked --force).

Once PATH prefers ~/.cargo/bin, plain cargo is fine:

cargo install --path crates/tkr --locked --force

On Unix, install from target/release/tkr (for example cp target/release/tkr ~/.local/bin/). On Windows (host triple MSVC), use target\release\tkr.exe. If you pass --target <triple>, the binary is under target/<triple>/release/ (with .exe for Windows targets).

Usage

tkr --help                   # all subcommands (incl. vault, admin)
tkr <command> [args...]      # proxy any command
tkr git status               # filtered git output
tkr cargo test               # only failures
tkr watch                    # live dashboard (run in a split pane)
tkr gain                     # token savings summary
tkr gain --breakdown         # per-command breakdown
tkr discover                 # find commands you ran without tkr
tkr vault status             # encrypted vault; plain `tkr vault` = status
tkr admin reset --plugin <name>
tkr hook universal           # stdin JSON hook (see Hooks below)

Configuration

~/.tkr/config.toml (auto-created with sensible defaults on first use):

[core]
plugin_dir  = "~/.tkr/plugins"
socket_path = "~/.tkr/session.sock"
filter_dir  = "~/.tkr/filters"

[plugins]
chain = ["tkr-filter"]

[plugins.analytics]
db_path = "~/.tkr/analytics.db"

Built-in defaults match the above (tkr-filter only). If ~/.tkr/analytics.db still exists from an older release, it is migrated once into ~/.tkr/vault/ and renamed to analytics.db.migrated.

Custom Filters

Drop a TOML filter file in ~/.tkr/filters/:

command = "mytool"

[[rules]]
type   = "suppress_regex"
pattern = "^DEBUG: "

[[rules]]
type    = "suppress_prefix"
prefix  = "info:"

[[rules]]
type    = "keep_regex"
pattern = "^(error|warning):"

Three rule types: suppress_prefix, suppress_regex, keep_regex (drops anything not matching).

Hooks

On success both emit the same hookSpecificOutput JSON (Claude Code–compatible).

Embeddings (optional)

Build with --features embeddings for vector clustering support used by tkr suggest when indexing noisy lines. Without it, suggestions still work using textual signatures only.

License

Licensed under the Apache License, Version 2.0 (LICENSE or http://www.apache.org/licenses/LICENSE-2.0).

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.