{"slug": "szr-a-safer-command-output-reduction-for-coding-agents", "title": "Szr: A safer command output reduction for coding agents", "summary": "Szr, a Go-native CLI proxy developed by devr-tools, reduces noisy terminal output before it reaches an LLM context, preserving exit codes and saving tokens on logs, diffs, and test output. It wraps commands, summarizes output with a built-in retention verifier, and offers features like deduplication for re-runs and delta rendering for edit-test loops. The tool is available via Go, Homebrew, npm, and pip.", "body_md": "`szr`\n\nis a Go-native CLI proxy that reduces noisy terminal output before it reaches an LLM context.\n\nIt keeps the useful signal, preserves the wrapped command's exit code, and helps you spend fewer tokens on logs, diffs, and test output.\n\n- wraps the commands you already run\n- rewrites supported tools into more compact machine-friendly output when possible\n- summarizes noisy output without hiding the important anchors\n- records local history so you can inspect token savings over time\n\n**Fidelity is a runtime guarantee, not a promise.** A built-in retention verifier checks every render against the raw output — error lines, `file:line`\n\nanchors, diagnostic codes, failing test names — and repairs anything a filter dropped by appending the missing detail. Failing commands can never render content-free, explicit flags you pass are never overridden, and exit codes always match the wrapped command.\n\n**Compression is never worse than raw.** The finished display — retention repairs and artifact pointers included — never costs more tokens than relaying the raw output; when it would, szr emits the raw output instead. This holds for failure renders too: failure detail expansion stays within raw size. (Ultra-compact mode opts out — there the reshaped display is the point.) Profiles that read a single stream still surface the other stream's message when theirs is empty, so kubectl's `No resources found`\n\non stderr renders as a compact line instead of a raw fallback.\n\n**Re-runs cost almost nothing.** Agents run `git status`\n\n, `git diff`\n\n, and test suites over and over. When output is byte-identical to a recent run, szr emits a two-line reference instead (`unchanged from previous run (39s ago, x3 identical) [ref: …]`\n\n) — and `szr expand <ref>`\n\nrecovers the original byte-exact, on demand. The store is machine-level, so concurrent agents share it automatically: what one agent already saw, another can reference.\n\n**Edit-test loops render as deltas.** When a rerun's output*changed*instead of repeating, szr can emit a compact change digest —`since last run (2m ago): +3 -1 lines`\n\nplus the changed lines themselves — but only when that is strictly cheaper than the normal summary, and never at the cost of a critical line: a newly-failing test always appears in the digest. The baseline stays one`szr expand <ref>`\n\naway.**Agent fleets get their own scope.** Export`SZR_SESSION=<id>`\n\nbefore launching parallel agents and the whole fleet shares one dedup/delta scope: what one agent rendered, its siblings reference. Runs without the variable stay in the machine scope and never cross-match scoped sessions;`szr expand`\n\nresolves refs from any scope.\n\n**Anomalies are the payload.** List and table summaries always keep the rows that differ — the one stopped instance among 800 running, the `past_due`\n\nrow in a result set — plus exact counts. Uniform JSON arrays render as a compact table that halves the token cost of list-shaped API responses at equal information.\n\n**Everything is recoverable.** Whatever a summary omits is preserved in a local artifact with an exact pointer — compression never costs you the ability to look at the full output.\n\nInstall the CLI with Go:\n\n```\ngo install github.com/devr-tools/szr/cmd/szr@latest\nszr self doctor\n```\n\nOr build from a local checkout:\n\n```\nmake build\n./bin/szr self install\nszr self doctor\n```\n\nHomebrew install via tap:\n\n```\nbrew install devr-tools/tap/szr\nszr self doctor\n```\n\nnpm (installs a prebuilt binary, no Go toolchain required):\n\n```\nnpm install -g @devr-tools/szr\nszr self doctor\n```\n\npip (installs a prebuilt binary per platform):\n\n```\npip install szr\nszr self doctor\n```\n\nRun your normal commands through `szr`\n\n:\n\n```\nszr git status\nszr git diff\nszr go test ./...\nszr find . --name \"*.py\"\n```\n\nTransparent wrapper prefixes — `env KEY=VAL`\n\n, `env -u NAME`\n\n, `command`\n\n, `nice [-n N]`\n\n, bare `time`\n\n, and leading `VAR=value`\n\nassignments — route to the inner command's profile, so `szr env -u GOROOT go test ./...`\n\ncompresses like `szr go test ./...`\n\n. Prefixes stack, work inside `sh -c \"...\"`\n\nstrings, and the wrapper words themselves always execute verbatim. A bare `env`\n\nwith no wrapped command is a command of its own (the `env-print`\n\nprofile compacts its dump and redacts secret-looking values).\n\nAI bootstrap targets:\n\n| Tool | Install command | Uninstall command | Description |\n|---|---|---|---|\n| Codex | `szr install codex` |\n`szr uninstall codex` |\nWrites `~/.codex/szr.md` (or `$CODEX_HOME/szr.md` ) and patches the repo `AGENTS.md` to reference it. |\n| Claude Code | `szr install claude-code` |\n`szr uninstall claude-code` |\nInstalls `~/.claude/szr.md` , a Claude hook script, and a `settings.json` hook registration. |\n| Cursor | `szr install cursor` |\n`szr uninstall cursor` |\nInstalls `~/.cursor/hooks.json` plus a `preToolUse` hook script under `~/.cursor/hooks/` . |\n| Gemini | `szr install gemini` |\n`szr uninstall gemini` |\nInstalls `~/.gemini/settings.json` BeforeTool registration plus a hook script under `~/.gemini/hooks/` . |\n\nExternal agents, hooks, and plugins can call `szr rewrite --json`\n\nto reuse the same shell-routing policy that powers the built-in Claude, Cursor, and Gemini integrations.\n\nExample:\n\n```\nszr rewrite --json --command 'git diff HEAD~1..HEAD --stat | tail -30'\n```\n\nExample response:\n\n```\n{\n  \"command\": \"git diff HEAD~1..HEAD --stat | tail -30\",\n  \"rewrite\": \"szr proxy git diff HEAD~1..HEAD --stat | tail -30\",\n  \"hint\": \"szr git diff ... --stat or szr proxy git diff ... -- path/to/file | head -200\",\n  \"reason\": \"wrap noisy producer inside shell pipeline\",\n  \"auto_rewrite\": true,\n  \"wrap_mode\": \"proxy\",\n  \"producer_only\": true,\n  \"already_routed\": false\n}\n```\n\nUse this surface when you want to:\n\n- apply the same routing logic from custom Codex tooling or future plugins\n- distinguish between safe auto-rewrites and hint-only guidance\n- avoid re-encoding\n`git diff`\n\n,`grep`\n\n,`find`\n\n, and pipeline policy in multiple places\n\nDrop a JSON spec into the `filters/`\n\ndirectory next to `config.json`\n\nand szr loads it as an extra profile — a `match`\n\nsection routes commands, and the same declarative reducer keys the builtins use (`keep_patterns`\n\n, `strip_patterns`\n\n, `head`\n\n, `tail`\n\n, `dedup_consecutive`\n\n, …) shape the output. Project-local specs in `.szr/filters/`\n\nload too, once `advanced.project_filters`\n\nis enabled via `szr settings`\n\n(off by default). Name collisions with project rules, builtins, or earlier user filters are skipped with a warning, never silently shadowed. `szr profiles`\n\nmarks loaded specs with `source: user`\n\nor `source: project`\n\n.\n\nSee [docs/FILTERS.md](/devr-tools/szr/blob/main/docs/FILTERS.md) for the spec format and a worked example.\n\n`szr spread`\n\nsummarizes recorded savings; three additions make the numbers actionable:\n\n-\nappends an estimated-cost section: dollars avoided at a USD-per-million-input-tokens rate, raw versus emitted output cost, and a`szr spread --cost`\n\n`≈ N× a 200k-token context`\n\nanchor. The rate resolves from`--rate <usd-per-mtok>`\n\nfirst, then the`cost_rate_per_mtok`\n\nconfig key, then the default`3.00`\n\n; passing`--rate`\n\nimplies`--cost`\n\n. With`--json`\n\n, the figures appear as a`cost`\n\nobject.`szr gain`\n\naccepts the same flags. -\nscans local AI-agent session transcripts (`szr discover`\n\n`~/.claude/projects/`\n\n) for shell commands that ran*without*szr, routes each through szr's own profile matching, and estimates the missed token savings using your own per-profile history ratios (60% fallback for profiles without enough history). Read-only and local-only: transcripts are never modified or transmitted. By default it covers the current project's transcripts from the last 30 days;`--all`\n\nscans every project,`--since <days>`\n\nwidens or narrows the window,`--top <n>`\n\nsizes the command table (default 15), and`--json`\n\nemits the full report. -\njoins the two sides: per agent session it reports the model-billed tokens recorded in the transcripts (fresh input, cache reads, output — exact, as recorded by the agent runtime) next to szr's estimated emitted and avoided tokens for that session, including szr's share of fresh input and how much larger fresh input would have been without szr, plus a per-subagent breakdown (an`szr usage`\n\n`agents`\n\ncolumn, and a per-agent table when`--session`\n\nmatches one session). Records are correlated by session scope when present (`SZR_SESSION`\n\n), otherwise by directory and session time window; cache reads are always excluded from the derived percentages. On a terminal, an interactive picker lets you drill into any listed session's agents (`--no-input`\n\ndisables it). Flags:`--all`\n\n,`--since <days>`\n\n(default 7),`--session <id-prefix>`\n\n,`--json`\n\n,`--no-input`\n\n. -\nstreams local, sanitized execution events for agent or IDE integrations. Events contain reducer and token/latency measurements only—never commands, paths, rendered output, tee artifacts, or transcript content. Add`szr watch --jsonl`\n\n`--once`\n\nfor a snapshot instead of following the stream. See[the integration guide](/devr-tools/szr/blob/main/docs/INTEGRATIONS.md)for the stable event contract and a minimal live-results consumer. -\n**Optional diagnostics export** can send the same allowlisted event schema to an HTTPS gateway. It is disabled by default; when enabled, szr queues events in a bounded, owner-only local outbox, retries them in background batches, and makes one final bounded delivery attempt on command exit. Export failures never change the wrapped command's result. Configure an explicit endpoint in`config.json`\n\n:\n\n```\n{\n  \"diagnostics\": {\n    \"enabled\": true,\n    \"endpoint\": \"https://gateway.example/v1/events\",\n    \"max_outbox_mb\": 8\n  }\n}\n```\n\nGateway requests are JSON objects with\n\n`version`\n\nand an`events`\n\narray. Events never include command text, paths, output, tee artifacts, or transcript content. A gateway may emit a`provider_usage_aggregate`\n\nwith only opaque gateway correlation and aggregate szr/provider token counters; it must not contain agent/provider session IDs, prompts, transcripts, model names, or account identifiers. -\ninspects local event and pending-export storage without making a network request, including exporter endpoint host, drops, last success/failure, and next retry.`szr diagnostics status [--json]`\n\nis an explicit, five-second-bounded export attempt; it is never run on a wrapped-command path.`szr diagnostics flush`\n\nexplicitly removes local event, outbox, and exporter-status stores.`szr diagnostics purge --yes`\n\n- stdin pipe mode for filtering output already in flight\n- broader reducer coverage and better fallback handling for noisy real-world commands\n\n| Command | Description |\n|---|---|\n`szr git status` |\nRun common Git commands through `szr` with reduced output. |\n`szr go test ./...` |\nCompress noisy test output while preserving failures and anchors. |\n`szr find <path> --name \"*.py\"` |\nFind files or directories with repo-noise suppression and a bounded match summary. |\n`szr grep <pattern> <path>` |\nGroup search matches by file via ripgrep-backed summaries with conservative repo-noise excludes. |\n`szr run /usr/bin/grep ...` |\nPreserve exact grep semantics while still routing output through `szr` . |\n`szr rewrite --json --command '<cmd>'` |\nReturn the shared shell-routing decision for external agents and integrations. |\n`szr spread` |\nShow token savings, usage patterns, hotspot summaries, and per-profile fallback and empty-result rates. |\n`szr spread --history` |\nInspect savings history across recent commands. |\n`szr spread --cost [--rate <usd-per-mtok>]` |\nAppend estimated dollar figures and a 200k-context anchor to the savings summary. |\n`szr discover [--all|--since <n>|--top <n>|--json]` |\nScan local agent transcripts read-only for commands that ran without szr and estimate the missed savings. |\n`szr usage [--all|--since <n>|--session <id>|--json|--no-input]` |\nCompare model-billed tokens per agent session and subagent against szr-side emitted and avoided estimates. |\n`szr watch --jsonl [--once]` |\nStream sanitized local execution diagnostics as JSON Lines. |\n`szr diagnostics status [--json]` |\nInspect local diagnostics event and outbox health without network access. |\n`szr diagnostics flush` |\nExplicitly attempt one bounded upload of the diagnostics outbox. |\n`szr diagnostics purge --yes` |\nExplicitly remove local diagnostics events and pending exports. |\n`szr gateway hints-refresh` |\nFetch, verify, and atomically install signed gateway budget hints. |\n`szr doctor [--json]` |\nCheck runtime diagnostics and local history health. |\n`szr self doctor [--json] [--refresh]` |\nCheck install state, `PATH` , config, cache, and version details; `--refresh` bypasses the release-check cache for a live lookup. |\n`szr settings` |\nOpen the interactive settings menu for update checks, auto update, and other local preferences. |\n`szr expand <ref>` |\nRecover the byte-exact original output behind a dedup or delta baseline reference. |\n`SZR_SESSION=<id> szr <cmd...>` |\nScope dedup and delta references to one agent session; export it fleet-wide so parallel agents share a scope. |\n`szr tee --latest` |\nInspect the latest preserved full-output artifact. |\n`szr explain go test ./...` |\nShow the matched profile, budget, and rewrite decisions for a command. |\n`szr commands` |\nShow the full command catalog for power users and agents. |\n`szr profiles` |\nList built-in and user-defined reducer profiles. |\n\nReasoning budget modes:\n\n`standard`\n\n: balanced for human readability`agent`\n\n: tighter defaults for agent loops`aggressive`\n\n: smallest previews for spread-heavy workflows, including terser`git diff`\n\nsummaries\n\n- Interactive shells:\n`szr`\n\ncan print update notices on`stderr`\n\nwhen update checks are enabled. - Agent or non-interactive tool runs: inline update notices are suppressed to keep tool output stable.\n- Hosts can poll\n`szr doctor --json`\n\nor`szr self doctor --json`\n\nand render their own user-facing notification with the returned`update`\n\nobject; add`--refresh`\n\nto force a live release lookup instead of the cached one. - Opt-in auto update is available for recognized Homebrew or\n`go install`\n\ninstalls:\n\n```\n{\n  \"update_check\": {\n    \"enabled\": true,\n    \"interval_hours\": 24,\n    \"auto_update\": true\n  }\n}\n```\n\nFull-output captures are tee'd into the local data directory so compressed renders stay recoverable. Retention is bounded by default:\n\n- a single artifact is capped at 4 MiB; a larger capture keeps the head and tail of the stream around a truncation marker that records how many bytes were omitted\n- the tee directory is pruned oldest-first past 200 files or 256 MiB total; the newest artifact always survives, and pruned files are dropped from the tee index so lookups never dangle\n- orphaned in-progress captures are cleaned up after one hour\n\nAll three caps are adjustable via `szr settings`\n\n(`tee max file mb`\n\n, `tee max dir files`\n\n, `tee max dir mb`\n\n) or in the config file:\n\n```\n{\n  \"tee_max_file_mb\": 4,\n  \"tee_max_dir_files\": 200,\n  \"tee_max_dir_mb\": 256\n}\n```\n\nZero or negative values fall back to the defaults rather than meaning \"unlimited\".", "url": "https://wpnews.pro/news/szr-a-safer-command-output-reduction-for-coding-agents", "canonical_source": "https://github.com/devr-tools/szr", "published_at": "2026-07-22 18:03:51+00:00", "updated_at": "2026-07-22 18:22:48.157624+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "large-language-models"], "entities": ["devr-tools", "szr", "Go", "Homebrew", "npm", "pip"], "alternates": {"html": "https://wpnews.pro/news/szr-a-safer-command-output-reduction-for-coding-agents", "markdown": "https://wpnews.pro/news/szr-a-safer-command-output-reduction-for-coding-agents.md", "text": "https://wpnews.pro/news/szr-a-safer-command-output-reduction-for-coding-agents.txt", "jsonld": "https://wpnews.pro/news/szr-a-safer-command-output-reduction-for-coding-agents.jsonld"}}