⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
context-compression
Use Tokenless for large files and noisy tool outputs before they enter context. Must be used when commands, Read output, diffs, logs, or search results are large.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
Quick start
npm install -g github:MaxForAI/Tokenless
tokenless repair-hooks --user
tokenless install-commands --user
tokenless launch
Then use Claude Code normally. Switch profiles anytime:
tokenless style chat # readable, shorter replies
tokenless style coding # dense coding output
tokenless style off # full hard-off
Claude Code gets expensive when every log, file read, diff, and long reply keeps getting carried into the next request.
Tokenless fixes that.
It keeps the raw evidence on your machine, sends Claude a compact version, and lets you expand the original output only when you need it.
Before / After
| Normal Claude Code | Claude Code with Tokenless |
|---|---|
| Reads a large file or log into future context repeatedly. | Stores the raw output locally and sends a compact packet. |
| Verbose final replies become part of the next request history. | chat and coding profiles keep replies short. |
| Agent trajectory can grow through repeated exploration and task-plan history. | Launcher trims Task/Plan tools by default; packets reduce large read context. |
Example large-read replacement:
| Raw context | Tokenless context |
|---|---|
| Full file/log output is carried through API requests. | TOKENLESS-READ-PACKET/0.1 with artifact id, imports, symbols, snippets, nearby files, and exact expansion commands. |
Why Tokenless
Claude Code sessions can become expensive because tool outputs, file reads, task-plan history, and verbose assistant replies are repeatedly carried through future API requests. Tokenless targets three sources of growth:
- Large tool output: test logs, build logs, search results, tree output, diffs, large reads, and large successful edit/write results.
- Agent trajectory overhead: repeated request context, high-overhead Task/Plan tools, and large raw file payloads.
- Response verbosity: optional
chatandcodingprofiles reduce assistant output tokens.
Benchmarks & Evidence
Tokenless has two evidence layers: real Claude Code API-body measurements, and external research showing why shorter, denser context can reduce cost without automatically reducing quality.
Real Claude Code benchmark runs
These are API-body measurements from actual Claude Code sessions. The main metric is estimated request-body or response-body tokens from raw API logs, not local hook-side savings estimates.
| Scenario | Baseline | Tokenless | Reduction |
|---|---|---|---|
5-turn CRM vibe coding, off vs coding | 4,697,867 request tokens | 2,476,391 | 47.3% |
6-turn natural conversation, off vs chat | 7,223 response tokens | 1,442 | 80.0% |
| Large CSS visual edit | 1,017,642 request tokens | 403,995-473,354 | ~54-60% |
| 10k-line React/TSX edit | 917,137 request tokens | 545,456 | 40.5% |
| Multifile React dashboard | 628,261 request tokens | 512,521 | 18.4% |
| Task/Plan tools enabled vs default launcher | 1,524,894 request tokens | 1,087,753 | 28.7% |
The strongest current product benchmark is the 5-turn CRM vibe-coding run: a non-specialist user gave vague iterative product-polish prompts. The public coding profile reduced request tokens by 47.3%, response tokens by 44.4%, and request count by 39.3% versus clean off.
The clean natural-conversation run isolates chat: no file tools or packet reducers were involved, and response tokens dropped by 80.0%.
Detailed methodology and raw run notes are in docs/benchmarking.md and docs/style-benchmark.md.
Research backing
The research does not prove Tokenless automatically helps every session. It supports the benchmark premise: context and response length are controllable engineering variables, and less text can sometimes be cheaper, faster, and more accurate.
| Paper | Why it matters for Tokenless |
|---|---|
| Brevity Constraints Reverse Performance Hierarchies in Language Models | Brevity constraints improved large-model accuracy by 26.3 percentage points on inverse-scaling problems. Verbose is not always better. |
| Prompt Compression in the Wild | Prompt compression can deliver real end-to-end speedups when workload, compression ratio, and hardware match; quality can remain statistically unchanged. |
| LLMLingua | Prompt compression can reduce inference cost while preserving semantic integrity under high compression ratios. |
| LongLLMLingua | Long-context compression can improve key-information perception while reducing cost and latency. |
| Selective Context | Pruning redundant context reported 50% context-cost reduction, 36% memory reduction, and 32% inference-time reduction with minor quality loss. |
| Gist Tokens | Learned prompt compression reached up to 26x prompt compression and up to 40% FLOPs reduction. |
Roadmap
Tokenless currently focuses on Claude Code context growth from tool output, file reads, and response verbosity. Next areas:
- User prompt compression: identify repeated prompt patterns, compress user intent without losing constraints, and keep the original prompt recoverable.
- Router-side optimization: reduce duplicated context and style overhead before requests hit the model backend.
- Broader workflow support: keep Claude Code as the primary target, then evaluate adapters for other agentic coding tools where the same context-growth problem appears.
Installation
Install from GitHub:
npm install -g github:MaxForAI/Tokenless
tokenless repair-hooks --user
tokenless launch
Tokenless is currently distributed through GitHub. It has not been published to the public npm registry yet.
For local development from a checkout:
git clone https://github.com/MaxForAI/Tokenless.git
cd Tokenless
npm install
npm link
tokenless repair-hooks --user
tokenless launch
If Claude Code is not available as claude on your PATH, set CLAUDE_BIN:
CLAUDE_BIN=/path/to/claude tokenless launch
Check installation status:
tokenless status --user
Output profiles
Tokenless has three public profiles:
| Profile | Behavior |
|---|---|
chat | Default. Short, readable natural-language responses. Only changes output style. |
coding | Dense structured responses for coding workflows. Only changes output style. |
off | Full Tokenless hard-off. Disables style injection and compression hooks. |
Set a profile:
tokenless style chat
tokenless style coding
tokenless style
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
plugins/claude-code/skills/context-compression/SKILL.md7.8 KBupstream ↗
--- name: context-compression description: Use Tokenless for large files and noisy tool outputs before they enter context. Must be used when commands, Read output, diffs, logs, or search results are large. --- # Tokenless Context Compression When working in this project, do not feed noisy raw outputs or large files directly into context. Tokenless is mandatory for large or noisy context: - If a file is large, first use `tokenless read --agent --data-dir <dir> <file>`. - If a Bash command is noisy, first use `tokenless run --agent --data-dir <dir> -- <command>`. - If a Tokenless hook blocks or caps a tool call, do not bypass it with another full-output command. - If you need exact evidence after a packet, expand the artifact before editing. - If Tokenless reports a pending large-file gate, the next action must be the exact `NEXT REQUIRED COMMAND`. The hook automatically caps high-noise Bash commands and large low-risk Read outputs through Tokenless. Keep tool inputs small: - Tokenless saves context by replacing large tool outputs with compact packets. Do not recreate the same token cost by sending huge generated tool inputs. - Prefer `tokenless read`, `tokenless expand`, and small bounded `Edit`/`MultiEdit` calls over large patch scripts. - Do not create large heredocs, `cat > file <<EOF`, giant `node -e` / `python -` commands, or temporary apply/fix/rewrite scripts unless the user explicitly asks. - If you feel tempted to write a big script to patch a large file, stop and use Tokenless to expand the exact lines, then edit only that small region. For manual local development in this repository, use `./plugins/claude-code/bin/tokenless` or the packaged `tokenless` alias: ```bash ./plugins/claude-code/bin/tokenless run --agent --data-dir /tmp/tokenless-dev -- npm test ``` High-noise commands include: - npm test, pnpm test, yarn test - pytest - npm/pnpm/yarn build, lint, typecheck, install - go test, cargo test, mvn test/verify/package, gradle build/test - git diff, git log - rg, grep -R - find, tree, ls -R - docker logs/build, kubectl logs/describe, Vercel/Netlify CLI logs When you see a `TOKENLESS-PACKET` block: 1. Treat it as a compressed evidence packet. 2. Use the key failures, relevant files, line numbers, and raw artifact pointer. 3. Do not ask for the full raw output unless needed. 4. If needed, use the full raw artifact command shown in the `Raw artifact:` line. When you see a `TOKENLESS-READ-PACKET` block: 1. Treat it as a compact local summary of a large file. 2. Read `Action boundary` before running any other command. It defines what tool commands are valid for this artifact. 3. If it contains `Action brief` and `Editable snippets`, treat those snippets as the first-pass edit surface, not as a table of contents to explore. 4. For broad visual/style tasks, do one minimal native `Read` to register editor state if you plan to edit, then make 6-10 bounded `Edit` calls from the snippets before doing more exploration. 5. Use only the artifact lookup commands shown in `Action boundary` when a needed `old_string` is not present in the snippets. 6. Do not expand every listed region by default. 7. Do not use repeated `grep`, `rg`, `sed`, or small `Read` calls to re-map the same file after a packet has already identified the edit targets. 8. Do not add unrelated files, scripts, or JS/HTML interactions for a CSS-only request unless the user explicitly asks. Tool boundaries: - `tokenless read` creates a whole-file packet only. - `tokenless read` is not a range, selector, or line lookup tool. - Do not invent `tokenless read --range`, `tokenless read --selector`, `tokenless read --lines`, or similar flags. - `tokenless expand` is the artifact lookup tool for a specific selector/text or line range. - `tokenless show` / raw artifact access is not for normal editing. Large CSS visual-edit protocol: 1. After a `TOKENLESS-READ-PACKET`, do not perform a second full-file read. 2. Identify the smallest useful edit set from `Editable snippets`: tokens/variables, background layer, shared cards, buttons, one optional hero/visual area, one optional timeline/footer area. 3. After the registration `Read`, make 6-10 bounded `Edit` calls when the snippets are sufficient. 4. If exact `old_string` is missing, use at most two `tokenless expand` lookups before the first edit. 5. Do not wait for `File must be read first`; proactively do one minimal native `Read` only to register editor state, then immediately edit. If the error still appears, do not remap the file. 6. After the first successful edit, continue editing only if the user request still clearly needs it; otherwise stop with a concise summary. 7. Do not open the page or run visual validation unless the user explicitly asks for validation. 8. Do not make “extra premium” changes outside the asked surface, such as mouse-tracking JS, custom scrollbars in HTML, or new runtime scripts, unless requested. 9. Final answer should be 3-5 concise bullets only; do not write a long change diary. Large source edit protocol: 1. After a `TOKENLESS-READ-PACKET` for `.js`, `.jsx`, `.ts`, `.tsx`, `.py`, `.vue`, or `.svelte`, do not perform a second full-file read. 2. Do one minimal native `Read` only to register editor state if you plan to edit. 3. Use `Source map`, `SFC sections`, `Project file hints`, and `Editable snippets` as the first-pass edit surface. 4. Make 4-8 bounded `Edit` calls from the snippets; do not remap the file with `grep`, `rg`, `sed`, or repeated `Read` calls. 5. If exact `old_string` is missing, use at most two `tokenless expand` lookups before editing. 6. Do not run tests, build, typecheck, browser validation, or package commands unless the user explicitly asks for validation. 7. Final answer should be 3-5 concise bullets only; do not write a long change diary. For multi-file JS/TS/Python/Vue/Svelte tasks: 1. Use `Project file hints` before running `ls`, `find`, or broad `rg`. 2. If a hinted adjacent file must be edited, read that exact file; do not map the whole project first. 3. Keep the first pass to the requested file plus clearly referenced adjacent files only. Trajectory budget: - Goal: one packet read, one minimal registration `Read` when editing, zero artifact expands unless required, one bounded serial `Edit` phase, concise final answer. - If you are about to run a fourth exploration command after a packet, stop and edit from the evidence already available. - If Tokenless blocks with stale state, run the required refresh once, then resume bounded editing. Do not probe around the stale gate with alternate raw reads. - Extra `tokenless expand` calls are a soft budget, not a hard denial. The 3rd lookup may include a warning; later lookups may be compacted. Treat either as a signal to edit from existing evidence unless the user requested exact review/security/legal/syntax validation. Large-file edit discipline: 1. Prefer normal editing behavior after the compact summary has identified the relevant area. 2. Use bounded serial `Edit` calls because this Claude Code environment may not expose `MultiEdit`. 3. For broad visual/style requests, pick a few high-impact regions and stop after meaningful improvements. 4. A successful small `Edit` or bounded `MultiEdit` keeps a Tokenless edit lease for the same file. 5. Run `tokenless read` again after `Write`, large edits, external file changes, lease exhaustion, or when Tokenless explicitly blocks with `TOKENLESS-STALE`. 6. If a stale-packet hook blocks an edit, the blocked tool call did not execute. 7. Do not use a large generated patch script as a workaround for the stale gate. When a large `Read` is capped: 1. Run the exact `tokenless read` command shown by the hook. 2. Use the packet to identify relevant selectors, symbols, sections, or line ranges. 3. If the packet includes exact snippets, attempt the next bounded edit from them before expanding. 4. Expand only with the exact artifact lookup commands shown in the packet if the compact summary isREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/maxforai-tokenless-plugins-claude-code-skills-context-compression.md