oliver-kriska/mix-compression

Mix Output Compression

Mix commands (mix test, mix credo, mix dialyzer, mix compile) emit verbose, repetitive output that consumes context fast. This skill installs rtk — a CLI proxy that filters tool output before it lands in the transcript.

The filters short-circuit happy paths to a single line (mix test: all pass) while preserving full failure blocks, compile errors, and stack traces. Net win: 5-15% per-session token reduction on mix-heavy workflows.

When to use

• Long sessions — /phx:work or /phx:full hitting context limits from mix output
• Debugging loops — /phx:investigate retrying mix compile/mix test repeatedly
• Dialyzer-heavy projects — mix dialyzer output dominates the transcript

Iron Laws

1. NEVER strip critical signals — compile errors (** (CompileError), == Compilation error in), test failures (FAILURES, 0 failures — preserved even on short-circuit), dialyzer warnings, and stack traces with file:line MUST pass through unchanged
2. Verify after install — run rtk verify (or rtk verify --filter mix-test) to confirm the bundled test fixtures pass before declaring success
3. Never overwrite existing .rtk/filters.toml — diff and merge instead

Workflow

Step 1: Detect rtk

which rtk && rtk --version

Read ${CLAUDE_SKILL_DIR}/references/install.md if rtk is missing — covers homebrew install + shell hook setup.

Step 2: Seed .rtk/filters.toml

Reference filters live at ${CLAUDE_SKILL_DIR}/references/rtk-filters.toml. Six production-tested filters covering:

• mix-test — short-circuits all-pass, preserves failure blocks + compile errors
• mix-credo — collapses clean runs, preserves violation blocks
• mix-dialyzer — drops PLT progress, keeps warnings + summary
• mix-deps-get — collapses unchanged package lists
• mix-ecto-migrate — strips compile prefix, short-circuits "already up"
• mix-compile — handles parallel worker prefixes (N>) and MIX_ENV

Run this if the project has no .rtk/filters.toml yet:

mkdir -p .rtk
cp "${CLAUDE_SKILL_DIR}/references/rtk-filters.toml" .rtk/filters.toml

Read both files if one already exists. Present a diff to the user. Merge only the filters they don't already have.

Step 3: Verify filters work

rtk verify                       # runs all embedded [[tests.*]] fixtures
rtk verify --filter mix-test     # one filter only

Check that all report "passed". Flag and stop if any fail — usually means the user has a custom rtk version with regex differences.

Step 4: Confirm shell hook

Run rtk init zsh (or rtk init bash) to install the transparent rewrite hook that turns mix X into rtk mix X. Re-running is safe (idempotent). Skip this step and mix calls run unfiltered.

Customization

Add custom regex patterns to strip_lines_matching for project-specific noise sources (e.g., third-party hex deps spamming stack traces). See the inline example in ${CLAUDE_SKILL_DIR}/references/rtk-filters.toml lines 57-59.

What this is NOT

• Not a hook — Claude Code's PostToolUse hooks fire after the tool result is in the transcript and cannot shrink it. rtk works at the subprocess layer (the only layer where transcript-shortening is possible).
• Not project-analysis — the bundled filter set is universal across Phoenix projects. No mix.exs inspection needed.
• Not telemetry — rtk has telemetry off by default (enabled = false in config.toml). Filters run locally, no data leaves the machine.

References

• ${CLAUDE_SKILL_DIR}/references/rtk-filters.toml — bundled filter set
• ${CLAUDE_SKILL_DIR}/references/install.md — rtk install + shell hook setup
• rtk on GitHub