terse-md
Compresses Claude instruction files (CLAUDE.md, memory files, SKILL.md) into dense closed-schema YAML — typically 50–70% fewer tokens. Verif
Open source Open in the app JSON README (API)
About
Compresses Claude instruction files (CLAUDE.md, memory files, SKILL.md) into dense closed-schema YAML — typically 50–70% fewer tokens. Verified lossless by meaning via a mandatory round-trip review: source prose is normalized, compressed to YAML, decompressed back to prose, and shown side-by-side so you can approve that no rule was dropped or invented. Closed-vocabulary schema (rules, transforms, triggers, thresholds, meta) makes the output deterministic and hand-editable. Runs entirely inside Claude Code; no API key, no external service, no network calls.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- marcelopaniza
- Origin
- marketplace
- Category
- ferramentas
- Last push
- 2026-04-19T22:30:44Z
- Repository state
- ativo
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
marcelopaniza/terse-md/terse-md
README
# 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](#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)
- `reference_*.md` — reference material with paths, URLs, facts, and
rationale. The closed schema has rules/transforms/triggers/thresholds
but no native "fact" or "context" bucket, so standalone paths and
"why this exclusion matters" explanations tend to get dropped or
folded into rule directives. Expect 15–25% size reduction and
meaningful context loss. **Read the review carefully.** Probably not
worth compressing unless the file is very large and very stable.
- `user_*.md` — a single user-profile memory. If it's short and mostly
facts (role, preferences, expertise), you'll save <200 tokens and the
YAML overhead eats most of that. Compress only if the file is large
and rule-heavy.
### Skipped by default
- `MEMORY.md` — the auto-memory index. Already one-liners; nothing to compress.
- `project_*.md` — Claude auto-memory "project" type. These are narrative
scratchpads with SHAs, version tags, TODO markers ("PICK UP HERE",
"LANDED"), file paths, and mid-task edits. They decay fast (many are
archived or deleted within days). Compressing then discarding is wasted
effort, and the closed schema fights their loose narrative shape.
### Override
If you know what you're doing and want to compress everything Terse-MD
found, pass `--include-all` to either command:
```
/terse-md:analyze ~/.claude/projects/-mnt-data-game2/memory --include-all
/terse-md:run --all ~/.claude/projects/-mnt-data-game2/memory --include-all
```
Naming a single file explicitly with `/terse-md:run <path>` always bypasses
the default-skip filter — if you point Terse-MD at a specific file, it
trusts you.
## The honest caveats
Read this before you run `/terse-md:run` on anything you care about.
### 1. The approval step is the entire safety model. Don't click through.
Terse-MD's promise of "lossless by meaning" is **not** a mechanical
guarantee — it's a human-approved guarantee. The tool compresses, then
decompresses, then shows you the original next to the reconstruction and
asks if meaning survived. If you click **Approve** without reading the
diff, you have bypassed the only thing that keeps drift out of your
compressed file.
This matters because **Claude will follow the drifted version on every
future session.** If the reconstruction dropped a rationale, a path, a
"why we do X", that context is now gone from what Claude sees. You may
not notice until Claude starts making choices you thought it wouldn't.
If you're tempted to approve reflexively because the diff is long: that's
the exact moment the tool is asking you to do its most important job.
Reject and edit the source to fit the schema better, or don't compress
that file.
### 2. Compression ratios vary more than "50–70%" suggests.
That number applies to rule-heavy CLAUDE.md-shaped files. Real ranges
I've seen in testing:
| Content shape | Typical savings |
|---------------------------------------------|-----------------|
| CLAUDE.md with many behavioural rules | 50–70% |
| feedback memory (rule + why + how-to-apply) | 40–60% |
| Short reference memory (<500 tokens) | 15–25% |
| Dense reference with inline commands | 20–30% with meaningful context loss |
| Very short files (<200 tokens) | near zero or negative — YAML overhead |
### 3. The compression pipeline is not free.
Each file burns ~60k tokens of subagent context (3 Sonnet calls: normalize,
compress, decompress). A file has to be re-read many times to amortize that
cost. CLAUDE.md easily does (read every session × hundreds of sessions).
Individual feedback memories probably don't. Run `/terse-md:analyze` first
and think about re-read frequency before compressing a whole directory.
### 4. The closed schema is opinionated.
The schema has `rules`, `transforms`, `triggers`, `thresholds`, and `meta`
— five sections chosen for *behavioural instructions*. Reference material
(facts, paths, URLs, "here's the state of the world") fits awkwardly.
When in doubt, either: (a) rewrite the source into imperative rule shape
before compressing, or (b) don't compress that file.
## How it works
Three Sonnet subagents run in sequence. The first rewrites your prose in
canonical form, stripping filler without altering meaning. The second emits
YAML conforming to `schema.yaml` — a closed vocabulary of `rules`,
`transforms`, `triggers`, `thresholds`, and `meta`. Any key outside the
schema fails validation, and the compress step is retried once with the
error attached. The third expands the validated YAML back to prose. You
review source-vs-reconstruction side-by-side and approve only if meaning
survived. The approved YAML is written next to the source as
`<name>.approved.yaml` — that file is what Claude loads on future sessions.
## What it's not
- Not a token-optimizer that guarantees savings (it measures, then asks).
- Not lossless at the wording level (it's lossless at the meaning level — you approve the diff).
- Not affiliated with Anthropic.
## License
MIT. See [LICENSE](LICENSE).