flowchart LR
  U([Your prompt]) --> UPS[UserPromptSubmit<br/>mode detector]
  UPS --> PRE[PreToolUse<br/>history dedup]
  PRE --> TOOL[(Tool runs)]
  TOOL --> POST[PostToolUse<br/>codec + session dedup]
  POST --> Q{compaction?}
  Q -- yes --> PC[PreCompact<br/>dense-form mandate]
  Q -- no --> R([Reply — never compressed])
  PC --> R

It does not fight Anthropic's cache — it works on a different token bucket. Native caching discounts what is already cached; Glyphdown shrinks the turn-to-turn traffic that changes every call and therefore never caches, plus the dense form of what does get cached. The two stack:

flowchart TB
  subgraph B[What you are billed per call]
    P[Stable prefix<br/>system prompt + tools]
    T[Turn-to-turn traffic<br/>tool results, history, compaction]
  end
  P -->|Anthropic cache: up to −90%| C[cheap]
  P -->|Glyphdown dialect: −44.6% of what caches| C
  T -->|Glyphdown codec: −31.7% corpus| S[shrunk every call]
  C --> L([Lower total])
  S --> L

The hot path is a prebuilt native binary; Python is the portable fallback:

flowchart LR
  H[PostToolUse hook] --> Qb{native binary<br/>available?}
  Qb -- yes --> Rb[Rust codec ~5 ms]
  Qb -- "no / GLYPHDOWN_RUST=0" --> Py[Python codec ~170 ms]
  Rb --> O([compacted output<br/>identical, fail-open])
  Py --> O

GLYPHDOWN-L1 — the symbolic dialect at the core

Glyphdown is named for its CoS — the symbolic notation it started as. GLYPHDOWN-L1 is a lossless prose↔dense transcoder: it rewrites verbose, repetitive instruction-style prose (system prompts, CLAUDE.md, skill and agent files) into a compact symbolic dialect the same model decodes natively, then expands it back byte-for-byte.

expand(compress(x)) == x      # byte-identical for dialect content;
                              # unrecognized text passes through untouched

Why it matters: the system prompt ships on every request, and dense instructions cost far fewer tokens while the model reads them just as well — so this is the only always-on, every-call saving. Measured −44.6% token reduction on dialect content (opus-dialect-validate-2026-05-31). It is the language behind the PreCompact dense-form mandate and the compress-config command — and it is where the whole project began. Every other mechanism (tool-result codec, dedup, the state-aware gate) stacks on top of it.

Model-specific dialects. Tokenizers differ per model, so the dialect is a data file the binary loads at runtime (GLYPHDOWN_DIALECT) — tune or ship a dialect for your model with no rebuild (lossless self-check on load). glyphdown-core dialect-export dumps the default to edit; glyphdown-core compress / expand run it directly; compress-config applies it to your config files (dry-run + backup + lossless gate).

Quickstart — first 5 minutes

claude plugin marketplace add MikkoParkkola/claude-marketplace
claude plugin install glyphdown

1. Restart your session. Hooks fire automatically — nothing to configure.
2. Use Claude normally for a few tool-heavy turns (reads, greps, bash).
3. Check what it saved: run glyphdown-stats — it reads the append-only audit log and prints per-tool savings (so the effect is measured, not asserted).
4. Tune aggressiveness with glyphdown-set-level if you want more or less.
5. Verify losslessness yourself: echo "<dense prose>" | glyphdown-core compress | glyphdown-core expand round-trips byte-for-byte.

Nothing leaves your machine; if anything errors, the original output passes through untouched. To pause, set GLYPHDOWN_DISABLE=1.

How it compares

Token reduction is a crowded, genuinely diverse space. Glyphdown is a lossless, in-process, agent-tool-result compressor that stacks on native caching — it is not trying to be a learned compressor or a hosted proxy. The honest landscape (★ = GitHub stars, a maturity signal, not a quality verdict):

Two honest notes:

1. Glyphdown is small by star count next to LLMLingua or claw-compactor — but it is dogfooded in production daily on real Claude Code traffic, not a research demo. Recently open-sourced, long battle-tested. It competes on being **lossless
   • in-process + zero-setup + cache-stacking**.
2. 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. Glyphdown deliberately occupies the lossless-in-process slot and leaves the others to their strengths.

General vs model-specific savings

Be precise about what is universal and what depends on the model:

• The character reduction is general. ANSI-strip, JSON-minify, dedup, and blank-collapse remove characters losslessly — that holds for any tokenizer, any model, any provider.
• The exact token percentage is model-specific. Tokens are not characters; every model tokenizes differently. The headline figures were measured on specific tokenizers: −44.6% dialect is in Claude Opus tokens (opus-dialect-validate-2026-05-31); −31.7% corpus uses a tokenizer-free chars/4 proxy. Your model's real saving will differ — sometimes higher, sometimes lower.
• Opus 4.7 / 4.8 ship their own tokenizers (as do GPT's o200k, Gemini, etc.). The bundled calibration/ snapshot fits per-model tokens-per-char so the keep-vs-compact decision matches the actual tokenizer rather than a fixed 4-char assumption — and it is refreshed as model tokenizers move (they can change silently on a model update).

The Glyphdown family

Glyphdown is a token-cost-reduction system for LLM coding agents. The pieces have distinct roles:

• Glyphdown Plugin (this repo) — the free, client-side codec for Claude Code.
• Glyphdown Verify (glyphdown-verify) — an MIT tool so savings can be verified independently, without trusting the provider.
• A managed offering — spend visibility and prompt-cache protection for teams running Claude Code at scale — is available on inquiry (see COMMERCIAL.md).

The plugin is free and complete on its own; the rest is optional.

Install

See Quickstart above — two commands, then restart your session. glyphdown-stats shows savings; glyphdown-set-level tunes aggressiveness.

What it does (the wired features)

Glyphdown registers six hook points; every one fails open.

Safety: it can reduce tokens but never corrupt context

Two guards make this safe:

• Break-even gating — a transform is applied only when it saves enough tokens to be worth its schema tag. Below that, the original passes through verbatim.
• Anchor-survival guard — a compaction that would drop the load-bearing file:line, error code, identifier, that made the output useful is automatically reverted. Truncation is the only lossy step, and it is anchor-guarded.

MCP server — the codec for any client, not just Claude Code

The same binary speaks the Model Context Protocol over stdio, so any MCP client (Cursor, Cline, Zed, Continue, claude.ai connectors) can call the codec on demand — the codec is text→text and language-agnostic, so this, not a per-language SDK, is the portable reach surface.

The plugin registers it automatically (mcpServers in plugin.json). To wire it into another client, point that client's MCP config at the launcher:

{
  "mcpServers": {
    "glyphdown": { "command": "sh", "args": ["<plugin>/bin/glyphdown-mcp.sh"] }
  }
}

Five tools, m