[Feature] Expose instruction tokens (CLAUDE.md) in statusline JSON

Resolved 💬 3 comments Opened Jan 24, 2026 by vavasilva Closed Mar 1, 2026

Problem

When using custom instructions via CLAUDE.md files (global and project-level), there's no way to know how many tokens these instructions consume from the context window.

This information would help users:

  • Optimize their instructions to avoid wasting context
  • Understand the trade-off between detailed instructions and available context
  • Debug when context runs out faster than expected

Current Behavior

The statusline JSON includes context window usage:

{
  "context_window": {
    "total_input_tokens": 15234,
    "used_percentage": 42.5
  }
}

But there's no breakdown of what is consuming those tokens.

Proposed Solution

Add an instructions field to the statusline JSON:

{
  "instructions": {
    "global_tokens": 440,
    "project_tokens": 1170,
    "total_tokens": 1610,
    "files_loaded": [
      "~/.claude/CLAUDE.md",
      "./CLAUDE.md"
    ]
  }
}

Use Case Example

A statusline script could display:

[Opus] 📋 1.6k instruction tokens | 📊 42% context used

This gives users immediate feedback about their instruction "overhead" and helps them make informed decisions about instruction verbosity.

Additional Context

  • Instructions are always loaded when files exist, so this is purely informational
  • Token counts should reflect actual tokenization, not character-based estimates
  • This would be especially valuable for users with large project-specific instructions

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗