{"id":50490172,"url":"https://github.com/mikkoparkkola/ultracos","last_synced_at":"2026-06-02T02:01:13.187Z","repository":{"id":361944478,"uuid":"1255440671","full_name":"MikkoParkkola/ultracos","owner":"MikkoParkkola","description":"Lossless, on-device token-cost reduction for Claude Code and LLM coding agents. Free plugin: compresses tool-result output, dedups context, compacts the system prompt — stacks on Anthropic prompt caching. Rust hot path, Python fallback, fail-open. PolyForm Noncommercial.","archived":false,"fork":false,"pushed_at":"2026-06-02T00:10:28.000Z","size":3656,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T00:21:10.313Z","etag":null,"topics":["agentic","ai-agents","anthropic","claude","claude-code","context-compression","cost-optimization","developer-tools","llm","llm-tools","mcp","prompt-compression","rust","token-compression","token-optimization"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MikkoParkkola.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T20:40:23.000Z","updated_at":"2026-06-02T00:10:31.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MikkoParkkola/ultracos","commit_stats":null,"previous_names":["mikkoparkkola/ultracos"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/MikkoParkkola/ultracos","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikkoParkkola%2Fultracos","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikkoParkkola%2Fultracos/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikkoParkkola%2Fultracos/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikkoParkkola%2Fultracos/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MikkoParkkola","download_url":"https://codeload.github.com/MikkoParkkola/ultracos/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikkoParkkola%2Fultracos/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33802170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai-agents","anthropic","claude","claude-code","context-compression","cost-optimization","developer-tools","llm","llm-tools","mcp","prompt-compression","rust","token-compression","token-optimization"],"created_at":"2026-06-02T02:01:12.395Z","updated_at":"2026-06-02T02:01:13.179Z","avatar_url":"https://github.com/MikkoParkkola.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UltraCoS — token-cost reduction for Claude Code\n\nUltraCoS is a Claude Code plugin that lowers token cost across a session without\nchanging what the agent can see. It compacts tool-result output, removes repeated\ncontent, and steers compaction toward a dense form — all **lossless by meaning**,\n**fail-open** (any error passes the original through untouched), and fast (a\nprebuilt native binary on the hot path, Python as the portable fallback).\n\nIt is **dogfooded in production daily** — the author runs it on their own Claude\nCode traffic — and only recently open-sourced. Lossless-by-meaning and fail-open\nare not aspirations; they are how it has had to behave to stay on every session.\n\nIt is free for noncommercial use (PolyForm Noncommercial 1.0.0); commercial use\nneeds a paid license — see [COMMERCIAL.md](COMMERCIAL.md).\n\n---\n\n\u003e **Your agent's tool output is mostly noise** — ANSI codes, repeated reads,\n\u003e machine chatter, verbose compaction summaries. UltraCoS strips it **losslessly,\n\u003e on-device, before it bills** — and stacks *on top of* Anthropic's prompt cache.\n\n| Measured | Reduction | On |\n|---|---:|---|\n| Tool-heavy session corpus (52 real fixtures) | **−31.7%** | total tokens 85,405 → 58,347 (`chars/4` proxy) |\n| Large `Bash` dumps | **−71.1%** | the noisiest payloads |\n| Instruction prose in the ULTRACOS-L1 dialect | **−44.6%** | every cached system-prompt call (Claude Opus tokens) |\n| Network calls · API keys · data leaving your machine | **0** | 100% local, fail-open |\n\n\u003csub\u003eChar reduction is general; exact token % is **model-specific** — see [General vs model-specific savings](#general-vs-model-specific-savings). Figures are measured, not asserted; the codec is fully open ([`ultracos-core/`](ultracos-core/)) so the lossless behavior is verifiable, and the project does not publish numbers it has not measured.\u003c/sub\u003e\n\n## How it works\n\nUltraCoS hooks the request lifecycle at six points; every one fails open\n(`{\"continue\": true}` on any error — it can never block your input):\n\n```mermaid\nflowchart LR\n  U([Your prompt]) --\u003e UPS[UserPromptSubmit\u003cbr/\u003emode detector]\n  UPS --\u003e PRE[PreToolUse\u003cbr/\u003ehistory dedup]\n  PRE --\u003e TOOL[(Tool runs)]\n  TOOL --\u003e POST[PostToolUse\u003cbr/\u003ecodec + session dedup]\n  POST --\u003e Q{compaction?}\n  Q -- yes --\u003e PC[PreCompact\u003cbr/\u003edense-form mandate]\n  Q -- no --\u003e R([Reply — never compressed])\n  PC --\u003e R\n```\n\nIt does **not** fight Anthropic's cache — it works on a different token bucket.\nNative caching discounts what is *already cached*; UltraCoS shrinks the\nturn-to-turn traffic that changes every call and therefore *never* caches, plus\nthe dense form of what *does* get cached. The two stack:\n\n```mermaid\nflowchart TB\n  subgraph B[What you are billed per call]\n    P[Stable prefix\u003cbr/\u003esystem prompt + tools]\n    T[Turn-to-turn traffic\u003cbr/\u003etool results, history, compaction]\n  end\n  P --\u003e|Anthropic cache: up to −90%| C[cheap]\n  P --\u003e|UltraCoS dialect: −44.6% of what caches| C\n  T --\u003e|UltraCoS codec: −31.7% corpus| S[shrunk every call]\n  C --\u003e L([Lower total])\n  S --\u003e L\n```\n\nThe hot path is a prebuilt native binary; Python is the portable fallback:\n\n```mermaid\nflowchart LR\n  H[PostToolUse hook] --\u003e Qb{native binary\u003cbr/\u003eavailable?}\n  Qb -- yes --\u003e Rb[Rust codec ~5 ms]\n  Qb -- \"no / ULTRACOS_RUST=0\" --\u003e Py[Python codec ~170 ms]\n  Rb --\u003e O([compacted output\u003cbr/\u003eidentical, fail-open])\n  Py --\u003e O\n```\n\n## ULTRACOS-L1 — the symbolic dialect at the core\n\nUltraCoS is named for its **CoS** — the *symbolic notation* it started as. ULTRACOS-L1\nis a **lossless prose↔dense transcoder**: it rewrites verbose, repetitive\ninstruction-style prose (system prompts, `CLAUDE.md`, skill and agent files) into a\ncompact symbolic dialect the **same model decodes natively**, then expands it back\nbyte-for-byte.\n\n```\nexpand(compress(x)) == x      # byte-identical for dialect content;\n                              # unrecognized text passes through untouched\n```\n\n**Why it matters:** the system prompt ships on *every* request, and dense instructions\ncost far fewer tokens while the model reads them just as well — so this is the only\n*always-on, every-call* saving. Measured **−44.6% token reduction on dialect content**\n(`opus-dialect-validate-2026-05-31`). It is the language behind the PreCompact\ndense-form mandate and the `compress-config` command — and it is **where the whole\nproject began**. Every other mechanism (tool-result codec, dedup, the state-aware\ngate) stacks on top of it.\n\n**Model-specific dialects.** Tokenizers differ per model, so the dialect is a *data\nfile* the binary loads at runtime (`ULTRACOS_DIALECT`) — tune or ship a dialect for\nyour model with **no rebuild** (lossless self-check on load). `ultracos-core\ndialect-export` dumps the default to edit; `ultracos-core compress` / `expand` run it\ndirectly; `compress-config` applies it to your config files (dry-run + backup + lossless gate).\n\n## Quickstart — first 5 minutes\n\n```sh\nclaude plugin marketplace add MikkoParkkola/ultracos\nclaude plugin install ultracos\n```\n\n1. **Restart your session.** Hooks fire automatically — nothing to configure.\n2. **Use Claude normally** for a few tool-heavy turns (reads, greps, bash).\n3. **Check what it saved:** run `ultracos-stats` — it reads the append-only audit\n   log and prints per-tool savings (so the effect is measured, not asserted).\n4. **Tune aggressiveness** with `ultracos-set-level` if you want more or less.\n5. **Verify losslessness yourself:** `echo \"\u003cdense prose\u003e\" | ultracos-core compress | ultracos-core expand` round-trips byte-for-byte.\n\nNothing leaves your machine; if anything errors, the original output passes\nthrough untouched. To pause, set `ULTRACOS_DISABLE=1`.\n\n## How it compares\n\nToken reduction is a crowded, genuinely diverse space. UltraCoS is a **lossless,\nin-process, agent-tool-result** compressor that stacks on native caching — it is\nnot trying to be a learned compressor or a hosted proxy. The honest landscape\n(★ = GitHub stars, a maturity signal, not a quality verdict):\n\n| Approach | Examples | Reversible? | Where it runs | Best at |\n|---|---|---|---|---|\n| **Lossless in-process codec** (this) | **UltraCoS** | yes (by meaning) | your machine, no hop | agent tool-results + dense compaction, stacked on cache |\n| Lossless reversible pipeline | [claw-compactor](https://github.com/open-compress/claw-compactor) (2.2k★) | yes | varies | multi-stage general-text compression |\n| Drop-in prompt compression | [leanctx](https://github.com/jia-gao/leanctx) (300★+) | varies | library | production-app prompt text |\n| Learned / lossy compression | [LLMLingua / LLMLingua-2](https://github.com/microsoft/LLMLingua) (6k★) | no (drops tokens) | local model | aggressive prompt-text reduction where some loss is acceptable |\n| Tool-call interceptor | [Crucible](https://github.com/Tetrahedroned/Crucible) | varies | in-process | nearest architecture to UltraCoS |\n| Hosted edge proxy | Edgee, `rtk`-based | partial | network hop | one layer across multiple agents / clients |\n| Output brevity (\"caveman\") | caveman, eridani-speak | no | varies | shrinking the model's *output* register |\n| Spend visibility (**not** compression) | [claude-usage](https://github.com/phuryn/claude-usage) (1.7k★), ai-token-monitor | n/a | dashboard | *seeing* cost, not reducing it |\n| Task offload | houtini-lm | n/a | local LLM | delegating bounded subtasks off the paid model |\n\nTwo honest notes:\n1. **UltraCoS is small by star count** next to LLMLingua or claw-compactor — but it\n   is **dogfooded in production daily on real Claude Code traffic**, not a research\n   demo. Recently open-sourced, long battle-tested. It competes on being **lossless\n   + in-process + zero-setup + cache-stacking**.\n2. **These mostly compose.** A lossless codec, a learned compressor, and a spend dashboard solve different parts of the bill — running more than one is normal, not redundant. UltraCoS deliberately occupies the lossless-in-process slot and leaves the others to their strengths.\n\n## General vs model-specific savings\n\nBe precise about what is universal and what depends on the model:\n\n- **The character reduction is general.** ANSI-strip, JSON-minify, dedup, and\n  blank-collapse remove *characters* losslessly — that holds for any tokenizer,\n  any model, any provider.\n- **The exact token percentage is model-specific.** Tokens are not characters;\n  every model tokenizes differently. The headline figures were measured on\n  specific tokenizers: **−44.6% dialect** is in **Claude Opus** tokens\n  (`opus-dialect-validate-2026-05-31`); **−31.7% corpus** uses a tokenizer-free\n  `chars/4` proxy. Your model's real saving will differ — sometimes higher,\n  sometimes lower.\n- **Opus 4.7 / 4.8 ship their own tokenizers** (as do GPT's o200k, Gemini, etc.).\n  The bundled [`calibration/`](calibration/) snapshot fits per-model\n  `tokens-per-char` so the keep-vs-compact decision matches the *actual*\n  tokenizer rather than a fixed 4-char assumption — and it is refreshed as model\n  tokenizers move (they can change silently on a model update).\n\n## The UltraCoS family\n\nUltraCoS is a token-cost-reduction system for LLM coding agents. The pieces have\ndistinct roles:\n\n- **UltraCoS Plugin** (this repo) — the free, client-side codec for Claude Code.\n- **UltraCoS Verify** (`ultracos-verify`) — an MIT tool so savings can be verified\n  independently, without trusting the provider.\n- A managed offering — spend visibility and prompt-cache protection for teams\n  running Claude Code at scale — is available on inquiry (see [COMMERCIAL.md](COMMERCIAL.md)).\n\nThe plugin is free and complete on its own; the rest is optional.\n\n## Install\n\nSee [Quickstart](#quickstart--first-5-minutes) above — two commands, then restart\nyour session. `ultracos-stats` shows savings; `ultracos-set-level` tunes aggressiveness.\n\n## What it does (the wired features)\n\nUltraCoS registers six hook points; every one fails open.\n\n| Hook | What it does |\n|---|---|\n| **PostToolUse — codec** | Compacts each tool result: ANSI strip, JSON minify, blank-collapse, shape-aware compaction (JSON / YAML / TOML / code / filesystem path-lists), oversize truncation, schema-tag. Runs as the native binary, Python fallback. |\n| **PostToolUse — session dedup** | A repeated `Read`/`Grep`/`Glob`/`Monitor` result is replaced with a short reference to its earlier occurrence in the session. |\n| **PreToolUse — history dedup** | Collapses duplicate context already carried in earlier turns before a tool runs. |\n| **PreCompact — summary-form mandate** | When Claude Code compacts, UltraCoS injects an instruction to summarize in a dense, structured form. |\n| **UserPromptSubmit — mode detector + stats** | Detects the active aggressiveness level and serves the `ultracos-stats` view. |\n| **SessionStart — skill loader** | Loads the UltraCoS mode skill so the agent understands the dense conventions. |\n\n### Safety: it can reduce tokens but never corrupt context\n\nTwo guards make this safe:\n\n- **Break-even gating** — a transform is applied only when it saves enough tokens\n  to be worth its schema tag. Below that, the original passes through verbatim.\n- **Anchor-survival guard** — a compaction that would drop the load-bearing\n  `file:line`, error code, identifier, that made the output useful is automatically\n  reverted. Truncation is the only lossy step, and it is anchor-guarded.\n\n## Architecture — and why there are Python files\n\nUltraCoS is **Rust-first, Python-fallback**:\n\n- The hot-path codec ships as **prebuilt native binaries** under\n  [`bin/\u003ctriple\u003e/`](bin/) (macOS and Linux, arm64 and x86_64). The PostToolUse hook\n  runs the binary by default — roughly `5 ms` per call versus `~170 ms` to launch a\n  Python interpreter, with identical output.\n- The **Python codec is the portable fallback** — used on an unsupported platform,\n  a missing binary, an `exec` denied by policy, or `ULTRACOS_RUST=0`. So\n  `hooks/PostToolUse/ultracos_codec.py` and the modules it imports (cache, dedup,\n  anchor-guard, tokenizer, paths) exist so the plugin still works where the binary\n  cannot run. Every path is fail-open.\n- The **lightweight glue hooks** (skill loader, mode detector, stats handler,\n  history dedup, PreCompact mandate) are Python because they are trivial and not on\n  the per-tool-result hot path; a native port would buy nothing.\n\nBinaries are reproducible from the in-repo source via [`bin/build.sh`](bin/build.sh)\nand verified by [`bin/SHA256SUMS`](bin/SHA256SUMS). The codec source is fully open —\n[`ultracos-core/`](ultracos-core/) — read every line.\n\n## Cache safety — why it can't bust your prompt cache\n\nAnthropic's prompt cache is the biggest token-cost lever there is, and mutating an\nalready-cached prefix forces a full re-fetch at creation price — the worst failure\nmode in this space. **UltraCoS is cache-safe by construction, not by a flag:**\n\n- The codec acts only on **fresh tool-result output** (the appended tail), never on\n  the system-prompt / tool-definition prefix that gets cached.\n- Compaction is **deterministic** — the same payload always compacts to the same\n  bytes, so a tool result that later becomes part of a cached prefix stays stable.\n- **Session-dedup back-references the *repeat*** (`[seen earlier this session]`) and\n  never rewrites the earlier occurrence — the potentially-cached copy is untouched.\n- **History-dedup only appends an advisory note**; it does not rewrite prior turns.\n- The user-visible reply is never compressed.\n\n`ULTRACOS_CACHE_AWARE` (below) is optional defense-in-depth — a heuristic that backs\noff on prefixes it *infers* are cache-hot. It is **off by default because the\nstructural guarantees above already protect the cache**, and the heuristic cannot\nsee Anthropic's real cache state (it awaits `usage.cache_read_input_tokens`). Turn it\non for belt-and-suspenders; you do not need it for correctness.\n\n## Configuration\n\n| Env var | Default | Effect |\n|---|---|---|\n| `ULTRACOS_RUST` | on | Set `0` to force the Python codec. |\n| `ULTRACOS_ANCHOR_GUARD` | on | Set `0`/`off` to disable the anchor-survival revert (not recommended). |\n| `ULTRACOS_CACHE_AWARE` | off | Optional defense-in-depth: backs off compaction on inferred cache-hot prefixes. Off because the codec is already cache-safe by construction (see [Cache safety](#cache-safety--why-it-cant-bust-your-prompt-cache)); on adds per-call disk I/O. |\n| `ULTRACOS_DATA_DIR` | `~/.ultracos` | Where the audit log and state live. |\n\n## Calibration — a published snapshot, kept current as a service\n\nThe codec's keep-vs-compact boundary uses a token estimate. UltraCoS ships a\n**calibration snapshot** ([`calibration/`](calibration/)): per-model\n`tokens-per-char` values fitted from real, model-billed token counts, so the\nestimate matches a model's actual tokenizer rather than a fixed assumption. The\nfallback, when no snapshot value applies, is the classic 4-characters-per-token\nestimate.\n\n**Public vs private.** The codec source, the published snapshot (numbers, schema,\nversion), this methodology, and the fallback are all here and inspectable. The data,\nthe fitting method, and the pipeline that *produce* the snapshot are not — that is\nwhat makes a snapshot a result you can use but not regenerate. See\n[METHODOLOGY.md](METHODOLOGY.md).\n\n**It is a service.** A model's tokenizer can change with a model update, with no\nchangelog. The snapshot is therefore refreshed as model tokenizers change. A frozen\ncopy keeps working under the license; a refreshed one tracks the change.\n\nEvery published value is fitted from measured counts. The project does not publish\nperformance figures it has not measured.\n\n## Observability\n\nUltraCoS writes an append-only audit row per compaction event (savings per tool,\nshape, version) so its effect is measurable, not asserted. `ultracos-stats` reads it.\n\n## Quality proof — losslessness is a gate, not a claim\n\n`expand(compress(x)) == x` is a hard invariant in the **shipped, open** codec:\n`Dialect::is_lossless()` in [`ultracos-core/src/codec.rs`](ultracos-core/src/codec.rs)\nself-checks every dialect on load and falls back to the bundled default on any\ncollision, and the Rust unit tests assert the round-trip for all compiled-in dialect\npairs. A release gate runs that same proof before every publish, so a dialect change\ncan never silently break the round-trip. The codec source is fully open — verify it\nyourself with `ultracos-core compress | ultracos-core expand`.\n\n## FAQ\n\n**How do I reduce Claude Code token costs?**\nInstall UltraCoS (`claude plugin install ultracos`). It losslessly compacts\ntool-result output, deduplicates repeated context, and compresses the system\nprompt — stacking on top of Anthropic's prompt cache. No API key, no signup.\n\n**Is it lossless? Does it change what the agent sees?**\nThe codec is lossless by meaning: `expand(compress(x)) == x` for dialect content,\nand unrecognized text passes through untouched. Truncation is the only lossy step\nand it is anchor-guarded (it reverts if it would drop a `file:line` or error\ncode). The user-visible reply is never compressed.\n\n**Does it work with models other than Claude?**\nThe character-level reductions (ANSI-strip, dedup, JSON-minify) are general and\nwork with any model and provider. The exact token percentage is model-specific\nbecause each model tokenizes differently; a per-model calibration snapshot keeps\nthe estimate honest. See [General vs model-specific savings](#general-vs-model-specific-savings).\n\n**How much does it actually save?**\n−31.7% on a 52-fixture tool-heavy corpus, −71.1% on large `Bash` dumps, −44.6% on\ninstruction prose in the dialect (Claude Opus tokens). Your numbers depend on\nyour workload and model — run `ultracos-stats` to measure your own.\n\n**How is it different from LLMLingua, claw-compactor, or a proxy like Edgee?**\nLLMLingua is a learned, *lossy* prompt compressor (it drops tokens); UltraCoS is\nlossless and in-process. claw-compactor is a lossless multi-stage pipeline;\nUltraCoS targets agent tool-results + compaction specifically and stacks on the\ncache. Edgee is a hosted edge proxy (network hop); UltraCoS runs on your machine\nwith no hop. They compose — see [How it compares](#how-it-compares).\n\n**Does it send my data anywhere?**\nNo. 100% local, zero network calls, zero API keys. Tool output never leaves your\nmachine. Every path is fail-open: on any error the original passes through.\n\n**Can I compress my `CLAUDE.md` / skills / agent files?**\nYes — `ultracos-core compress-config \u003cfile\u003e` previews savings (dry-run by\ndefault), and `--apply` writes them behind a lossless gate with an automatic\n`.ultracos.bak` backup. The system prompt ships on every request, so this is the\nonly always-on saving.\n\n## License\n\n**PolyForm Noncommercial License 1.0.0** — free for any noncommercial use.\nCommercial use requires a paid license: see [COMMERCIAL.md](COMMERCIAL.md) or\ncontact **mikko.parkkola@iki.fi**. Full text in [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikkoparkkola%2Fultracos","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikkoparkkola%2Fultracos","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikkoparkkola%2Fultracos/lists"}