Summarize

Summarize finds prompt files worth shortening and rewrites their prose while keeping every structured block intact. It’s advisory: you review the diff and choose whether to write it.

tj summarize list                # find candidate files
tj summarize prep <file>         # wrap structure, emit for rewriting
tj summarize check <file> --summary <rewrite> --prepped-hash <hash>
tj summarize apply <file> --go   # write a staged rewrite (default dry-run)
tj summarize undo <file> --go    # restore from backup

The mechanism

The trick is that structure is protected before any rewriting happens. prep wraps each structured span (fenced code, inline code, tags, templates, tables) behind an id’d <tj-keep> marker and emits the wrapped prompt plus rewrite rules. A model summarizes the prose and leaves the markers untouched. check re-reads the file, hash-guards it against drift, restores every marked block verbatim by id, and stages the result only if every block survived. That gate is hard: if structure didn’t survive, nothing is staged.

apply writes a staged rewrite back to the file. It defaults to a dry-run that prints the unified diff; --go writes. It takes a gzip backup first and is guarded by an owner, content-hash, and symlink check. undo restores from that backup and refuses if the file drifted since apply.

There’s no scratch state. The file on disk is the source of truth, and Summarize reads only your config, never the telemetry DB.

Running the rewrite for you

prep can drive the rewrite in one shot instead of handing you the wrapped prompt:

tj summarize prep <file> --via claude-p    # your local Claude Code, no key
tj summarize prep <file> --via api         # Anthropic with your TJ_ANTHROPIC_API_KEY

The api path needs [summarize] api_model set and reports a “pays for itself” amortization. Both paths still pass the check gate before anything is staged.

list

Bare, list scans a catalog of known prompt locations and estimates the per-call token saving. Any scope-widening input — a PATH, --repo, --recursive, or --ext — opens it to all *.md. It’s read-only.

Honesty caveat

Summarize guarantees structure and nothing more. Every structured block is restored byte-for-byte by id, so structure is guaranteed. Meaning may change — a summary is a rewrite, and Summarize can’t prove the shorter prose carries the same instruction. The estimate is a per-call token reduction that amortizes across every reuse of the cached prompt, labelled estimated recoverable.

You will never see “behavior provably unchanged.” The candidate note says it plainly:

Candidates only. Review the summary before adopting. The figure is the estimated per-call token reduction.

The design goal is that load-bearing terms stay intact because they live inside protected blocks; the free-flowing prose is what gets condensed. Review the diff and confirm the meaning held before you --go.

See also

• Trim — flag low-significance regions to edit by hand
• Cost visibility — where your quota goes