[FEATURE] Implement HOT/WARM/COLD File Tiering System for 94.5% Token Cost Reduction

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

Every time Claude Code reads a codebase, users pay for all tokens loaded into context - regardless of relevance. Most projects contain:

• READMEs, changelogs, archived docs (rarely needed)
• Core patterns, config files (sometimes needed)
• Active task files (always needed)

Claude Code currently charges the same for all files, leading to inflated token costs and slower response times. Users are essentially paying for Claude to read outdated documentation and archived content on every session.

Real-world impact: A typical mid-size project with ~66,834 tokens loads ALL of this content into every session, even when only ~3,647 tokens (5.5%) are actively relevant to the current task.

Proposed Solution

Implement a HOT/WARM/COLD file tiering system inspired by cortex-tms (https://github.com/cortex-tms/cortex-tms):

HOT Tier: Active tasks, current work (~3,647 tokens)

• Always loaded into context
• Files with <!-- @cortex-tier HOT --> marker or in active sprint folders

WARM Tier: Patterns, glossary, recent docs (~10,419 tokens)

• Loaded when referenced or via explicit flag: claude --include-warm

COLD Tier: Archives, old sprints, changelogs (~52,768 tokens)

• Almost never loaded unless explicitly requested: claude --include-cold

Implementation Details:

1. Add tier markers to documentation files (comment-based, non-intrusive)
2. Provide claude status --tokens command to show token breakdown by tier
3. Default behavior: Load only HOT files
4. Smart detection: Automatically promote files to WARM when frequently accessed
5. Configuration file (.claude-tiering.yml) for custom tier rules

Real Results from cortex-tms dogfooding:

• Without tiering: 66,834 tokens/session
• With tiering: 3,647 tokens/session
• 94.5% reduction in token costs
• Faster responses (less context processing)
• Better focus (Claude sees current docs, not 6-month-old archives)

Cost Savings:

• Claude Sonnet 4.5: $0.01/session (was $0.11)
• GPT-4: $0.11/session (was $1.20)

This would give Claude Code users direct control over token costs while maintaining full access to their entire codebase when needed.

Alternative Solutions

Current workarounds being used:

1. Manually organizing files into separate directories and using selective @file references (tedious, error-prone)
2. Creating separate .claudeignore files for different contexts (requires switching configs)
3. Splitting large projects into multiple repositories (not always feasible)

Other tools addressing this:

• cortex-tms (open source, MIT license): Already implements this exact system with proven 94.5% cost reduction
• Manual token management via custom scripts (fragile, requires maintenance)

Why these don't fully solve it:

• cortex-tms is a separate tool - native Claude Code integration would provide seamless UX
• Manual approaches require constant vigilance and don't scale

Priority

High - Significant impact on productivity

Feature Category

Performance and speed

Use Case Example

Scenario: A developer working on a large SaaS application with extensive documentation

Current Workflow (without tiering):

1. Open Claude Code: claude
2. Claude loads entire project: 66,834 tokens
3. Ask: "Update the user authentication flow to support OAuth"
4. Wait while Claude processes 66K tokens (including 5-year-old changelogs, archived sprint docs)
5. Cost: $0.11 per session
6. Time: Slower responses due to large context

With File Tiering:

1. Developer tags files during setup:

• docs/sprints/CURRENT.md → HOT
• src/auth/README.md → HOT
• docs/patterns/oauth-guide.md → WARM
• CHANGELOG-2020.md → COLD

1. Open Claude Code: claude
2. Claude loads only HOT files: 3,647 tokens
3. Ask: "Update the user authentication flow to support OAuth"
4. Claude references WARM tier when needed (oauth-guide.md)
5. Cost: $0.01 per session (10x cheaper)
6. Time: Faster responses, focused context

When WARM/COLD needed:

• "Check what changed in version 2.0" → claude --include-cold
• "Review our OAuth implementation patterns" → Automatically loads WARM tier

Result: 94.5% cost reduction, faster responses, better focus

Additional Context

Reference Implementation: cortex-tms has already proven this concept works with 1,000+ NPM downloads and real-world usage. See their case study: https://cortex-tms.org/blog/cortex-dogfooding-case-study/

Community Interest: Based on Reddit discussions (r/ClaudeAI), many developers are actively seeking ways to reduce Claude API costs. This feature directly addresses a major pain point.

Implementation Considerations:

• Backward compatible: Works with existing projects without requiring changes
• Opt-in: Developers can choose to use tiering or continue with current behavior
• Non-intrusive markers: Comment-based tags don't affect code execution
• Cross-platform: Works with CLI, VS Code extension, and web interface

Benefits Beyond Cost:

1. Lower carbon footprint: Less GPU compute = reduced environmental impact
2. Better quality: Claude focuses on relevant, current documentation
3. Scalability: Enables larger projects to use Claude Code without prohibitive costs
4. Educational: Helps developers understand token usage patterns

MIT License: cortex-tms is open source and could serve as reference or even be integrated directly.