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

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/25351
2. https://github.com/anthropics/claude-code/issues/32228
3. https://github.com/anthropics/claude-code/issues/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

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

• #25351 asks for sizing alerts and consolidation suggestions. Good idea, different feature.
• #32228 proposes a compression protocol. Conceptual overlap, but no implementation.
• #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.

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

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

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.

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

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.

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

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.

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.

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.

This is a real problem at scale. My own CLAUDE.md + memory system is ~8K tokens before I start. A few practical workarounds:

1. SessionStart hook for on-demand loading:

Instead of putting everything in CLAUDE.md, keep it lean and load context-specific rules via a SessionStart hook:

#!/bin/bash
# ~/.claude/hooks/smart-context-loader.sh
# Load only relevant rules based on the project type

PROJECT_DIR=$(pwd)
RULES=""

# Detect project type and load relevant rules
if [ -f "package.json" ]; then
  RULES="$RULES\n$(cat ~/.claude/rules/node-rules.md 2>/dev/null)"
elif [ -f "Cargo.toml" ]; then
  RULES="$RULES\n$(cat ~/.claude/rules/rust-rules.md 2>/dev/null)"
elif [ -f "project.godot" ]; then
  RULES="$RULES\n$(cat ~/.claude/rules/godot-rules.md 2>/dev/null)"
fi

# Load git-specific rules only if in a git repo
if git rev-parse --is-inside-work-tree &>/dev/null; then
  RULES="$RULES\nGit rules: commit messages use conventional commits. Always check status before committing."
fi

cat <<EOF
{"systemMessage": "Project-specific rules loaded:\n$RULES"}
EOF

This way your CLAUDE.md stays small (core principles only), and project-specific rules are injected at runtime based on what's actually in the directory.

2. Tiered CLAUDE.md structure:

~/.claude/CLAUDE.md          → 500 tokens (core principles only)
~/project/CLAUDE.md          → 500 tokens (project-specific)
~/.claude/rules/*.md         → Loaded by rules system
~/.claude/hooks/context.sh   → Dynamic context via SessionStart

Keep each file under 500 tokens. The rules directory files are loaded automatically, and the hook handles everything else.

3. Manual compression technique that works well:

Replace verbose natural language with telegraphic format:

# Before (~200 tokens)
When you are working on this project, please make sure to always
run the tests after making changes. If any tests fail, fix them
before moving on to the next task. Use pytest for Python files.

# After (~40 tokens)
## Rules
- Post-edit: run tests. Fix failures before proceeding
- Python: pytest

The model understands compressed instructions perfectly — it doesn't need the politeness or complete sentences. I've found 3-5x compression is typical with no semantic loss.

4. Cold-start via skill:

Create a /context skill that the model can invoke to load detailed rules on demand:

---
name: context
description: Load detailed project rules
---
Read and internalize all files in ~/.claude/rules/ and ~/project/docs/conventions.md.
Summarize the key rules that apply to the current task.

This keeps the initial context tiny and lets the model pull in details when needed.

that's a cool tool, bookmarked it. the manual-first approach makes sense - you learn what actually matters before automating. we went through the same cycle with our CLAUDE.md, started at like 400 lines and realized 80%% of it was never relevant to any given task

240 lines with API keys and operational state in it is going to be rough once you hit context compaction. we moved all that into separate files and just keep pointers in CLAUDE.md - the index file is like 50 lines and each memory file gets loaded only when relevant. the operational state stuff especially should be externalized since it changes every conversation

exactly, convergent evolution. when three people independently arrive at the same pattern it's usually because the tool is pushing you there. anthropic should just build this into claude code natively - conditional section loading based on task context would save everyone from reinventing it

the SessionStart hook approach is smart, hadn't thought of pre-filtering before the conversation even starts. we just do it lazily - CLAUDE.md has the index and individual files get read on demand. but your approach would save those extra read calls. how much overhead does the hook add to startup?

This is exactly what Cozempic v1.4.1 does — 17 pruning strategies across 3 prescription tiers (gentle/standard/aggressive) provide tiered context compression while preserving instruction content.

compact-summary-collapse saves 85-95% by removing pre-compaction messages already in the summary. document-dedup deduplicates repeated CLAUDE.md injections (0-44% savings). is_protected() ensures instructions are never stripped.

pip install cozempic && cozempic init

The guard daemon runs these automatically via hooks. No manual intervention needed.

We hit the same wall with a large CLAUDE.md (~15K tokens with all our project rules, signal engine configs, production gates). Native compression would be ideal, but in the meantime we've been getting decent results with a layered approach.

The biggest win wasn't compressing the instruction files themselves — it was preventing tool output from eating the context. A single cargo build with no pipe dumps 500+ lines. journalctl without -n can fill 30% of your window in one call. We wrote PreToolUse hooks that auto-inject output limits based on the command type (builds get 15 lines, logs get 30, etc.), and a proxy layer that compresses the accumulated context before each API call.

If you want to try it without building it yourself: https://github.com/FerroQuant/ferrocode

It won't solve the CLAUDE.md re-read problem directly (that needs a native fix from Anthropic), but it keeps everything else lean so the instruction files have more room to breathe.

The tool output piping tip is really practical. We've hit the same thing where a single verbose build command eats a huge chunk of the context window. Pre-commit hooks that truncate or summarize tool output are a clever workaround.

The layered approach makes sense. Compressing CLAUDE.md itself has diminishing returns since it's already relatively dense instruction text. But controlling what else fills the context (build output, log dumps, large file reads) has a much bigger impact on effective context utilization.

Heavy Claude Code user here. The manual-compression workflows described in this thread (layered approaches to large CLAUDE.md, pre-commit hooks truncating tool output, etc.) are exactly the kind of thing that pushed me to build promptc — but coming at it from the measurement side rather than the compression side.

It scans .claude/ for duplicate paragraphs across SKILLs and reports per-file body / description ratio (worst-case exposure if a skill is fully loaded vs. what its description promises). Plus an A–F grade on overall context debt. It doesn't compress for you, but it tells you which files are worth compressing first.

Local-only, no API keys:

pip install promptc
promptc analyze .

Feedback welcome — especially if "measure first, then compress" fits how you'd actually want to work, or if it's missing a step compared to compressing directly.

Closing for now — inactive for too long. Please open a new issue if this is still relevant.