[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
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗