From b0c648b4573bacaec794fce1f85ee4dd694cc034 Mon Sep 17 00:00:00 2001 From: Alex Wilkerson John Date: Thu, 23 Jul 2026 20:18:03 -0400 Subject: [PATCH 1/4] docs: streamline README quick start --- README.md | 255 ++++++++++----------------------------------- docs/USER_GUIDE.md | 75 +++++++++++++ 2 files changed, 129 insertions(+), 201 deletions(-) create mode 100644 docs/USER_GUIDE.md diff --git a/README.md b/README.md index 00c981d..b6b4beb 100644 --- a/README.md +++ b/README.md @@ -12,98 +12,78 @@ PyPI version - - CD - CI - - homebrew-validation - - - Go Reference - - - Go Report Card - - + License: Apache 2.0 - - LinkedIn -

# szr -`szr` is a Go-native CLI proxy that reduces noisy terminal output before it reaches an LLM context. - -It keeps the useful signal, preserves the wrapped command's exit code, and helps you spend fewer tokens on logs, diffs, and test output. - -## What it does - -- wraps the commands you already run -- rewrites supported tools into more compact machine-friendly output when possible -- summarizes noisy output without hiding the important anchors -- records local history so you can inspect token savings over time +`szr` makes noisy terminal output easier to read and cheaper to send to an AI assistant. Run the commands you already use through `szr`; it keeps errors, file locations, and exit codes while trimming the noise. -## Why szr - -**Fidelity is a runtime guarantee, not a promise.** A built-in retention verifier checks every render against the raw output — error lines, `file:line` anchors, 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. - -**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` on stderr renders as a compact line instead of a raw fallback. - -**Re-runs cost almost nothing.** Agents run `git status`, `git diff`, 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: …]`) — and `szr expand ` recovers 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. - -- **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` plus 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 ` away. -- **Agent fleets get their own scope.** Export `SZR_SESSION=` before 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` resolves refs from any scope. - -**Anomalies are the payload.** List and table summaries always keep the rows that differ — the one stopped instance among 800 running, the `past_due` row 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. - -**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. +It is useful whether you are working in a terminal yourself or asking an AI coding tool to help. ## Install -Install the CLI with Go: +Choose the option that fits your setup, then run `szr self doctor` to check that everything is ready. + +
+Homebrew — macOS or Linux ```bash -go install github.com/devr-tools/szr/cmd/szr@latest +brew install devr-tools/tap/szr szr self doctor ``` -Or build from a local checkout: +
+ +
+npm — prebuilt binary; no Go required ```bash -make build -./bin/szr self install +npm install -g @devr-tools/szr szr self doctor ``` -Homebrew install via tap: +
+ +
+pip — prebuilt binary; no Go required ```bash -brew install devr-tools/tap/szr +pip install szr szr self doctor ``` -npm (installs a prebuilt binary, no Go toolchain required): +
+ +
+Go — build from source ```bash -npm install -g @devr-tools/szr +go install github.com/devr-tools/szr/cmd/szr@latest szr self doctor ``` -pip (installs a prebuilt binary per platform): +
+ +
+Local checkout — for contributors ```bash -pip install szr +make build +./bin/szr self install szr self doctor ``` -## Main commands +
+ +## Get started -Run your normal commands through `szr`: +Put `szr` in front of a command you already run: ```bash szr git status @@ -112,163 +92,36 @@ szr go test ./... szr find . --name "*.py" ``` -Transparent wrapper prefixes — `env KEY=VAL`, `env -u NAME`, `command`, `nice [-n N]`, bare `time`, and leading `VAR=value` assignments — route to the inner command's profile, so `szr env -u GOROOT go test ./...` compresses like `szr go test ./...`. Prefixes stack, work inside `sh -c "..."` strings, and the wrapper words themselves always execute verbatim. A bare `env` with no wrapped command is a command of its own (the `env-print` profile compacts its dump and redacts secret-looking values). - -## AI tool support - -AI bootstrap targets: - -| Tool | Install command | Uninstall command | Description | -| --- | --- | --- | --- | -| Codex | `szr install codex` | `szr uninstall codex` | Writes `~/.codex/szr.md` (or `$CODEX_HOME/szr.md`) and patches the repo `AGENTS.md` to reference it. | -| Claude Code | `szr install claude-code` | `szr uninstall claude-code` | Installs `~/.claude/szr.md`, a Claude hook script, and a `settings.json` hook registration. | -| Cursor | `szr install cursor` | `szr uninstall cursor` | Installs `~/.cursor/hooks.json` plus a `preToolUse` hook script under `~/.cursor/hooks/`. | -| Gemini | `szr install gemini` | `szr uninstall gemini` | Installs `~/.gemini/settings.json` BeforeTool registration plus a hook script under `~/.gemini/hooks/`. | - -## Integration surface - -External agents, hooks, and plugins can call `szr rewrite --json` to reuse the same shell-routing policy that powers the built-in Claude, Cursor, and Gemini integrations. - -Example: - -```bash -szr rewrite --json --command 'git diff HEAD~1..HEAD --stat | tail -30' -``` - -Example response: - -```json -{ - "command": "git diff HEAD~1..HEAD --stat | tail -30", - "rewrite": "szr proxy git diff HEAD~1..HEAD --stat | tail -30", - "hint": "szr git diff ... --stat or szr proxy git diff ... -- path/to/file | head -200", - "reason": "wrap noisy producer inside shell pipeline", - "auto_rewrite": true, - "wrap_mode": "proxy", - "producer_only": true, - "already_routed": false -} -``` - -Use this surface when you want to: - -- apply the same routing logic from custom Codex tooling or future plugins -- distinguish between safe auto-rewrites and hint-only guidance -- avoid re-encoding `git diff`, `grep`, `find`, and pipeline policy in multiple places +`szr` returns the same exit code as the command it runs. If a shorter result would lose important information, it shows the original output instead. -## User-defined filters - -Drop a JSON spec into the `filters/` directory next to `config.json` and szr loads it as an extra profile — a `match` section routes commands, and the same declarative reducer keys the builtins use (`keep_patterns`, `strip_patterns`, `head`, `tail`, `dedup_consecutive`, …) shape the output. Project-local specs in `.szr/filters/` load too, once `advanced.project_filters` is enabled via `szr settings` (off by default). Name collisions with project rules, builtins, or earlier user filters are skipped with a warning, never silently shadowed. `szr profiles` marks loaded specs with `source: user` or `source: project`. - -See [docs/FILTERS.md](docs/FILTERS.md) for the spec format and a worked example. - -## Savings insight - -`szr spread` summarizes recorded savings; three additions make the numbers actionable: - -- **`szr spread --cost`** appends an estimated-cost section: dollars avoided at a USD-per-million-input-tokens rate, raw versus emitted output cost, and a `≈ N× a 200k-token context` anchor. The rate resolves from `--rate ` first, then the `cost_rate_per_mtok` config key, then the default `3.00`; passing `--rate` implies `--cost`. With `--json`, the figures appear as a `cost` object. `szr gain` accepts the same flags. -- **`szr discover`** scans local AI-agent session transcripts (`~/.claude/projects/`) 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` scans every project, `--since ` widens or narrows the window, `--top ` sizes the command table (default 15), and `--json` emits the full report. -- **`szr usage`** joins 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 `agents` column, and a per-agent table when `--session` matches one session). Records are correlated by session scope when present (`SZR_SESSION`), 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` disables it). Flags: `--all`, `--since ` (default 7), `--session `, `--json`, `--no-input`. -- **`szr watch --jsonl`** streams 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 `--once` for a snapshot instead of following the stream. See [the integration guide](docs/INTEGRATIONS.md) for the stable event contract and a minimal live-results consumer. -- **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 and retries them in background batches. Export failures never affect the wrapped command. Configure an explicit endpoint in `config.json`: - - ```json - { - "diagnostics": { - "enabled": true, - "endpoint": "https://gateway.example/v1/events", - "max_outbox_mb": 8 - } - } - ``` - - Gateway requests are JSON objects with `version` and an `events` array. Events never include command text, paths, output, tee artifacts, or transcript content. A gateway may emit a `provider_usage_aggregate` with 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. -- **`szr diagnostics status [--json]`** inspects local event and pending-export storage without making a network request, including exporter endpoint host, drops, last success/failure, and next retry. **`szr diagnostics flush`** is an explicit, five-second-bounded export attempt; it is never run on a wrapped-command path. **`szr diagnostics purge --yes`** explicitly removes local event, outbox, and exporter-status stores. - -## Upcoming features - -- stdin pipe mode for filtering output already in flight -- broader reducer coverage and better fallback handling for noisy real-world commands - -## Command reference +## Main commands -| Command | Description | +| Command | What it does | | --- | --- | -| `szr git status` | Run common Git commands through `szr` with reduced output. | -| `szr go test ./...` | Compress noisy test output while preserving failures and anchors. | -| `szr find --name "*.py"` | Find files or directories with repo-noise suppression and a bounded match summary. | -| `szr grep ` | Group search matches by file via ripgrep-backed summaries with conservative repo-noise excludes. | -| `szr run /usr/bin/grep ...` | Preserve exact grep semantics while still routing output through `szr`. | -| `szr rewrite --json --command ''` | Return the shared shell-routing decision for external agents and integrations. | -| `szr spread` | Show token savings, usage patterns, hotspot summaries, and per-profile fallback and empty-result rates. | -| `szr spread --history` | Inspect savings history across recent commands. | -| `szr spread --cost [--rate ]` | Append estimated dollar figures and a 200k-context anchor to the savings summary. | -| `szr discover [--all\|--since \|--top \|--json]` | Scan local agent transcripts read-only for commands that ran without szr and estimate the missed savings. | -| `szr usage [--all\|--since \|--session \|--json\|--no-input]` | Compare model-billed tokens per agent session and subagent against szr-side emitted and avoided estimates. | -| `szr watch --jsonl [--once]` | Stream sanitized local execution diagnostics as JSON Lines. | -| `szr diagnostics status [--json]` | Inspect local diagnostics event and outbox health without network access. | -| `szr diagnostics flush` | Explicitly attempt one bounded upload of the diagnostics outbox. | -| `szr diagnostics purge --yes` | Explicitly remove local diagnostics events and pending exports. | -| `szr gateway hints-refresh` | Fetch, verify, and atomically install signed gateway budget hints. | -| `szr doctor [--json]` | Check runtime diagnostics and local history health. | -| `szr self doctor [--json] [--refresh]` | Check install state, `PATH`, config, cache, and version details; `--refresh` bypasses the release-check cache for a live lookup. | -| `szr settings` | Open the interactive settings menu for update checks, auto update, and other local preferences. | -| `szr expand ` | Recover the byte-exact original output behind a dedup or delta baseline reference. | -| `SZR_SESSION= szr ` | Scope dedup and delta references to one agent session; export it fleet-wide so parallel agents share a scope. | -| `szr tee --latest` | Inspect the latest preserved full-output artifact. | -| `szr explain go test ./...` | Show the matched profile, budget, and rewrite decisions for a command. | -| `szr commands` | Show the full command catalog for power users and agents. | -| `szr profiles` | List built-in and user-defined reducer profiles. | - -Reasoning budget modes: - -- `standard`: balanced for human readability -- `agent`: tighter defaults for agent loops -- `aggressive`: smallest previews for spread-heavy workflows, including terser `git diff` summaries - -## Update notices - -- Interactive shells: `szr` can print update notices on `stderr` when update checks are enabled. -- Agent or non-interactive tool runs: inline update notices are suppressed to keep tool output stable. -- Hosts can poll `szr doctor --json` or `szr self doctor --json` and render their own user-facing notification with the returned `update` object; add `--refresh` to force a live release lookup instead of the cached one. -- Opt-in auto update is available for recognized Homebrew or `go install` installs: - -```json -{ - "update_check": { - "enabled": true, - "interval_hours": 24, - "auto_update": true - } -} -``` +| `szr ` | Run a command with cleaner, more compact output. | +| `szr spread` | See the token savings from recent runs. | +| `szr explain ` | See how szr would handle a command. | +| `szr expand ` | Recover the complete original output from a saved reference. | +| `szr self doctor` | Check your installation, configuration, and updates. | +| `szr settings` | Open interactive local settings. | -## Tee artifact retention +## Works well with AI tools -Full-output captures are tee'd into the local data directory so compressed renders stay recoverable. Retention is bounded by default: +Set up your preferred assistant with one command: -- 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 -- 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 -- orphaned in-progress captures are cleaned up after one hour - -All three caps are adjustable via `szr settings` (`tee max file mb`, `tee max dir files`, `tee max dir mb`) or in the config file: - -```json -{ - "tee_max_file_mb": 4, - "tee_max_dir_files": 200, - "tee_max_dir_mb": 256 -} +```bash +szr install codex +szr install claude-code +szr install cursor +szr install gemini ``` -Zero or negative values fall back to the defaults rather than meaning "unlimited". +Use `szr uninstall ` to remove an integration. See the [user guide](docs/USER_GUIDE.md#ai-tool-integrations) for what each integration changes. -## More docs +## Learn more +- [User guide](docs/USER_GUIDE.md) — advanced commands, integrations, history, diagnostics, and updates +- [Profiles](docs/PROFILES.MD) — supported command families +- [User-defined filters](docs/FILTERS.md) — add your own command reducers - [Contributing](CONTRIBUTING.md) -- [Local CI](docs/LOCAL_CI.md) -- [Releasing](docs/RELEASING.md) -- [Go package](docs/GO_PACKAGE.md) - [Architecture](docs/ARCHITECTURE.md) -- [Profiles](docs/PROFILES.MD) -- [User-defined filters](docs/FILTERS.md) diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..da1911e --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,75 @@ +# szr user guide + +This guide covers the features that are useful once you are comfortable running commands through `szr`. + +## Everyday use + +Run `szr` before a command you already use. It chooses a profile for supported tools, preserves the command's exit code, and keeps useful error lines and file locations. If a compact result would be larger or less useful than the original output, szr prints the original output. + +```bash +szr git status +szr git diff +szr go test ./... +szr grep "TODO" . +``` + +You can also use common shell wrappers. For example, `szr env -u GOROOT go test ./...` is handled like `szr go test ./...`. + +## AI tool integrations + +Install an integration with `szr install ` and remove it with `szr uninstall `. + +| Tool | Install command | What it sets up | +| --- | --- | --- | +| Codex | `szr install codex` | A Codex instruction file and a reference from the repository's `AGENTS.md`. | +| Claude Code | `szr install claude-code` | A Claude instruction file and hook registration. | +| Cursor | `szr install cursor` | A Cursor pre-tool hook. | +| Gemini | `szr install gemini` | A Gemini before-tool hook. | + +## See your savings + +`szr spread` summarizes recent output and token savings. Add `--history` for recent commands, or `--cost` to include an estimate based on an input-token price. + +```bash +szr spread +szr spread --history +szr spread --cost --rate 3.00 +``` + +`szr discover` can scan local AI-agent transcripts, without changing or uploading them, to estimate savings from commands that did not use szr. `szr usage` compares recorded agent token use with szr's estimates. + +```bash +szr discover +szr usage +``` + +## Recover complete output + +szr keeps local references to output it has compacted. Use `szr expand ` to retrieve the original output. + +```bash +szr expand abc123 +``` + +Use `szr tee --latest` to inspect the most recent saved artifact. Full-output retention is bounded by default; adjust it in `szr settings` if needed. + +## For integrations and advanced workflows + +- `szr rewrite --json --command ''` returns szr's routing decision for custom tools and hooks. +- `szr watch --jsonl` streams sanitized local execution events for integrations. Add `--once` for one snapshot. +- `szr diagnostics status` checks local diagnostics storage. Diagnostics export is disabled by default. +- `SZR_SESSION= szr ` shares deduplication and delta history across agents in one session. + +See [Integrations](INTEGRATIONS.md) for the stable event contract and routing details. + +## Full command catalog + +Run `szr commands` for the complete command list on the version installed on your machine. Useful commands include: + +| Command | Purpose | +| --- | --- | +| `szr profiles` | List the built-in and user-defined profiles. | +| `szr doctor --json` | Return runtime diagnostics in JSON. | +| `szr self doctor --refresh` | Check the installation and refresh the release check. | +| `szr settings` | Change local preferences interactively. | +| `szr diagnostics purge --yes` | Explicitly remove local diagnostics data. | From d4512ad482b0b83c0faa5314d9b6c48f08ed5b10 Mon Sep 17 00:00:00 2001 From: Alex Wilkerson John Date: Thu, 23 Jul 2026 20:20:57 -0400 Subject: [PATCH 2/4] docs: clarify getting started guidance --- README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b6b4beb..57194b7 100644 --- a/README.md +++ b/README.md @@ -83,16 +83,23 @@ szr self doctor ## Get started -Put `szr` in front of a command you already run: +Use the commands you already know—just add `szr` at the beginning. ```bash +# Instead of: git status szr git status + +# Instead of: git diff szr git diff + +# Instead of: go test ./... szr go test ./... + +# Instead of: find . --name "*.py" szr find . --name "*.py" ``` -`szr` returns the same exit code as the command it runs. If a shorter result would lose important information, it shows the original output instead. +Your command still succeeds or fails exactly as it normally would. szr only makes the output easier to scan; if it cannot safely shorten something, it shows the original output. ## Main commands From 1839bdf19ffd690150314e6956cecbeff3eea072 Mon Sep 17 00:00:00 2001 From: Alex Wilkerson John Date: Thu, 23 Jul 2026 20:21:24 -0400 Subject: [PATCH 3/4] docs: lead with AI integration workflow --- README.md | 33 +++++++++++---------------------- 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 57194b7..6b6660d 100644 --- a/README.md +++ b/README.md @@ -83,23 +83,25 @@ szr self doctor ## Get started -Use the commands you already know—just add `szr` at the beginning. +If you use an AI coding assistant, set up its integration and it can use szr while it works: ```bash -# Instead of: git status -szr git status +# Choose the assistant you use: +szr install codex +``` -# Instead of: git diff -szr git diff +Other options: `szr install claude-code`, `szr install cursor`, or `szr install gemini`. Use `szr uninstall ` to remove an integration. The [user guide](docs/USER_GUIDE.md#ai-tool-integrations) explains what each setup changes. -# Instead of: go test ./... -szr go test ./... +If you work directly in a terminal, you can also use szr yourself by adding it before a command: -# Instead of: find . --name "*.py" +```bash +szr git status +szr git diff +szr go test ./... szr find . --name "*.py" ``` -Your command still succeeds or fails exactly as it normally would. szr only makes the output easier to scan; if it cannot safely shorten something, it shows the original output. +Whether you or an assistant runs it, szr keeps the command's normal success or failure result. It only makes the output easier to scan; if it cannot safely shorten something, it shows the original output. ## Main commands @@ -112,19 +114,6 @@ Your command still succeeds or fails exactly as it normally would. szr only make | `szr self doctor` | Check your installation, configuration, and updates. | | `szr settings` | Open interactive local settings. | -## Works well with AI tools - -Set up your preferred assistant with one command: - -```bash -szr install codex -szr install claude-code -szr install cursor -szr install gemini -``` - -Use `szr uninstall ` to remove an integration. See the [user guide](docs/USER_GUIDE.md#ai-tool-integrations) for what each integration changes. - ## Learn more - [User guide](docs/USER_GUIDE.md) — advanced commands, integrations, history, diagnostics, and updates From ceae983e409e4b167b1a6d5c43c8c7a5eca87640 Mon Sep 17 00:00:00 2001 From: Alex Wilkerson John Date: Thu, 23 Jul 2026 20:24:47 -0400 Subject: [PATCH 4/4] docs: organize README around onboarding steps --- README.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6b6660d..69f8bb8 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ It is useful whether you are working in a terminal yourself or asking an AI coding tool to help. -## Install +## 1. Install szr Choose the option that fits your setup, then run `szr self doctor` to check that everything is ready. @@ -81,9 +81,9 @@ szr self doctor -## Get started +## 2. Connect szr to your agent -If you use an AI coding assistant, set up its integration and it can use szr while it works: +Choose the coding agent you use. This lets it use szr while it works: ```bash # Choose the assistant you use: @@ -92,7 +92,9 @@ szr install codex Other options: `szr install claude-code`, `szr install cursor`, or `szr install gemini`. Use `szr uninstall ` to remove an integration. The [user guide](docs/USER_GUIDE.md#ai-tool-integrations) explains what each setup changes. -If you work directly in a terminal, you can also use szr yourself by adding it before a command: +## 3. Use szr + +Your agent can now use szr when it runs terminal commands. If you work directly in a terminal, add `szr` before a command yourself: ```bash szr git status @@ -103,6 +105,17 @@ szr find . --name "*.py" Whether you or an assistant runs it, szr keeps the command's normal success or failure result. It only makes the output easier to scan; if it cannot safely shorten something, it shows the original output. +## 4. See what you saved + +After using szr, check how much output and how many tokens it has saved: + +```bash +szr spread +szr usage +``` + +`szr spread` shows savings from terminal output. `szr usage` compares that with the token usage recorded by supported local AI-agent sessions. + ## Main commands | Command | What it does |