{
  "markdown": "<p align=\"center\">\n  <img src=\"docs/logo.png\" alt=\"turo\" width=\"480\">\n</p>\n\n<p align=\"center\">\n  <strong>Point more. Token less.</strong>\n</p>\n\nA real instruction block — **150 tokens** (cl100k):\n\n```\nWhen you are reviewing a pull request, please make sure that you carefully\nexamine each of the changed files and verify that the new code does not\nintroduce any regressions in the existing behavior. Missing tests lead to\nuntested code which produces subtle breaks that are difficult to debug later,\nso check whether the author has added appropriate tests for the new\nfunctionality. Updated docs and clear commit messages result in easier review;\nconfirm that the documentation has been updated to reflect the changes and that\nthe commit messages explain what was changed and why. Security issues such as\nunsanitized user input or hardcoded credentials cause real risk, so you must\nflag them immediately — that request results in changes before the pull request\ncan be merged.\n```\n\nbecomes **48 tokens — 68% fewer** (`turo`, default `--level ultra`), with\ncausal chains reduced to `->`:\n\n```\nReview pull request make change file verify code bring act exist\nbehavior miss test -> untested -> break debug later check author add\nupdated docs commit message -> easier confirm documentation reflect\nsecurity issue unsanitized user input hardcoded -> real risk must flag\n-> merge\n```\n\nor **59 tokens — 61% fewer** at `--level full` (adjectives kept, no lemma collapse):\n\n```\nReviewing pull request make changed files verify new code bring\nregressions existing behavior missing tests -> untested -> subtle\nbreaks debug later check author added appropriate functionality\nupdated docs clear commit messages -> easier review confirm\ndocumentation reflect changes explain security issues unsanitized user\ninput hardcoded credentials -> real risk must flag -> merged\n```\n\nor **121 characters** with `--level wenyan`, which additionally swaps each\nword for a single Classical Chinese character (for CJK-tokenizer models — see\n[wenyan](#wenyan-cjk-tokenizer-models-only)):\n\n```\n閱引請作變檔驗碼 bring act 存為 miss 試 -> untested -> 破診後查者增更 docs 交訊 -> easier 證文映安題 unsanitized 戶入 hardcoded -> real risk 須標 -> 併\n```\n\n775 → 121 characters (30 Han chars). Token counts for that output:\n\n| tokenizer | tokens |\n|-----------|--------|\n| Qwen / DeepSeek / GLM (~1 per Han char) | **~45** |\n| OpenAI cl100k (2–3 per Han char) | 77 |\n\nSo wenyan is competitive on CJK-tokenizer models (~45) but loses on OpenAI\n(77 vs ultra's 48) — use it only with CJK models. See below.\n\nNo articles. No prepositions. No adverbs. No repeated words. Only the content\nwords that carry meaning, deduplicated, in reading order. Every prompt, every\nturn — the savings compound. If a reduction is not smaller than the input, turo\npasses the original through unchanged.\n\nInstall turo once and any coding agent that can shell out to a binary — Claude Code, Codex, Gemini, Cursor, Windsurf, Cline, Copilot, and 20+ more — pipes its context through the same reducer. Code, paths, and identifiers pass through untouched.\n\n## Install\n\n| Method | Command |\n|--------|---------|\n| **Homebrew** | `brew install kdeps/tap/turo` |\n| **Go** | `go install github.com/kdeps/turo@latest` |\n| **Shell** | `curl -fsSL https://raw.githubusercontent.com/kdeps/turo/main/install.sh \\| sh` |\n| **Manual** | Download from [releases](https://github.com/kdeps/turo/releases) |\n\n## Quick start\n\n```bash\nbrew install kdeps/tap/turo   # or any method above\nturo run claude               # launch your agent with every request reduced —\n                              # base URL wired for you, 60-90% fewer input tokens\nturo doctor                   # verify the install + agent wiring\nturo gain                     # tokens saved so far\n```\n\n`turo run <agent>` is the everyday driver: it starts an in-process proxy, points\nthe agent's base-URL env var at it, and reduces every request — no config, no API\nkeys touched. Run `turo run` to list supported agents ([details below](#proxy--reduce-every-request-for-any-agent)).\n\n**Flag order** for `run`: turo flags go *before* `run`, agent flags go *after*\nthe agent name — everything after the agent is forwarded as-is:\n\n```bash\nturo [turo-flags] run <agent> [agent-args...]\n\nturo -level ultra -proxy-verbose run claude --dangerously-skip-permissions\nturo -proxy-safe-mode=false run claude --model sonnet -p \"review this PR\"\nturo -arrows=false run codex --full-auto\n```\n\nThe flags below are for tuning or one-off pipe use.\n\n## Usage\n\n```bash\ncat CLAUDE.md | turo              # text -> deduped content words\necho \"fox jumps over dog\" | turo  # pipe mode\nturo -passes 1                    # single pass (default runs to convergence)\nturo -filler=false                # skip filler deletion\nturo -synonyms=false              # skip the synonym pass (keep words verbatim)\nturo -gloss=false                 # skip the defining-word swap (less lossy)\nturo -defmatch=false              # keep definition-like phrases (skip the phrase -> headword swap)\nturo -arrows=false                # keep connectives verbatim (skip multi- and single-word -> swaps)\nturo -special=false               # strip specials from tokens (C++/$5/array[0] stay intact by default)\nturo gain                         # estimated tokens saved so far\nturo gain --history               # per-reduction history, newest first\nturo gain --json                  # same totals as JSON for scripts/dashboards\nturo discover                     # tokens turo could save on your Claude Code history\nturo discover --json              # discover totals as JSON\nturo doctor                       # health check: version, settings, paths, agent wiring\nturo --version                    # print version\nturo -level ultra run claude --dangerously-skip-permissions   # turo flags before run; agent args after\n```\n\n`-gloss` (on by default) replaces each word with the shortest\nsame-part-of-speech word from its own dictionary definition (`approach` ->\n`come`). Definitions are prose, not synonyms, so it is the lossiest stage —\ndisable it with `-gloss=false` / `TURO_GLOSS=off` when you need words closer to\nthe original.\n\n`-defmatch` (on by default) runs the gloss trade in reverse: where `-gloss`\nswaps a word for one of its defining words, `-defmatch` collapses a whole\ndefinition-like phrase into the word it defines (`the state of disorder and\nlawlessness` -> `anarchy`). It slides a 2–6 word window and replaces only when\nevery keyword of a headword's definition is present, any surplus word is a bland\ncarrier noun (`person`, `state`, `thing`), and the headword is strictly cheaper\nin tokens. Those gates are strict by design: on technical text it makes **zero**\nreplacements — README output here is byte-identical with it on or off — for\n~315 KB of generated tables and ~2 ms per reduction. It earns its keep on\nnatural prose. Disable with `-defmatch=false` / `TURO_DEFMATCH=off`.\n\nStage order matters, and the pipeline runs phrase-level stages before word-level\nones: arrows, then filler deletion, then `-defmatch`, then `-gloss`, then\n`-synonyms`, then the reduction to content words. A phrase matcher has to see the\nphrase — one gloss swap inside it (`disorder` -> something shorter) is enough to\nlose the match. Headwords `-defmatch` produces are then held back from the\nlater swaps, which would otherwise walk the match straight back (`anarchy` ->\n`law`, inverting it). Between the two word-level swaps the ordering is close to a\nwash on any single document — gloss-first is one token cheaper across a full\nREADME — but a sweep of all 120 stage permutations over mixed corpora puts every\ngloss-before-synonyms order in the cheapest tier, three tokens ahead of the\ninverse. Arrow and filler placement is free; only the two phrase-then-word\nconstraints (defmatch before gloss, gloss before synonyms) cost anything.\n\n`-special` (on by default) preserves whitespace-delimited tokens that contain\nspecial characters so the reducer cannot strip their punctuation or operators:\n\n```text\ncost is $5.00 (50%)     =>  Cost $5.00 (50%)\nC++ and C# rocks        =>  C++ C# rock\narray[0] and map[\"k\"]   =>  array[0] map[\"k\"]\nx = y + z * 2           =>  X = y + z * 2\nuse #hashtag and @user  =>  Use #hashtag @user\n```\n\nPlain words still reduce; only tokens with non-alphanumeric marks (`$`, `%`,\n`[]`, `{}`, operators, `_`, `@`, `#`, unicode symbols, …) are shielded. Single-\nletter non-stopword identifiers (`x`, `y`, `i`) are also kept so expressions\nstay coherent. Disable with `-special=false` / `TURO_SPECIAL=off` for maximum\ncompression when symbols do not matter.\n\n`-arrows` (on by default) rewrites causal, sequential, and transformation\nconnectives to a single `->` token the reducer keeps between surviving content\nwords. The table is **440** entries:\n\n- **Multi-word** (338) always save tokens: `leads to`, `results in`,\n  `gives rise to`, `which produces`, `brings about`, `culminates in`,\n  `paves the way for`, `followed by`, `falls back to`, `compiles to`,\n  `evaluates to`, `desugars to`, `resolves to`, `defaults to`,\n  `is rewritten as`, …\n- **Single-word** (102) normalize vocabulary so later stages see one form:\n  `therefore`, `thus`, `hence`, `becomes`, `yields`, `triggers`, `implies`,\n  `spawns`, `generates`, `enables`, … Bare `so` / `then` stay literal (too\n  common to rewrite safely).\n\nLongest match wins. Reverse-causal phrases that name the cause *after* the\neffect (`due to`, `because of`, `stems from`, `caused by`, `driven by`) are\nexcluded — and single-word verbs do not fire when followed by `by`/`from` —\nso an arrow never points the wrong way. Disable with `-arrows=false` /\n`TURO_ARROWS=off`.\n\n```text\nA cache miss leads to a slow query which produces a timeout\n  =>  Cache miss -> slow query -> timeout\n\nTimeout causes Retry and therefore Backoff\n  =>  Timeout -> Retry -> Backoff\n\ndefaults to zero\n  =>  -> zero\n\ncompiles to bytecode\n  =>  -> bytecode\n\nevaluates to true\n  =>  -> true\n\nthe call falls back to the cache\n  =>  Call -> cache\n\nthe macro desugars to a loop\n  =>  Macro -> loop\n\nthe outage caused by a bad deploy\n  =>  Outage -> bad deploy\n```\n\n## Savings — `turo gain`\n\nEvery reduction (pipe mode, the proxy, and `turo run`) appends an estimated\nbefore/after token count to a JSONL log in your OS config dir\n(`~/Library/Application Support/turo/` on macOS, `~/.config/turo/` on Linux;\noverride with `TURO_HOME`). `turo gain` totals it up; `turo gain --history` lists\nrecent reductions newest-first.\n\nProxy events count **every** text field the proxy considered: reduced fields\ncontribute their compressed size, and fields left unreduced (`-proxy-safe-mode`\ntool I/O / tables / code, or ineligible roles) contribute the same count to\nboth sides. That keeps `tokens saved` and the percentage honest against the\nfull request — safe mode cannot inflate % by omitting large passthrough blobs.\n\nCounts of 1 000+ print with a magnitude suffix (`k` / `m` / `g` / `t`);\nsmaller values stay plain integers.\n\n```text\nturo gain — 42 reductions\n  tokens in     8.14k\n  tokens out    2.61k\n  tokens saved  5.53k (67%)\n\nby folder:\n  ~/Projects/turo        31 reductions  saved 4.1k (69%)\n  ~/Projects/api          11 reductions  saved 1.43k (61%)\n```\n\nEach event also records the working folder it ran in, so `turo gain` breaks the\nsavings down per project (busiest first) and `turo gain --history` shows the\nfolder for each reduction.\n\nAdd `--json` to either command for the same numbers in machine form — totals,\nraw (un-abbreviated) token counts, integer percentages, and the per-folder\nbreakdown — so you can pipe savings into a dashboard, a CI check, or `jq`:\n\n```console\n$ turo gain --json | jq '.tokens_saved, .saved_pct'\n5530\n67\n```\n\nCounts are estimates from the built-in `cl100k`-style approximation, not a real\ntokenizer — treat them as a trend, not a bill.\n\n## Missed savings — `turo discover`\n\n`turo gain` totals reductions that happened. `turo discover` shows the ones that\ndidn't: it scans your existing Claude Code history and estimates how many tokens\nturo would have saved had those sessions run through the proxy.\n\nCounts use the same `k` / `m` / `g` / `t` suffixes as `turo gain`.\n\n```text\nturo discover — scanned 403 sessions in ~/.claude/projects\n  messages       53.01k reducible (all roles)\n  tokens in      13.52m\n  would be out   6.25m\n  would save     7.28m (53%)\n\nby project:\n  ~/Projects/api          29.49k msgs  saved 3.24m (49%)\n  ~/Projects/web          19.94k msgs  saved 3.14m (57%)\n\nthese sessions ran without turo — capture the savings next time with:\n  turo run claude\n```\n\nIt reads the per-project session logs under `~/.claude/projects` (set\n`CLAUDE_CONFIG_DIR` if Claude Code stores them elsewhere), applying the same role\ngating and compression flags (`-level`, `-filler`, `-gloss`, `-arrows`,\n`-proxy-all`) as the proxy — so the estimate reflects what `turo run claude`\nwould actually do. Nothing is sent anywhere; the scan is local and read-only.\n\n## Health check — `turo doctor`\n\n`turo doctor` runs a local health check and exits non-zero if anything is\nbroken — useful in CI, install scripts, or after an upgrade to confirm turo is\nwired up correctly.\n\nEvent counts, session totals, and the self-test token figures use the same\n`k` / `m` / `g` / `t` magnitude suffixes as `turo gain` (values under 1 000 stay\nplain integers — e.g. `22 -> 5`).\n\n```text\nturo doctor\n\nturo\n  · version dev (unreleased build)\n  · binary /usr/local/bin/turo\n  ✓ default level ultra (all roles)\n\nenvironment\n  · no turo env overrides set (using defaults)\n\ngain log\n  ✓ writable: ~/Library/Application Support/turo/gain.jsonl (3.03k events)\n\nclaude history (turo discover source)\n  ✓ 420 session logs in ~/.claude/projects\n\npipeline self-test\n  ✓ 22 -> 5 tokens (77% smaller) at level ultra\n\nagents\n  ✓ Claude Code — detected, skill installed\n  ✓ opencode — detected, skill installed\n  · Gemini CLI — detected\n  · Cursor — detected\n  · Qwen Code — detected\n  · 5 of 18 supported agents detected (turo -list-agents shows all)\n\nturo is healthy\n```\n\nWhat it checks:\n\n| Section | What it verifies |\n|---------|-----------------|\n| **turo** | Version string, binary path, default level validity |\n| **environment** | Lists any `TURO_*` env overrides that are set |\n| **gain log** | Gain directory creatable, log file writable, event count (`N{k,m,g,t}`) |\n| **claude history** | Session logs found under `~/.claude/projects` (`N{k,m,g,t}`) |\n| **pipeline self-test** | Runs `reduce()` on a sample sentence, confirms token count decreased |\n| **agents** | Detects installed coding agents, checks skill installation for native agents |\n\nPass `-level <name>` to test a specific level; an invalid level is reported as a\nproblem (✗) rather than a hard exit, so the full report is still visible.\n\n```bash\nturo doctor               # healthy -> exit 0\nturo -level bogus doctor  # invalid level -> exit 1\n```\n\n## Pipeline\n\nEvery run is six stages, each on by default, phrase-level before word-level.\nStage separators below are `|` — the rewrite token `->` only appears inside stage 1.\n\n```text\ntext\n  | [1] arrow rewrite (connectives => ->)\n  | [2] delete filler\n  | [3] phrase to headword\n  | [4] swap defining words\n  | [5] swap cheaper synonyms\n  | [6] reduce to content words\n  | (stage 1 re-runs after each of 2–6 so new connectives still become ->)\n```\n\n1. **Arrow rewrite** replaces causal/sequential/transformation connectives\n   (multi-word *and* single-word: `leads to`, `therefore`, `becomes`,\n   `falls back to`, …) with a single `->` token. It runs at the start of each\n   pass **and again after stages 2–6**, so connectives those stages reveal still\n   become arrows; adjacent `->` runs and stopword-only gaps (`-> and ->`) are\n   collapsed so you never get `-> -> ->` artifacts. Reverse-causal phrases\n   (`caused by`, `due to`) stay put. Disable with `-arrows=false` /\n   `TURO_ARROWS=off`.\n2. **Filler deletion** removes pleasantries, hedges, and leaders that survive\n   word-level stopword lists (`please`, `I think`, `of course`, `let me`),\n   while protecting code, paths, URLs, and identifiers verbatim. Disable with\n   `-filler=false` / `TURO_FILLER=off`.\n3. **Definition match** collapses a definition-like phrase into the word it\n   defines (`the state of disorder and lawlessness` -> `anarchy`). Disable with\n   `-defmatch=false` / `TURO_DEFMATCH=off`.\n4. **Gloss swap** replaces words with the shortest defining word from their\n   dictionary definition — the lossiest stage. Disable with `-gloss=false` /\n   `TURO_GLOSS=off`.\n5. **Synonym swap** replaces words with a fewer-token synonym (see below).\n   Disable with `-synonyms=false` / `TURO_SYNONYMS=off`.\n6. **Reduction** drops the remaining stopwords, keeps content words by part of\n   speech, deduplicates, and (ultra) collapses inflections by lemma.\n\nHeadwords stage 3 produces are held back from stages 4 and 5, which would\notherwise swap the match straight back (`anarchy` -> `law`, inverting it).\n\nThe whole pipeline repeats until the output stops changing (`-passes 0`, the\ndefault; a positive `-passes N` caps the count). The first pass keeps document\nstructure (headings, per-section bodies); later passes flatten that and dedupe\nacross it, so large structured docs keep shrinking before converging — this\nREADME goes ~4.9k (1 pass) → ~4.83k tokens (converged, estimateTokens). Set\n`-passes 1` to keep it single-shot.\n\nturo never emits output larger than the input: if a stage does not save tokens,\nthe text passes through unchanged.\n\n\n### Synonym substitution (on by default, lossy)\n\nturo runs a first pass that replaces each word with a fewer-token synonym before\nreducing (`utilize` -> `use`, `demonstrate` -> `show`). The table is built from\n**WordNet synsets** (real synonyms) and frequency-filtered so swaps land on\ncommon words, then gated to same-part-of-speech words and validated to cost\nstrictly fewer tokens. turo still passes the original through if the result is\nnot smaller.\n\nDisable it with `-synonyms=false` or `TURO_SYNONYMS=off` when you need words\nverbatim. The gain is usually small — modern tokenizers\nalready encode most words as a single token. WordNet polysemy also leaves some\nnoise (`leverage` -> `purchase`), so keep it opt-in for prose, not code. The\ntable is generated by `tools/gensyn.py` (WordNet + wordfreq + the cl100k\ntokenizer), so token counts are measured for cl100k, not the target model's\ntokenizer.\n\n## Intensity levels\n\n| Level | What it keeps | Reduction (demo block) |\n|-------|--------------|------------------------|\n| **lite** | Adjectives, nouns, verbs, and leftover adverbs/prepositions | ~58% (63 tok) |\n| **full** | Adjectives, nouns, verbs | ~61% (59 tok) |\n| **ultra** (default) | Nouns and verbs only, deduplicated by lemma (base form) | ~68% (48 tok) |\n| **wenyan** | ultra, then swap surviving words for a single 文言 (Classical Chinese) character | CJK models only |\n\n```bash\necho \"the quick brown fox jumps over the lazy dog\" | turo --level lite   # quick brown fox jumps over lazy dog\necho \"the quick brown fox jumps over the lazy dog\" | turo --level full   # quick brown fox jumps lazy dog\necho \"the quick brown fox jumps over the lazy dog\" | turo --level ultra  # fox jump dog\necho \"the wise king studies the old book\" | turo --level wenyan    # 智王學舊書\n```\n\n### wenyan (CJK-tokenizer models only)\n\n`wenyan` reduces at ultra, then swaps each surviving English content word\nfor one Classical Chinese character (`water` -> `水`, `king` -> `王`, `verify` ->\n`驗`) from a ~480-entry hand-curated lexicon. One char per concept, no spaces\n(Classical Chinese has none).\n\nTwo examples, measured:\n\n| input | ultra | wenyan | chars | cl100k | CJK-model (~1/char) |\n|-------|-------|--------------|-------|--------|----------------------|\n| `The wise king uses water and fire so the person can see the hill and the old tree` (81 ch / 18 tok) | `Wise king use water fire person see hill old tree` (49 ch / 11 tok) | `智王用水火人見 hill 舊樹` | **15** | 16 | **~10** |\n| the PR-review paragraph (775 ch / 150 tok) | 281 ch / 48 tok | `閱引請作變檔驗碼 bring act 存為 miss 試 -> untested -> 破診後查者增更 docs 交訊 -> easier 證文映安題 unsanitized 戶入 hardcoded -> real risk 須標 -> 併` | **121** | 77 | **~45** |\n\nIt collapses to the fewest **characters** (775 → 121 on the paragraph). A CJK\ncharacter is 2–3 tokens on OpenAI's cl100k, so `wenyan` is *larger* there\n(77 > 48). **Use it only on CJK-optimized tokenizers** (Qwen, DeepSeek, GLM),\nwhere a common character is ~1 token — then those 121 chars are ~45 tokens\n(competitive with ultra). Don't use it with OpenAI models.\n\nturo's own token estimator counts CJK as 1 rune = 1 token (matching those\nmodels), so it treats `wenyan` as a reduction and never rejects it. Words\noutside the lexicon stay English (`untested`, `unsanitized`, `hardcoded`\nabove); code/paths/URLs are preserved verbatim. Extend `wenyanMap` for more\ncoverage.\n\nIn **ultra**, inflections of the same word collapse to one token by their\ndictionary base form: `goes`, `went`, `going` -> `go`; `children` -> `child`;\n`servers` -> `server`. A reduction is only applied when it lands on a real\ndictionary word, so no mangled non-words are ever emitted.\n\nSet default via `TURO_LEVEL` env var.\n\n## Proxy — reduce every request for any agent\n\nTo compress **all** input for an agent that turo can't reach from the inside\n(Claude Code, Codex, ...), route the agent's requests through turo.\n\n### `turo run` — launch an agent with everything reduced (turnkey)\n\n```bash\nturo run claude          # every claude request reduced, base URL wired for you\nturo run codex           # OPENAI_BASE_URL wired instead\nturo run grok            # GROK_CLI_CHAT_PROXY_BASE_URL -> cli-chat-proxy.grok.com\nturo run                 # list supported agents\n```\n\n`turo run` starts an in-process proxy on a free port, points the agent's\nbase-URL env var at it (`ANTHROPIC_BASE_URL` for claude, `OPENAI_BASE_URL` for\nOpenAI-compatible agents, `GROK_CLI_CHAT_PROXY_BASE_URL` for Grok Build), execs\nthe agent, and stops the proxy when it exits. One command, no exports, no\n`/turo` inside the agent. Supported: `claude`, `codex`, `opencode`, `qwen`,\n`aider`, `crush`, `goose`, `amp`, `grok`.\n\n#### Passing flags to turo and to the agent\n\nShape:\n\n```text\nturo [turo-flags] run <agent> [agent-args...]\n```\n\n- **turo flags** (`-level`, `-proxy-verbose`, `-proxy-safe-mode=false`,\n  `-arrows=false`, …) must come **before** `run`. Go’s flag parser stops at the\n  first non-flag word, so `turo run -level ultra claude` does *not* set the level.\n- **Agent args** are everything after the agent name — forwarded unchanged to\n  the agent binary (Claude Code, Codex, …).\n\n```bash\n# turo: ultra + verbose proxy logs\n# claude: skip its permission prompts\nturo -level ultra -proxy-verbose run claude --dangerously-skip-permissions\n\n# turo: also squeeze tool I/O / code (safe mode is on by default)\n# claude: model + a one-shot prompt\nturo -proxy-safe-mode=false run claude --model sonnet -p \"summarize the diff\"\n\n# turo defaults + codex full-auto\nturo run codex --full-auto\n```\n\n`-level`, `-filler`, `-synonyms`, `-gloss`, `-defmatch`, `-arrows`, `-markdown`,\n`-proxy-all`, `-proxy-verbose`, `-proxy-safe-mode`, and `-upstream` all apply to\n`run` the same way they do to `-proxy`.\n\n### `turo -proxy` — the proxy on its own\n\n```bash\nturo -proxy -upstream https://api.openai.com   # silent by default, listens on 127.0.0.1:8787\nturo -proxy -proxy-verbose                      # print activity: token summary + before -> after text\nturo -proxy -proxy-all=false                    # reduce only user + tool, not every role\nturo -proxy -proxy-safe-mode=false             # also reduce tool I/O + code/tables (safe mode on by default)\nexport OPENAI_BASE_URL=http://127.0.0.1:8787/v1\n```\n\nEvery `/chat/completions`, Anthropic `/messages`, and OpenAI Responses\n`/responses` (Grok Build) request has its message content reduced before it\nreaches the real endpoint; the response streams back untouched. By default\n**every role** is reduced (`-proxy-all` is on); pass `-proxy-all=false` to\nreduce only `user` and `tool` content and leave system and assistant history\nverbatim. Auth headers pass through; non-chat paths are forwarded unchanged.\n\n`-proxy-safe-mode` (on by default) is **content-shaped**, not role-shaped:\n\n- **Always pass through** tool *calls* (`tool_use` / `function_call` args and\n  similar machinery) — those are JSON the agent must parse byte-for-byte.\n- **Tool results and other text** (including `role: tool`, `tool_result`,\n  `function_call_output`) are inspected with `isStructured`. Pure prose still\n  reduces fully. When a field is structured, **protected spans** (code fences,\n  tables, shell transcripts, stack traces, JSON, diffs, build/test logs, and\n  other machine dumps) stay byte-identical, while **prose around them still\n  reduces** — so a mixed “here’s the dump… `$ go test` … please fix the\n  approach” blob shrinks the intro/outro without scrambling the transcript.\n\nDisable with `-proxy-safe-mode=false` / `TURO_SAFE_MODE=off` to reduce every\neligible field regardless of shape (including inside dumps). Unreduced spans\nstill count toward `turo gain` (before = after for those spans) so reported\nsavings reflect the whole request.\n\nTransient upstream failures (`502`, `503`, `504`, `529`) are retried by the proxy\nitself — up to 3 attempts, waiting for the upstream's `Retry-After` when it sends\none and backing off exponentially (1s to 30s) when it does not.\n\nRate limits (`429`) are **not** retried: they pass straight through with\n`Retry-After` intact. The agent runs its own limiter and retries the whole\nrequest regardless, so retrying inside the proxy just multiplies attempts\n(proxy attempts × agent attempts) against a limit that is already closed. For\nthe same reason, a `Retry-After` longer than the 30s ceiling is handed back\nrather than clamped down to an early retry that is certain to fail again.\n\nRetries are logged to stderr even in silent mode; every other status, including\n`401`/`400`, passes straight through untouched.\n\nThe proxy is **silent by default**. Pass `-proxy-verbose` to print its activity:\nthe estimated `before -> after` token count per request plus each message's text\nbefore and after (truncated for the terminal). The flag also applies to\n`turo run <agent>`.\n\nkdeps does not need this: in agent mode it already pipes the preamble, input,\ntool results, and history through turo before every call.\n\n## Integration\n\n> ⚠️ **Name collision**: `turo` is also a car-sharing service and an unrelated\n> npm package — `npx turo` does **not** install this tool. Install the binary\n> from source or the tap, and confirm `which turo` points at the kdeps/turo\n> binary before wiring it into an agent.\n\n```bash\nbrew install kdeps/tap/turo          # or: go install github.com/kdeps/turo@latest\n```\n\nThe binary registers its own skill + `/turo` command with every coding agent it\nfinds on your machine — Claude Code, Gemini CLI, opencode, Codex, Cursor,\nWindsurf, Cline, Copilot, and 20+ more. Install once; every agent gets the same\nreducer.\n\n```bash\nturo -install-agents           # register with detected agents\nturo -install-agents -all      # register with every supported agent, detected or not\nturo -list-agents              # show every supported agent and its status\n```\n\nUnder the hood each agent gets one of:\n\n- **Claude Code / opencode** — the skill and `/turo` command are copied into the agent's config dir\n- **Gemini CLI** — `gemini extensions install`\n- **everything else** — the skill file is written into the agent's own config dir\n\nOnce turo is on PATH, any agent can also pipe context through it directly:\n\n```bash\ncat CLAUDE.md | turo               # compact system prompt\ncat error.log | turo               # reduce log output\n```\n\nSet `TURO_LEVEL=ultra` for maximum compression. `KDEPS_TURO=off` or `TURO_DISABLED=1` to disable.\n\n## What it does NOT touch\n\n- Code blocks and inline code — passed through unchanged\n- URLs, file paths, version numbers — verbatim\n- Technical terms (API names, CLI commands, error strings) — exact\n\n## How it works\n\n1. Embedded English dictionary (120k words, 14MB) classifies every word\n2. Strips articles, prepositions, conjunctions, pronouns (~70 stop words)\n3. Keeps the content words for the level (nouns, verbs, adjectives)\n4. Deduplicates and emits them in reading order — then keeps the result only if it is actually smaller than the input\n\n## turo vs caveman\n\n[caveman](https://github.com/JuliusBrussee/caveman) is a sibling idea with the\nopposite dial. caveman deletes filler with regex (articles, pleasantries,\nhedges) and **keeps readable prose**. turo runs that same filler pass, then\nkeeps going — POS-classifying, deduplicating, lemmatizing, and swapping words\nfor shorter synonyms and glosses — trading readability for a much smaller token\ncount.\n\nSame input, measured with the cl100k tokenizer:\n\n| | output | tokens |\n|--|--------|--------|\n| input | `Please, I think you should really just utilize this approach to demonstrate the functionality of the component.` | 19 |\n| caveman | `You should utilize this approach to demonstrate functionality of component.` | 11 |\n| turo full | `Come show functionality component` | 4 |\n| turo ultra | `Come show component` | 3 |\n\n|  | caveman | turo |\n|--|---------|------|\n| method | regex filler removal | dict POS + dedup + lemma + synonyms + gloss |\n| output | readable prose | keyword stream |\n| dictionary / WordNet | no | yes |\n| synonym / gloss swaps | no | yes (on by default) |\n| best when | you still need to read it | you only feed it to an LLM |\n\nUse caveman when a human reads the result; use turo when only a model does.\n\n## Why\n\nAgent context — system prompt, `CLAUDE.md`, skills, tool schemas — runs tens of\nthousands of tokens before your first message, and it is resent every turn. Most\nof the prose in it carries grammar, not meaning. Turo points at what matters and\ndrops the rest.\n\nTuro reduces the prose parts (instructions, skills, docs, logs). It does not\ntouch tool-call JSON schemas — those have to parse.\n\nPoint more. Token less.\n",
  "bytes": 30041,
  "sha": "10dfef71facb669db5ab261efa60396a03e304e510bb40e491812c2c8a3cf0cd",
  "repo_slug": "kdeps/turo",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_kdeps_turo_2a964990/readme"
}