Usagetrim

Keep the signal. Cut the noise. Local CLI + MCP that folds verbose tool output for Claude Code, Codex, Cursor, and Claude Desktop — recoverable by reference. Optional macOS pet.

Website · Install · Demo · Features · Connect · Pet · Guide

---

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

| App | Install | |---|---| | Claude Code | /plugin marketplace add 00200200/usagetrim, then /plugin install usagetrim@usagetrim — MCP tools, Bash and MCP output hooks, Haiku agents | | Claude Desktop | Customize → Plugins → add the marketplace 00200200/usagetrim, or double-click usagetrim-.mcpb from Releases (Settings → Extensions) | | Codex app & CLI | codex plugin marketplace add 00200200/usagetrim, then codex plugin add usagetrim@usagetrim (or pick it under Plugins in the app) | | Cursor, Windsurf | usagetrim install --cursor or usagetrim install --windsurf |

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

---

See it cut

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

| Fixture | Tokens | | --- | ---: | | docker build BuildKit | 18,360 → 107 (99.4%) | | go test + goroutine dump | 3,281 → 64 (98.0%) | | terraform plan refresh/read | 5,885 → 236 (96.0%) | | cargo test + backtrace | 3,795 → 185 (95.1%) | | pytest noisy (xdist + I/O) | 5,111 → 349 (93.2%) | | kubectl describe pod | 8,049 → 601 (92.5%) | | pytest recovery demo | 1,562 → 174 (88.9%) | | vitest / eslint / tsc | up to 98.8% / 79% |

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 `` stay verbatim. [Measured below](#measured-on-real-sessions).
• 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.

| Tool results | Count | Tokens before → after | Cut | |---|---:|---:|---:| | All third-party MCP results | 11,058 | 7.17M → 5.85M | 18.3% | | Supabase execute_sql | 6,571 | 4.97M → 4.03M | 18.9% | | Google Search Console analytics | 223 | 702k → 434k | 38.2% | | Vercel list_deployments | 43 | 250k → 210k | 16.1% |

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.

| Approach | What UsageTrim does instead | | --- | --- | | Blind head/tail truncation | Specialized cutters keep the failure signal; rest recovers via usagetrim retrieve | | Rewrite the whole chat stream | MCP + prepare only — Desktop cannot rewrite model turns | | Opaque “saved tokens” badges | usagetrim gain shows local Raw→Compact by tool family (not billing quotas) |

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 00200200
• Source: 00200200/usagetrim
• License: MIT
• Homepage: https://00200200.github.io/usagetrim/

Install and usage instructions live in the source repository linked above.