terse-md

Terse-MD

Compress Claude instruction files. Verified lossless by meaning, not by wording.

What it does

Terse-MD is a Claude Code plugin that compresses human-written Markdown instruction files (CLAUDE.md, memory files, SKILL.md) into dense YAML conforming to a closed schema. The YAML is what Claude loads on subsequent sessions. Compression is verified by round-tripping the YAML back to prose and asking you to approve the reconstruction. Wording will shift. Meaning should not — but see The honest caveats below, because meaning can drift, and the whole design assumes you'll catch it.

Compression ratios vary by content shape. Rule-heavy files (CLAUDE.md, SKILL.md, feedback memories shaped as "rule + why + how-to-apply") can see 50–70% reduction. Reference files with paths/facts/rationale typically see 15–25% at best, and they lose meaningful context in the process. Short files (<300 tokens) may not shrink at all — the YAML scaffolding costs more than the prose you're compressing.

Requirements

Terse-MD runs inside Claude Code. The validation step in /terse-md:run and the canonicalization step in /terse-md:test shell out to Python. You need:

• python3
• PyYAML (pip install pyyaml)
• jsonschema (pip install jsonschema)

If pyyaml or jsonschema is missing, /terse-md:analyze falls back to a structural closure check of the compressed YAML's top-level keys against the schema. /terse-md:run and /terse-md:test both require PyYAML — /terse-md:run uses it to inject meta.source_hash into the validated YAML, and /terse-md:test uses it to canonicalize both runs before diffing. Both commands error out cleanly at the first Python call if PyYAML is missing.

Install

From inside Claude Code:

/plugin marketplace add marcelopaniza/terse-md
/plugin install terse-md@marcelopaniza-terse-md
/reload-plugins

Or for local development, clone the repo and start Claude Code with the plugin directory attached:

git clone https://github.com/marcelopaniza/terse-md
claude --plugin-dir ./terse-md

Use

/terse-md:analyze .

Scans . for candidate files, counts tokens (bytes ÷ 3.5 estimate), runs one real compression on the largest file, and prints projected savings. Writes nothing.

Scanned 4 files, 3,700 tokens total.
Sample compression on examples/larder_claude.source.md: 1,700 → 600 tokens (65% saved).
Estimated total after compression: ~1,300 tokens.

Top candidates by size:
  1. examples/larder_claude.source.md    1,700 tokens
  2. docs/SKILL.md                         900 tokens
  3. CLAUDE.md                             800 tokens
  4. memory/feedback_bar.md                300 tokens

Skipped by default (re-run with --include-all to include):
  MEMORY.md                  index file; already one-liners
  memory/project_foo.md      narrative scratchpad; short half-life

Next: `/terse-md:run --all .` or `/terse-md:run <file>`

/terse-md:run examples/larder_claude.source.md --dry-run

Runs the full pipeline on one file: normalize → compress → decompress, then shows the normalized source alongside the prose reconstructed from the YAML. You approve, reject, or skip. --dry-run performs every step but never writes the .approved.yaml file.

/terse-md:test examples/larder_claude.source.md

Idempotence check. Runs the pipeline twice with fresh subagents, canonicalizes both YAMLs (sorted keys, JSON form), and diffs them. Passes if identical. Useful after changing prompts or schema.

Which files to compress

Terse-MD's closed schema works best on files that are stable (you don't edit them weekly) and structured (rules, facts, pointers — not flowing narrative). By default, Terse-MD picks up files likely to fit that profile and skips files that don't.

Good fits (picked up by default)

• CLAUDE.md — global or project instructions. High re-read frequency (loaded every session), rule-shaped content, long-lived. Compression costs amortize over hundreds of reads. This is the target Terse-MD was designed for.
• SKILL.md — skill definitions. Similar shape and lifetime.
• feedback_*.md — Claude auto-memory "feedback" type. Already shaped as "rule + why + how-to-apply" which maps cleanly to the schema.

The user_*.md, feedback_*.md, and reference_*.md patterns also match similarly-named files outside Claude's auto-memory directory (e.g. a user_guide.md or reference_api.md in a docs folder). If that's not what you want, narrow the scan path — the patterns are filename prefixes, not directory-scoped.

Weak fits (picked up but drift is likely)