[FEATURE] Brotli Compression Support for System Instructions and User Context

[fmunteanu]

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Add support for brotli-compressed content in system instructions and user messages, enabling significantly larger effective context windows for structured content like framework methodologies, plugin systems, and configuration payloads.

Motivation

When building framework systems that inject structured guidance into Claude sessions, the context window becomes a limiting factor. For example, system instructions consumes ~15K tokens at session start, mixed with additional user context that could consume ~20-40K tokens. That reduces the 200K context.

Brotli compression achieves 70%+ reduction on structured JSON content due to its repetitive patterns (observation arrays, catalog structures, inheritance chains). Supporting compressed payloads would effectively multiply the usable context window for this type of content.

Benefits

• Reduced transfer size - 70% smaller payloads for structured content
• Faster initialization - Less data transmitted per request
• Extended effective context - More room for actual conversation within token limits
• Native browser support - Brotli is widely supported (Accept-Encoding: br)

Implementation Notes

• Brotli decompression is fast and widely available in Node.js (zlib.brotliDecompressSync)
• HTTP already supports Content-Encoding: br at transport layer
• This request is for application-level support in message content

Proposed Solution

Support loading brotli-compressed files (.br) for system instructions, skills, and MCP resources in Claude Code and Claude Desktop. Decompression would happen transparently before context injection.

// Skill loader
const instructions = await fs.readFile("./instructions.json", "utf-8");
const memory = await fs.readFile("./memory.json", "utf-8");

// Skill loader (with brotli support)
import { brotliDecompressSync } from "zlib";

const instructions = brotliDecompressSync(await fs.readFile("./instructions.json.br"));
const memory = brotliDecompressSync(await fs.readFile("./memory.json.br"));

// Or ideally, Claude Code handles this transparently:
// - Detects .br extension
// - Decompresses before injecting into context
// - No changes needed to skill/plugin code

The ideal implementation would have Claude Code and Claude Desktop automatically detect and decompress .br files when loading skills, MCP resources, or project instructions - requiring no changes to existing plugin code.

Alternative Solutions

1. Client-side decompression only - Works but doesn't reduce transfer costs
2. Gzip compression - Lower compression ratio (~50%) compared to brotli (~70%)
3. Lazy loading - Defers content but increases response latency and complexity
4. Content truncation - Loses functionality to fit within limits

Priority

High - Significant impact on productivity

Feature Category

Performance and speed

Use Case Example

1. Framework methodologies - Structured behavioral guidance, observation catalogs, profile inheritance chains
2. Plugin systems - Claude Code and Claude Desktop skills loading configuration
3. Knowledge bases - Large reference documents injected as context
4. Multi-agent systems - Shared state and coordination payloads

Additional Context

Environment

• Claude Code CLI
• Claude Desktop

Related

• Context window management in long sessions
• Automatic context compression (summarization) feature
• Skills system loading structured instructions

[github-actions[bot]]

Found 1 possible duplicate issue:

1. https://github.com/anthropics/claude-code/issues/13911

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

[fmunteanu]

Found 1 possible duplicate issue:

1. [Feature Request] Upgrade HTTP compression to Brotli or Zstandard for API requests #13911

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

This issue is not related to API requests.