{
  "markdown": "# Terse-MD\n\nCompress Claude instruction files. Verified lossless by meaning, not by wording.\n\n## What it does\n\nTerse-MD is a Claude Code plugin that compresses human-written Markdown\ninstruction files (`CLAUDE.md`, memory files, `SKILL.md`) into dense YAML\nconforming to a closed schema. The YAML is what Claude loads on subsequent\nsessions. Compression is verified by round-tripping the YAML back to prose\nand asking you to approve the reconstruction. Wording will shift. Meaning\nshould not — but see **[The honest caveats](#the-honest-caveats)** below,\nbecause meaning *can* drift, and the whole design assumes you'll catch it.\n\nCompression ratios vary by content shape. Rule-heavy files (CLAUDE.md,\nSKILL.md, feedback memories shaped as \"rule + why + how-to-apply\") can\nsee 50–70% reduction. Reference files with paths/facts/rationale typically\nsee 15–25% at best, and they lose meaningful context in the process.\nShort files (<300 tokens) may not shrink at all — the YAML scaffolding\ncosts more than the prose you're compressing.\n\n## Requirements\n\nTerse-MD runs inside Claude Code. The validation step in `/terse-md:run` and the\ncanonicalization step in `/terse-md:test` shell out to Python. You need:\n\n- `python3`\n- `PyYAML` (`pip install pyyaml`)\n- `jsonschema` (`pip install jsonschema`)\n\nIf `pyyaml` or `jsonschema` is missing, `/terse-md:analyze` falls back to a\nstructural closure check of the compressed YAML's top-level keys against the\nschema. `/terse-md:run` and `/terse-md:test` both require PyYAML — `/terse-md:run`\nuses it to inject `meta.source_hash` into the validated YAML, and\n`/terse-md:test` uses it to canonicalize both runs before diffing. Both commands\nerror out cleanly at the first Python call if PyYAML is missing.\n\n## Install\n\nFrom inside Claude Code:\n\n```\n/plugin marketplace add marcelopaniza/terse-md\n/plugin install terse-md@marcelopaniza-terse-md\n/reload-plugins\n```\n\nOr for local development, clone the repo and start Claude Code with the plugin\ndirectory attached:\n\n```\ngit clone https://github.com/marcelopaniza/terse-md\nclaude --plugin-dir ./terse-md\n```\n\n## Use\n\n```\n/terse-md:analyze .\n```\n\nScans `.` for candidate files, counts tokens (bytes ÷ 3.5 estimate), runs one\nreal compression on the largest file, and prints projected savings. Writes\nnothing.\n\n```\nScanned 4 files, 3,700 tokens total.\nSample compression on examples/larder_claude.source.md: 1,700 → 600 tokens (65% saved).\nEstimated total after compression: ~1,300 tokens.\n\nTop candidates by size:\n  1. examples/larder_claude.source.md    1,700 tokens\n  2. docs/SKILL.md                         900 tokens\n  3. CLAUDE.md                             800 tokens\n  4. memory/feedback_bar.md                300 tokens\n\nSkipped by default (re-run with --include-all to include):\n  MEMORY.md                  index file; already one-liners\n  memory/project_foo.md      narrative scratchpad; short half-life\n\nNext: `/terse-md:run --all .` or `/terse-md:run <file>`\n```\n\n```\n/terse-md:run examples/larder_claude.source.md --dry-run\n```\n\nRuns the full pipeline on one file: normalize → compress → decompress, then\nshows the normalized source alongside the prose reconstructed from the YAML.\nYou approve, reject, or skip. `--dry-run` performs every step but never\nwrites the `.approved.yaml` file.\n\n```\n/terse-md:test examples/larder_claude.source.md\n```\n\nIdempotence check. Runs the pipeline twice with fresh subagents, canonicalizes\nboth YAMLs (sorted keys, JSON form), and diffs them. Passes if identical.\nUseful after changing prompts or schema.\n\n## Which files to compress\n\nTerse-MD's closed schema works best on files that are **stable** (you don't\nedit them weekly) and **structured** (rules, facts, pointers — not flowing\nnarrative). By default, Terse-MD picks up files likely to fit that profile\nand skips files that don't.\n\n### Good fits (picked up by default)\n\n- `CLAUDE.md` — global or project instructions. High re-read frequency\n  (loaded every session), rule-shaped content, long-lived. Compression\n  costs amortize over hundreds of reads. **This is the target Terse-MD\n  was designed for.**\n- `SKILL.md` — skill definitions. Similar shape and lifetime.\n- `feedback_*.md` — Claude auto-memory \"feedback\" type. Already shaped\n  as \"rule + why + how-to-apply\" which maps cleanly to the schema.\n\nThe `user_*.md`, `feedback_*.md`, and `reference_*.md` patterns also match\nsimilarly-named files outside Claude's auto-memory directory (e.g. a\n`user_guide.md` or `reference_api.md` in a docs folder). If that's not\nwhat you want, narrow the scan path — the patterns are filename prefixes,\nnot directory-scoped.\n\n### Weak fits (picked up but drift is likely)\n\n- `reference_*.md` — reference material with paths, URLs, facts, and\n  rationale. The closed schema has rules/transforms/triggers/thresholds\n  but no native \"fact\" or \"context\" bucket, so standalone paths and\n  \"why this exclusion matters\" explanations tend to get dropped or\n  folded into rule directives. Expect 15–25% size reduction and\n  meaningful context loss. **Read the review carefully.** Probably not\n  worth compressing unless the file is very large and very stable.\n- `user_*.md` — a single user-profile memory. If it's short and mostly\n  facts (role, preferences, expertise), you'll save <200 tokens and the\n  YAML overhead eats most of that. Compress only if the file is large\n  and rule-heavy.\n\n### Skipped by default\n\n- `MEMORY.md` — the auto-memory index. Already one-liners; nothing to compress.\n- `project_*.md` — Claude auto-memory \"project\" type. These are narrative\n  scratchpads with SHAs, version tags, TODO markers (\"PICK UP HERE\",\n  \"LANDED\"), file paths, and mid-task edits. They decay fast (many are\n  archived or deleted within days). Compressing then discarding is wasted\n  effort, and the closed schema fights their loose narrative shape.\n\n### Override\n\nIf you know what you're doing and want to compress everything Terse-MD\nfound, pass `--include-all` to either command:\n\n```\n/terse-md:analyze ~/.claude/projects/-mnt-data-game2/memory --include-all\n/terse-md:run --all ~/.claude/projects/-mnt-data-game2/memory --include-all\n```\n\nNaming a single file explicitly with `/terse-md:run <path>` always bypasses\nthe default-skip filter — if you point Terse-MD at a specific file, it\ntrusts you.\n\n## The honest caveats\n\nRead this before you run `/terse-md:run` on anything you care about.\n\n### 1. The approval step is the entire safety model. Don't click through.\n\nTerse-MD's promise of \"lossless by meaning\" is **not** a mechanical\nguarantee — it's a human-approved guarantee. The tool compresses, then\ndecompresses, then shows you the original next to the reconstruction and\nasks if meaning survived. If you click **Approve** without reading the\ndiff, you have bypassed the only thing that keeps drift out of your\ncompressed file.\n\nThis matters because **Claude will follow the drifted version on every\nfuture session.** If the reconstruction dropped a rationale, a path, a\n\"why we do X\", that context is now gone from what Claude sees. You may\nnot notice until Claude starts making choices you thought it wouldn't.\n\nIf you're tempted to approve reflexively because the diff is long: that's\nthe exact moment the tool is asking you to do its most important job.\nReject and edit the source to fit the schema better, or don't compress\nthat file.\n\n### 2. Compression ratios vary more than \"50–70%\" suggests.\n\nThat number applies to rule-heavy CLAUDE.md-shaped files. Real ranges\nI've seen in testing:\n\n| Content shape                               | Typical savings |\n|---------------------------------------------|-----------------|\n| CLAUDE.md with many behavioural rules       | 50–70%          |\n| feedback memory (rule + why + how-to-apply) | 40–60%          |\n| Short reference memory (<500 tokens)        | 15–25%          |\n| Dense reference with inline commands        | 20–30% with meaningful context loss |\n| Very short files (<200 tokens)              | near zero or negative — YAML overhead |\n\n### 3. The compression pipeline is not free.\n\nEach file burns ~60k tokens of subagent context (3 Sonnet calls: normalize,\ncompress, decompress). A file has to be re-read many times to amortize that\ncost. CLAUDE.md easily does (read every session × hundreds of sessions).\nIndividual feedback memories probably don't. Run `/terse-md:analyze` first\nand think about re-read frequency before compressing a whole directory.\n\n### 4. The closed schema is opinionated.\n\nThe schema has `rules`, `transforms`, `triggers`, `thresholds`, and `meta`\n— five sections chosen for *behavioural instructions*. Reference material\n(facts, paths, URLs, \"here's the state of the world\") fits awkwardly.\nWhen in doubt, either: (a) rewrite the source into imperative rule shape\nbefore compressing, or (b) don't compress that file.\n\n## How it works\n\nThree Sonnet subagents run in sequence. The first rewrites your prose in\ncanonical form, stripping filler without altering meaning. The second emits\nYAML conforming to `schema.yaml` — a closed vocabulary of `rules`,\n`transforms`, `triggers`, `thresholds`, and `meta`. Any key outside the\nschema fails validation, and the compress step is retried once with the\nerror attached. The third expands the validated YAML back to prose. You\nreview source-vs-reconstruction side-by-side and approve only if meaning\nsurvived. The approved YAML is written next to the source as\n`<name>.approved.yaml` — that file is what Claude loads on future sessions.\n\n## What it's not\n\n- Not a token-optimizer that guarantees savings (it measures, then asks).\n- Not lossless at the wording level (it's lossless at the meaning level — you approve the diff).\n- Not affiliated with Anthropic.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 9720,
  "sha": "45fd6785bd18d61b8c3737afc329c5b55055426737b0d1726c057006179d66a9",
  "repo_slug": "marcelopaniza/terse-md",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_marcelopaniza_terse_md_terse_md_1a398ebe/readme"
}