trimwire
AZagatti/trimwire
Reduz peso morto em sessões longas do Claude Code automaticamente
Ver no GitHubGateway local que poda o contexto da API do Claude Code em tempo real, removendo requisições falhadas, deduplicando conteúdo e eliminando screenshots antigos. Aprovado pela Anthropic, sem certificados CA ou reinicializações necessárias.
Instalação
npx convez-ai AZagatti/trimwire1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Otimizar sessões longas de Claude Code removendo contexto obsoleto
- Reduzir custos de tokens ao eliminar conteúdo repetido e falhado
- Comprimir histórico com resumidor opcional para sessões de raciocínio intenso
Veredito

Ferramenta sólida e bem-construída em Rust que resolve um problema real de eficiência em sessões longas do Claude Code. Aprovação da Anthropic + zero overhead de configuração a torna confiável para quem quer otimizar contexto sem complexidade.
README
A tradução para o português deste README ainda está na fila.
trimwire
Long Claude Code sessions fill up with stale file reads, superseded tool output, and old reasoning — so every turn ships more dead weight to Anthropic. trimwire is a tiny local gateway that prunes that dead weight from each request, deterministically, keeping recent turns verbatim. No CA cert, no MITM, no restart.

Quickstart
1. Install
Download a prebuilt binary — no toolchain, nothing piped to a shell. Grab the asset for your OS/arch from the latest release, then (Linux/macOS example — pick the asset matching your platform):
tar xzf trimwire-x86_64-unknown-linux-gnu.tar.gz # Windows: unzip the .zip
chmod +x trimwire
sudo mv trimwire /usr/local/bin/ # or any dir on your PATH
trimwire --version # prints version + git SHA
Have Rust?
cargo binstall trimwire # fetches the same prebuilt binary, no compile
cargo install trimwire # from crates.io (builds from source; needs Rust 1.85+)
cargo install --path . # build from a local checkout
Quick install — Linux/macOS only (convenience) — downloads the right prebuilt
binary and runs trimwire install for you. Read the script
first if you pipe to a shell:
curl -LsSf https://raw.githubusercontent.com/AZagatti/trimwire/main/scripts/install.sh | sh
Windows — download trimwire-x86_64-pc-windows-msvc.zip from the
latest release, unzip it,
and put trimwire.exe on your PATH (or cargo binstall trimwire). Note: Claude
Code on Windows typically runs under WSL2 — there, use the Linux instructions
above; the always-on service targets Linux/macOS (systemd/launchd).
2. Wire it up
trimwire install # config + shell-rc ANTHROPIC_BASE_URL + the always-up service (auto-started)
exec $SHELL # pick up the new env
trimwire doctor # optional: confirm the gateway is wired + healthy
claude # use claude as normal — trimwire prunes each request
Day one: zero rows in
trimwire statsis normal — no traffic has flowed through the gateway yet (or the session was short and text-only). Run a session, then check again.Long, reasoning-heavy sessions? Turn on the optional summarizer to compress old context with a model you choose — local (ollama) or a cloud API. One command:
trimwire summarizer setup.
Optional shell completions: trimwire completions zsh > ~/.zfunc/_trimwire
(also bash, fish, elvish, powershell). trimwire --version reports the
build's git SHA + date for bug reports.
On systemd/launchd, install starts the service for you (socket activation). No
systemd/launchd (some containers)? install prints a one-time trimwire on.
install is idempotent and never touches your statusline. Want to try it
once without installing anything? trimwire run spins up the gateway in
the background and launches claude through it for that one session (any args
you pass are forwarded to claude). To see
the savings on a session you've already run, with zero install:
trimwire preview ~/.claude/projects/<project>/<session>.jsonl
It replays the real strategies over a recorded transcript and prints what each
would trim. Read-only, no network. (Reports messages[] only; the live request
also carries a system prompt + tool schemas not in the transcript.)
How it works
Claude Code ──/v1/messages──▶ trimwire ──prune messages[]──▶ api.anthropic.com
(localhost) (localhost) (cache-safe) (real upstream)
▲ │
└──────── response streamed back byte-for-byte, unbuffered ◀───┘
trimwire points Claude Code at itself via Anthropic's documented
ANTHROPIC_BASE_URL, intercepts every outbound /v1/messages request, rewrites
the messages[] array with eight cache-safe pruning strategies, and forwards the slimmer
payload to api.anthropic.com. Pure request-shaping: no CA cert, no TLS
interception, no Claude Code restart, and your on-disk transcript is left
untouched.
The always-up service uses socket activation: the OS owns the port, so a crashed or restarting daemon never strands Claude Code; connections queue instead of being refused. Set it and forget it.
Tuning & safety
New here / worried about ToS or privacy? Short answers: with an API key you're clearly fine —
ANTHROPIC_BASE_URLis Anthropic's documented gateway mechanism. With a Pro/Max OAuth subscription the rules tightened in 2026 and it's a greyer area —docs/FAQ.mdhas the honest detail. On privacy: it never stores your code (the ledger is content-free), and you can try it with zero risk viatrimwire preview.
- One knob: the profile. Run
trimwire configand setprofile = "default" | "gentle"(defaultdefault). These are cleanliness levels, not cost tiers.defaultprunes hardest (all eight cache-safe strategies, aggressive knobs).gentleis the lightest touch (dedup + failed-input-purge + a conservative bloat_cap + a conservative thinking_strip). Both turn on stable-prefix re-pruning ([reprune], which replays the same pruning decisions turn-to-turn so the cache prefix stays byte-identical) to keep the prompt cache warm on long sessions. SeeCONFIGURATION.mdandbenchmark/for what each trades. - Rollback any time. To route Claude Code straight to Anthropic again,
unset ANTHROPIC_BASE_URLin your shell (or open a fresh shell after uninstalling).trimwire offstops the gateway — note your rc still exportsANTHROPIC_BASE_URL, so Claude calls fail until youonagain or unset it.trimwire uninstallremoves the service, login autostart, and the statusline (only if trimwire added it); it leaves the shell-rcANTHROPIC_BASE_URLblock for you to delete by hand (it prints a reminder). Your config and ledger stay until you delete~/.trimwire/. - No message content stored. The only local persistence is an optional
savings ledger of byte counts + hashes (
~/.trimwire/ledger.db); it never records your prompts or tool output. Disable with[ledger] enabled = false. SeeSECURITY.md.
Summarizer (opt-in)
trimwire is model-free by default. There's an optional summarizer that compresses the old part of a long session with a language model. It's never load-bearing: any failure (model down, slow, bad output) silently falls back to model-free pruning.
Configure with trimwire summarizer setup (interactive wizard). Three engines:
local— ollama on your own machine. No API key, no data leaves your machine. Default model:qwen3.5:4b(~3.4 GB RAM), the only harm-validated model.- Cloud API (engine = a provider id, e.g.
"anthropic") — sends the prunable slice to the provider you configure using your own API key. Your key, your provider, your choice. model-free— the default; no summarizer, no model calls.
The wizard writes the block for you. To edit by hand, add it to
~/.config/trimwire.toml (global) or ./.trimwire.toml (per-project):
# ~/.config/trimwire.toml — local (ollama) engine
[summarizer]
engine = "local"
[summarizer.local]
model = "qwen3.5:4b"
# ~/.config/trimwire.toml — cloud API engine: set engine to a provider id
[summarizer]
engine = "anthropic" # a provider id below (or "local" / "model-free")
[[summarizer.providers]]
id = "anthropic"
style = "anthropic" # or "openai" (OpenAI-compatible)
base_url = "https://api.anthropic.com"
model = "claude-haiku-4-5"
api_key_env = "ANTHROPIC_API_KEY" # env var name; key never stored in the config
Best for long, reasoning-dense sessions; it only fires once a request exceeds
trigger_bytes (200 KB default), so short sessions are untouched. Model fidelity
varies — validate your pick with trimwire summarizer probe --model <id> --runs 10
(add --yes for an API provider; local models need no flag).
See docs/SUMMARIZER.md and
docs/MODEL-COMPATIBILITY.md for the full guide + a
verified model ranking.
Commands
| Command | What it does |
|---|---|
trimwire install [--boot] | Config + shell-rc ANTHROPIC_BASE_URL export + the always-up service (systemd user / launchd, login-scoped; --boot starts it pre-login). Idempotent; does not touch your statusline. |
trimwire on / off / status | Start / stop / health-check the service. |
trimwire doctor | One-shot setup diagnosis: config + active profile, gateway health, ANTHROPIC_BASE_URL wiring, ledger. Exits non-zero if a hard check fails, so trimwire doctor && claude and CI healthchecks work. |
trimwire completions <shell> | Print a shell completion script to stdout (bash/zsh/fish/elvish/powershell). |
trimwire man [--out DIR] | Generate man pages: to stdout (trimwire man | man -l -), or one page per command into DIR (for packagers). |
trimwire run [claude args…] | Start the gateway in the background and launch claude through it (no install needed). |
trimwire summarizer setup / status / benchmark / probe | Configure the optional summarizer (interactive wizard), check its status, score a model for fact retention/compression, or probe whether your model holds your slice budget (retention by position). |
trimwire stats [--json] [-q] [-v] [--session [ID]] [--since YYYY-MM-DD] [--until YYYY-MM-DD] | Savings ledger: total saved, reduction %, ~tokens removed, per-strategy gauge (bars by bytes trimmed), cache-prefix stability. --session [ID] drills into one session's per-model cache/token report (omit ID for the most recent); --since/--until restrict to a UTC date window; --json for scripting; -q/--quiet for a one-line headline; -v/--verbose for full instrumentation. |
trimwire recall [query] [--json] [--limit N] | List recent sessions (content-free: date, requests, in→out + reduction %, cache-hit %, model), newest first; optional substring filter on session-id / model. Find a session id to pass to stats --session. |
trimwire dashboard [--out FILE] | Write a self-contained local HTML stats dashboard (content-free; embeds the ledger report, no server, no network) to FILE (default trimwire-report.html). Open it via file://. A snapshot; re-run to refresh. |
trimwire share enable / disable | Opt in or out of telemetry uploads. Persists [share] enabled = true/false in the global config. Once enabled, trimwire share stats uploads without --yes each run. |
trimwire share stats [--yes] [--force] | Opt-in, off by default. Upload an anonymous, content-free aggregate of your ledger to the community dashboard. Requires consent (share enable or --yes). Without consent, prints the exact payload it would send (a dry run, no network). --force bypasses the once-per-day upload throttle. Coarse buckets only; never prompts/paths/ids. See docs/TELEMETRY.md. |
trimwire share benchmark [--model TAG] [--all-installed] [--yes] | Opt-in, off by default. Score your summarizer model on a bundled synthetic corpus and upload one anonymous, content-free per-model row to the community benchmark leaderboard. Dry-run (prints the row) without --yes. See docs/BENCHMARK.md. |
trimwire preview [<session.jsonl>| --last] [--profile] [--json] | Read-only what-if: reconstruct messages[] from a recorded session transcript and report what pruning would trim (per strategy), without touching the file or the network. --last auto-picks the most recent session (no path needed). |
trimwire statusline add / wrap / remove | Opt-in live savings bar (see below). |
trimwire hook | Optional SessionStart hook that warns in-session if trimwire is set but not actually serving. |
trimwire sweep list / all [--dry-run] [--yes] / file <path> / undo <path> | Clean session transcripts on disk (atomic, backed up). list/all auto-discover; all confirms first (--yes to skip; required when piped/CI); undo restores a backup. |
trimwire config / config show [--json] | Open the config in $EDITOR; show prints the resolved effective config + active profile. |
trimwire uninstall | Remove the service, GUI/login env hooks, lingering, and the statusline (if trimwire added it). Leaves the shell-rc ANTHROPIC_BASE_URL block for you to delete by hand. |
Output adapts to context: the status glyphs (
✓ ✗ ⚠ ⊡) and the▰▱gauge fall back to ASCII ([ok] [x] [!] ::,#-) when stdout is piped/redirected orNO_COLORis set, so logs and scripts stay clean.
Live savings bar (opt-in)
trimwire install never modifies your Claude Code statusline. Showing live
per-session savings (⊡ trimwire 128 KB (~32K tok) · 41% ↓ · 87 reqs) is a
separate, explicit step:
- No statusline yet →
trimwire statusline addmakes trimwire your bar. - Already have one (e.g.
claude-statusline) →trimwire statusline wrapadds a trimwire row beneath it, reversibly. trimwire statusline removeundoes either.
Embedding trimwire as a segment in your own script, and the health-alert hook,
are covered in CONFIGURATION.md. trimwire stats always
shows totals with no statusline at all.
Telemetry — opt-in, anonymous, off by default
trimwire collects nothing unless you explicitly opt in. Opt in with
trimwire share enable (persists consent); opt out with trimwire share disable.
Once enabled, trimwire share stats uploads a single small JSON of coarse,
bucketed, aggregate numbers: per-strategy reduction share, overall reduction,
version, model family, profile, cache health, conversation length bucket. Nothing
else. Never prompts, code, file paths, session ids, machine ids, IPs, or raw
counts. Everything is bucketed on your machine before it leaves.
The built-in community collector endpoint ships in the binary and points at
https://api.trimwire.dev/ingest. The public community dashboard at
https://trimwire.dev shows only k-anonymous aggregates. Full contract:
docs/TELEMETRY.md.
How much does it save?
It depends on your session shape. trimwire prunes only when a strategy matches,
and does nothing when there's no redundancy, so there's no single "saves
X%". Offline replay through the real strategy code (default profile) spans the
full range:
| Session shape | Request size | Reduction |
|---|---|---|
| Plain chat, no tools | 9.5 KB | 0% (no-op) |
| Repeated searches | 29.8 KB | 78% |
| Coding (superseded reads + old log) | 48.0 KB | 83% |
| Long-running diverse tools | 133.6 KB | 60% |
| Resumed ~50-turn session | 186.4 KB | 65% |
| Browser / screenshot-heavy | 423.2 KB | 85% |
| Realistic composite | 363.0 KB | 95% |
The point is a cleaner session, not a smaller bill. Pruning drops stale backlog so the current task isn't buried in history ("context rot"). That lifts the focus ratio (the share of the request that's your recent working window: repeated-search 33%→66%, browser 71%→98%) and keeps it 2–3× higher than no pruning over a long session. (Focus is a byte-share proxy; that it improves model output is plausible, not proven.)
Cost is a side effect, and non-monotonic. Cache hits bill at ~0.1×, so pruning old content can bust the cache: short sessions are a wash-to-loss, long ones win (≈ −55% at 256 turns). Overhead is sub-2 ms per request, off the network path.
Numbers are reproducible (cargo run --release --example bench) and least
reliable for token/cost estimates (~4 bytes/token). The full 14-corpus tables,
per-strategy attribution, profiles, cache-stability, and the cost model live in
benchmark/.
For figures from your traffic, run trimwire stats.
Eight cache-safe strategies ship enabled in default: cross_turn_dedup,
failed_input_purge, stale_input_cap, stale_reads, bloat_cap,
sliding_window, image_strip, thinking_strip. The gentle profile runs a
conservative subset: dedup + failed_input_purge + bloat_cap + thinking_strip. A
ninth strategy, simhash_dedup (near-duplicate tool_result collapse), is opt-in
(off in both profiles). Every threshold, denylist, profile, and the ledger are
documented in
CONFIGURATION.md.
Compatibility
- Works with both Pro/Max OAuth subscriptions and API keys (auth header forwarded unchanged).
- Covers the terminal
claudeCLI and IDE extensions that inherit the shell environment. - Does not cover the standalone desktop/web app. Like any local gateway, it
only sees clients that read
ANTHROPIC_BASE_URL. - Does not modify the Claude Code system prompt.
Docs
- FAQ & Trust: ToS, code privacy, latency, how to try it safely first:
docs/FAQ.md - Configuration: every strategy knob, the ledger, statusline integration:
CONFIGURATION.md - Troubleshooting: connection errors, empty stats, port conflicts, sweep aborts:
docs/TROUBLESHOOTING.md - Alternatives: mitmproxy-based pruners and other options:
docs/ALTERNATIVES.md - Architecture: module-by-module design:
ARCHITECTURE.md - Design rationale + validation:
SPIKE.md /trimwireClaude Code skill: in-session savings/cache visibility by shelling the read-only CLI; bundled at.claude/skills/trimwire/(copy into your project's.claude/skills/to use it).
Contributing & development
cargo build
cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt --check
See CONTRIBUTING.md for how to submit changes, AGENTS.md
for repo conventions + pre-commit gates, and SECURITY.md for the
threat model (a localhost proxy that buffers your requests; the only local
persistence is the savings ledger (byte counts + hashes, no message content))
and how to report a vulnerability.
License
Dual-licensed under MIT or Apache-2.0 at your option. Unless you state otherwise, any contribution you submit shall be dual-licensed as above, without additional terms.