tokencut

Install

Requires Python 3.11+ and uv (pipx works too).

uv tool install git+https://github.com/00200200/usagetrim
usagetrim demo

Try without installing: uvx --from git+https://github.com/00200200/usagetrim usagetrim demo.

Add it inside your app

Plugins run the pinned release wheel through uvx, so they need uv on PATH. The .mcpb extension installs its own copy through Claude Desktop.

verbose tool text  →  keep the failure  →  recover the rest by reference

Related MCP server: project-graph-mcp

See it cut

usagetrim demo is offline — no model calls. Failures stay; originals recover exactly.

Local o200k_base estimate — not billing, quality, or subscription-limit claims. Full matrix: usagetrim demo --json.

usagetrim run -- pytest -v
usagetrim run -- docker build -t app .
usagetrim run -- cargo test
usagetrim run -- go test ./...
usagetrim run -- kubectl describe pod api-7d8f9c-xk2m9
usagetrim run -- terraform plan
usagetrim run -- npx eslint . --format codeframe

What you get

• Compact other MCP servers, losslessly. The Claude Code hook rewrites results from other MCP servers: uniform JSON rows become TSV with the keys once, {"result": "…"} wrappers lose their escaping, and indentation goes. Every value and type survives, and prompt-injection boundaries such as Supabase's <untrusted-data-…> stay verbatim. Measured below.

• Spend Haiku, not Opus, on reading. The plugin adds scout (read-only search) and runner (tests and builds, failures only) agents on Haiku, so the main model gets conclusions instead of files and logs. usagetrim install --cheap-explore moves Claude Code's built-in Explore, which now inherits the main model, back to Haiku. /output-style usagetrim:lean trims reply preambles and recaps.

• Cut noise, keep the failure. Specialized filters for pytest, Docker, cargo, go, vitest, eslint, tsc, mypy, pyright, kubectl, terraform, GitHub Actions logs (gh run view --log-failed), uv sync/uv add, git diff, ruff…

• Session dedup + spill. Same run output or identical cat / MCP usagetrim_read view within ~15 minutes → short cache ref. Payloads over ~20 KiB → file + preview (USAGETRIM_SPILL_BYTES).

• Recover by reference. Omitted text stays in a local CCR cache: usagetrim retrieve tc_…

• Measure it. usagetrim gain / MCP usagetrim_gain — per-tool-family savings and passthrough candidates (local estimates, not account quotas).

• Desktop-ready. MCP for Claude Code / Codex / Cursor / Claude Desktop; Prepare-for-chat clipboard flow; optional macOS pet.

usagetrim gain                 # summary + by tool family + passthrough tips
usagetrim gain --history       # same tables + recent Raw→Compact / Saved rows
usagetrim gain --passthrough   # near-zero cuts only (specializer candidates)
usagetrim prepare --file draft.txt

Details and tradeoffs →

Measured on real sessions

14 days of the maintainer's Claude Code transcripts, replayed offline through the same functions the hook runs. Token counts are local o200k_base estimates, not billing.

All 3,144 SQL results rewritten as TSV decoded back to the original rows (reproduce on your own transcripts: uv run python scripts/replay_mcp_transcripts.py). Browser and page-text tools return prose and were left alone. Bash output in the same sessions was mostly ad-hoc scripts, where the filters saved under 1%. Test and build logs are where the Bash filters pay off, so results depend on what your tools print.

How it fits

UsageTrim is not a chat interceptor. It sits on the tool path (CLI wrapper, MCP, Prepare-for-chat) so agents still see failures — just without the noise.

Same CCR idea as peers (compress → cache → retrieve). Differentiation is specialized cutters, session dedup, spill-to-file, and Desktop/MCP install paths — not a claim that we beat RTK/snip/headroom on every workload.

Connect your agent

Desktop & Coding profiles: 9–11 essential tools instead of 16 — about 36–38% smaller tool schemas in local o200k_base measurements (3,414 → 2,183 / 2,102). Not a per-turn usage guarantee.

# One-command installer for Codex & Claude Desktop
usagetrim install --codex            # configures ~/.codex/config.toml
usagetrim install --claude-desktop   # configures Claude Desktop MCP
usagetrim install --mcpb             # Extension manifest for one-click packaging
usagetrim install --all              # configures all at once

For Claude Code CLI:

claude mcp add --scope user usagetrim -- usagetrim mcp --profile coding
# or, without installing first:
claude mcp add --scope user usagetrim -- uvx --from git+https://github.com/00200200/usagetrim usagetrim mcp

Manual MCP configuration for Claude Desktop, Cursor, Codex, Windsurf:

{
  "mcpServers": {
    "usagetrim": {
      "command": "/absolute/path/to/usagetrim",
      "args": ["mcp", "--profile", "desktop"]
    }
  }
}

Path: command -v usagetrim. Use --profile full for every tool, --profile coding for core terminal tools, or --profile desktop for chat apps. Client setup →

# Prepare messy logs or stack traces with prompt-cache prefix stabilization:
usagetrim prepare --desktop -f error.log

# Initialize or optimize lean, cache-aligned instructions (CLAUDE.md / AGENTS.md):
usagetrim rules --init --client claude        # writes lean CLAUDE.md (~120 tokens)
usagetrim rules --init --client codex         # writes lean AGENTS.md (~120 tokens)
usagetrim rules --optimize --write -f CLAUDE.md # strips filler, aligns prompt caching

Desktop companion

Mint robot on your Mac — draggable pet or menu-bar mode. Local measurements, task memory, optional account-limit readings. English UI. No extra AI calls.

Example balances are remaining allowance — not savings caused by UsageTrim.

Prepare for chat — paste a log, preview the cut, copy into Codex / Claude Desktop. Log prep →

macOS 13+ · ad-hoc signed, not notarized. CLI and MCP work without the pet. Build →

Roadmap

Ideas from the strongest tools in this space, adopted only with a measurement behind them:

• Ranked repo map (Aider-style PageRank over the symbol graph) fitted to a token budget.

• LSP-backed references and rename (Serena-style), falling back to the ast-grep index.

• Lossless log templating (Drain-style) for dev-server, Docker and CI logs.

• A paired A/B harness on provider-reported tokens and task pass rate, because output-size savings alone can hide extra turns.

Make it better with us

If UsageTrim earns a place in your workflow, star the repo. Lost context or a missed cut? Open an issue with a small redacted example.

Guide · Measurements · MIT