Feature Request: Add "/usage" Command for Context Usage Visualization

[will-lamerton]

Description

Add a new /usage command that provides a detailed visual breakdown of current context usage, helping users understand how their context window is being utilized and how much capacity remains.

Use Case

Users working with AI models need to understand their context consumption to:

• Monitor context limits: See how close they are to hitting model limits
• Optimize conversations: Identify what's consuming the most tokens
• Plan interactions: Know how much context is available for new messages
• Debug performance: Understand why responses might be slower or truncated
• Make informed decisions: Choose when to start a new session vs continue current one

This is especially important for local models with smaller context windows or when working on large projects with extensive system prompts.

Proposed Solution

Implement a /usage command that displays:

1. Context Breakdown

Visual representation showing token usage across categories:

• System Prompt: Base system prompt + NANOCODER.md content
• Messages: User and assistant conversation history
• Tools: Tool definitions and recent tool call results
• Available: Remaining context capacity

2. Visual Display Format

Context Usage (4,250 / 8,192 tokens) ████████████░░░░ 52%

┌─ System Prompt        1,200 tokens ██████░░░░░░░░░░ 15%
├─ Messages            2,800 tokens ██████████████░░ 34%
├─ Tools                 250 tokens ██░░░░░░░░░░░░░░  3%
└─ Available           3,942 tokens ░░░░░░░░░░░░░░░░ 48%

Recent Activity:
• Last 5 messages: 890 tokens
• Last tool call: 156 tokens
• Largest message: 245 tokens

Model: claude-4-sonnet (8,192 token limit)
Provider: OpenRouter

3. Detailed Breakdown

• Message-by-message token counts
• Individual tool usage
• System prompt component breakdown
• Historical context consumption patterns

Technical Implementation

Command Structure

• Location: src/core/commands/usage.ts
• Integration: Add to existing command registry

Token Counting

• Integrate with existing tokenization logic used by LLM clients
• Cache token counts to avoid recalculation

Data Collection

• Access current ChatSession message history
• Retrieve active tool definitions
• Get system prompt content (including NANOCODER.md)
• Query current model limits from provider configuration

Display Components

• Use existing CLI styling (colors)
• ASCII progress bars for visual representation - Ink might have a component
• Tabular data for breakdowns
• Color coding (green=safe, yellow=warning, red=near limit)

Model Integration

• Read model context limits from provider configurations
• Support different limits per model/provider
• Handle unknown limits gracefully

Acceptance Criteria

• /usage command appears in help menu
• Shows total context usage with visual progress bar
• Breaks down usage by category (system, messages, tools)
• Displays remaining available context
• Shows current model and provider information
• Includes recent activity summary
• Handles different tokenizers per provider
• Visual warnings when approaching context limits
• Graceful handling of unknown model limits

Additional Context

This feature would provide essential visibility into context usage, helping users optimize their interactions with AI models. It's particularly valuable for:

• Power users managing complex conversations
• Developers working on large codebases where system prompts are extensive
• Local model users with tighter context constraints
• Anyone wanting to understand AI model resource consumption

The command should integrate seamlessly with the existing CLI interface and leverage the project's established patterns for displaying information to users.

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update