Feature Request: Native token compression for CLAUDE.md and instruction files

[Gumby63]

Summary

Claude Code loads CLAUDE.md, rules files, and project instructions into context on every session start. As these files grow with real usage, they compete with working memory for context space. Users who build serious assistant configurations hit this wall quickly. The platform should handle instruction file compression natively rather than requiring users to manually optimize their token footprint.

The Problem

Power users build CLAUDE.md files that grow to 10K-15K+ tokens as they add workflows, agent configurations, project context, and operational rules. Combined with .claude/rules/ files, memory systems, and project instructions, startup context can consume 20-30K tokens before the user says a word.

The current options are:

1. Manually compress your instruction files (I reduced mine from ~15,600 tokens to ~2,800 by hand)
2. Accept the context cost and hit compaction earlier
3. Split files and load on-demand (requires building your own cold-start architecture)

All three put the optimization burden on the user.

Proposed Solutions

Any or all of these would help:

1. Automatic instruction file compression. When loading CLAUDE.md and rules files, compress them to a token-efficient representation while preserving semantic meaning. The user writes in natural English. Claude reads a compressed version. The algorithm is straightforward: remove filler words, collapse verbose instructions to shorthand, preserve specifics (paths, names, rules). I wrote a working version of this: https://build-tammy.netlify.app/token-trim

2. Semantic/progressive loading. Don't dump every rules file into context on every session. Load instruction sections that match the current task. If I'm writing an article, load the editorial rules. If I'm doing browser automation, load the browser rules. Expand sections on demand as the task requires.

3. A human-to-compressed interpreter. Users write CLAUDE.md in plain English because that's natural. Offer a tool or built-in process that automatically generates a token-optimized version. Most users don't know that "When editing or creating agent instruction files, every agent file must include a mission statement, protocol, output format template, quality standards, scope boundaries, and inter-agent routing" can be compressed to "agent files must include: mission, protocol, output format, quality standards, scope boundaries, inter-agent routing" with zero meaning loss.

Context

I'm a Max plan user running Claude Code as a full-time personal assistant for journalism and civic work. 27 agent files, 15+ custom skills, 200+ memories in a semantic search server, 18 active projects. My CLAUDE.md is heavily compressed already. Most users building toward this level of configuration won't know how to compress their instructions, and shouldn't have to.

The token-trim algorithm I built and use: https://build-tammy.netlify.app/token-trim

[github-actions]

Found 3 possible duplicate issues:

1. [FEATURE] CLAUDE.ms (and other rules) - Sizing alerts, auto consolidation on write, auto review suggestions #25351
2. [Feature] Short@Tags — Semantic Compression Protocol for AI Context Windows #32228
3. Rules re-injected as system-reminders on every tool call, consuming ~46% of context window #32057

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[Gumby63]

These are related but not duplicates. The three flagged issues describe symptoms. This one provides a working solution.

• [FEATURE] CLAUDE.ms (and other rules) - Sizing alerts, auto consolidation on write, auto review suggestions #25351 asks for sizing alerts and consolidation suggestions. Good idea, different feature.
• [Feature] Short@Tags — Semantic Compression Protocol for AI Context Windows #32228 proposes a compression protocol. Conceptual overlap, but no implementation.
• Rules re-injected as system-reminders on every tool call, consuming ~46% of context window #32057 identifies rules consuming 46% of context. That's the symptom this issue solves.

I've actually built and deployed the token compression algorithm described here. It reduced my CLAUDE.md from ~15,600 tokens to ~2,800 (82% reduction) with zero semantic loss. It's been running in production daily for a week. The working implementation is documented at https://build-tammy.netlify.app/token-trim.

This issue proposes that Claude Code do natively what I'm doing manually: compress instruction files before loading them into context. The algorithm exists. It works. It would benefit every user with a non-trivial CLAUDE.md.

[m13v]

we run a global CLAUDE.md plus per-project CLAUDE.md files and hit this wall. our global instructions alone cover identity, accounts, development workflow, testing requirements, multi-agent coordination, and debugging patterns. every session starts by loading all of it.

the practical workaround we landed on: keep CLAUDE.md as a routing layer with brief rules, and offload detailed context to separate files that get loaded on-demand. for example, our memory system uses small index files (under 200 lines) that point to individual memory files - only the relevant ones get read when needed.

the tiered approach in your proposal makes sense. one thing worth considering - rather than compressing instructions (which risks losing nuance), a conditional loading system where CLAUDE.md sections are tagged with triggers would help more. something like "only load this section when working on frontend" or "only load when debugging"

that said, native support for this would be way better than the manual workarounds we're doing

[m13v]

our memory system that implements the tiered loading pattern: https://github.com/m13v/user-memories - small index files with pointers to detailed memory files, only loaded when relevant. the CLAUDE.md that routes to these: it's a routing layer that stays under 200 lines while referencing detailed per-topic memory files

[m13v]

This resonates. We run Claude Code as a multi-agent orchestration system with 27+ agent instruction files and a semantic memory server, and the startup context cost is a real problem.

Your solution 2 (semantic/progressive loading) is the most impactful in practice. We implemented a version of this ourselves - instead of one massive CLAUDE.md, we split instructions into a base file and topic-specific rules files in .claude/rules/. The base CLAUDE.md is kept minimal (identity, defaults, critical rules only) and the rules files are loaded contextually. This cut our effective startup context from ~15K tokens to ~4K for most tasks.

The key insight: most tasks only need 20-30% of your total instruction set. If you're doing browser automation, you don't need your git workflow rules. If you're writing code, you don't need your social media posting rules.

For solution 3 (human-to-compressed), we found that the compression isn't just about removing filler words - it's about restructuring. Tables compress better than paragraphs. Pipe-separated lists compress better than bullet points. 'When X, do Y' compresses better than 'In situations where X occurs, the expected behavior is to perform Y'. We got roughly 5:1 compression on our instruction files by restructuring alone.

One addition to your proposals: lazy loading for skills/commands. We have 15+ custom skills, and loading all their definitions at startup is wasteful. A skill registry that just loads names + one-line descriptions at startup, with full definitions loaded on-demand when invoked, would save significant context.

[m13v]

Our multi-agent orchestration setup that uses the split-instructions approach I described: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md

The skill registry pattern for lazy loading: https://github.com/m13v/social-autoposter/blob/main/skill/SKILL.md

[Gumby63]

Interesting that we landed on nearly identical architectures independently. 28 agent files, semantic memory server (ChromaDB), compressed CLAUDE.md, cold-start loading that only pulls what the task needs. The fact that two users built the same workarounds separately is the strongest argument for native support.

Your compression ratios match mine. Restructuring is the real win. My CLAUDE.md uses pipe-separated values, semicolons instead of periods where meaning holds, no articles or filler. 82% reduction with zero semantic loss. The algorithm I built automates that restructuring, not just word removal.

On lazy-loading skills: Claude Code already does a version of this. The Skill tool loads skill names and one-line descriptions at startup, then fetches full content on invocation. But it's opt-in and only works for skills registered in a specific way. Formalizing this as a first-class feature for all instruction files (rules, memory indexes, agent definitions) would be the real unlock.

The core point stands: two power users shouldn't need to independently engineer the same context management system. This should be platform-level.

[m13v]

the convergence is interesting - 28 agent files and a semantic memory server is a serious setup. we went with a simpler stack (flat markdown files + SQLite with embeddings) partly because we wanted zero infrastructure dependencies, but ChromaDB gives you better similarity search out of the box.

the compressed CLAUDE.md approach you're using - are you doing that manually or with a script? we keep ours under 200 lines by treating it as a routing layer (brief rules + pointers to detailed files) rather than trying to fit everything inline. the conditional loading idea in this issue would make both approaches unnecessary though

[Gumby63]

Both. I compressed manually first to learn what worked, then built an algorithm to automate it. The tool is live at https://build-tammy.netlify.app/token-trim. It handles restructuring (tables over paragraphs, pipe-separated lists, dropping articles and filler) plus semantic compression. That's what got the 82% reduction.

My CLAUDE.md is also a routing layer with on-demand loading, same pattern you describe. Compression and routing are complementary. The base file is compressed AND minimal. Detailed context loads only when the task demands it.

For context on the scale: I publish two news sites with this system. Several articles a day. Heavy research. Often four different projects running simultaneously, one generating audio, another building a slide deck, others doing research or drafting.

The two biggest problems at this scale aren't really about token compression. They're about delegation. Getting Opus to ALWAYS delegate to subagents instead of trying to do the work itself. And part of that delegation process is pulling the right workflow context from the memory server into the agent's prompt, because subagents can't access memory on their own. Compression helps, but the real bottleneck is behavioral, not mechanical.

You're right that conditional loading would reduce the need for both approaches. But compression still matters for the files that do load. Even a conditionally loaded rules file benefits from being half the size.

[ThinkOffApp]

We maintain a CLAUDE.md that is currently around 240 lines with agent configs, API keys, outreach rules, and operational state. It grows naturally as the project evolves.

Our approach: split content into a lean CLAUDE.md index that references topic-specific memory files. The memory system loads the index on every session but only reads individual topic files when relevant. This keeps startup tokens under control while preserving access to the full knowledge base.

For the compression side: we found that moving ephemeral state (task progress, current work) out of CLAUDE.md entirely and into external systems (room messages, scratchpads on GroupMind) reduces file size significantly. CLAUDE.md stays focused on durable rules and identity.

The /compact interaction also helps. We use append-only room logs as external memory that survives compression, so even aggressive compaction does not lose operational context. The key insight: anything you might need after compact should live outside the session, not in CLAUDE.md.

[Gumby63]

Three users, same architecture. Lean index, topic files loaded on demand, ephemeral state externalized. Nobody coordinated this. That's the strongest signal Anthropic could ask for.

Your point about append-only logs surviving compression is good. I use a state.md file that serves the same purpose. Session state saves there before close, reloads on startup. Anything that matters after /compact lives outside the conversation. Same conclusion you reached.

The question is whether Anthropic formalizes this pattern or lets every power user reinvent it. Conditional loading at the platform level would eliminate most of the engineering all three of us did independently.