Interactive TUI Implementation Plan

Interactive TUI Implementation Plan

Transform Claude Code Usage Monitor from a read-only Rich dashboard to an interactive Textual TUI.

Status: Implementation Complete Created: 2025-12-13 Updated: 2025-12-14 Documents: 4 supporting documents in this folder

Vision

An interactive terminal experience that empowers developers to monitor, analyze, and control their Claude AI token usage through efficient keyboard-driven interactions—without breaking their development flow.

Jobs To Be Done

Primary Job

"When using Claude Code, I want to understand my token consumption and remaining capacity so I can make informed decisions about my work session without interruption."

Supporting Jobs

Experience Principles

Feature Set

Phase 1: Foundation

• Textual app skeleton
• Dashboard view with real-time updates
• Basic keyboard navigation
• Pause/Resume functionality

Phase 2: Views

• Daily aggregation view
• Monthly aggregation view
• Agents activity view
• View switching (1-4 keys)

Phase 3: Interactivity

• Panel focus/navigation
• Drill-down into details
• Filter/search functionality
• Help overlay (?)

Phase 4: Analysis

• What-if scenario calculator
• Comparison mode (today vs yesterday) - future
• Historical trends with sparklines - future
• Peak hours analysis - future

Phase 5: Advanced

• Configurable alert thresholds - future
• Agent relationships view - future
• Model efficiency metrics - future
• Density modes (compact/normal/detailed) - future

Technical Approach

Framework Migration: Rich → Textual (parallel development)

Current: Rich Live (read-only)
    ↓
New: Textual App (interactive)
    - Screen-based views
    - Widget composition
    - Reactive state
    - Keyboard events

Key Technical Decisions:

1. Parallel development - New tui/ module alongside existing ui/
2. Centralized state - AppState dataclass with reactive properties
3. Thread safety - call_from_thread() for background updates
4. TCSS theming - Dark/light detection, CSS-like styling

Implementation Summary

Files Created

src/claude_monitor/tui/
├── __init__.py
├── app.py                 # ClaudeMonitorApp main class
├── bindings.py            # Keyboard bindings configuration
├── events.py              # Custom Textual events
├── styles.tcss            # Textual CSS theme
├── screens/
│   ├── __init__.py
│   ├── base.py            # BaseMonitorScreen class
│   ├── dashboard.py       # Real-time monitoring
│   ├── daily.py           # 7-day aggregation
│   ├── monthly.py         # 3-month aggregation
│   ├── agents.py          # Agent activity
│   ├── help.py            # Help overlay modal
│   └── whatif.py          # What-if calculator modal
├── widgets/
│   ├── __init__.py
│   ├── header.py          # App header
│   ├── footer.py          # App footer with hints
│   ├── usage_panel.py     # Token/cost overview
│   ├── progress_bars.py   # TokenBar, CostBar, TimeBar
│   ├── burn_rate.py       # Consumption rate display
│   ├── predictions.py     # Usage projections
│   ├── model_usage.py     # Per-model breakdown
│   ├── session_table.py   # Daily/monthly data table
│   └── agent_table.py     # Agent data table
└── state/
    ├── __init__.py
    └── app_state.py       # AppState, SessionState

Files Modified

Usage

# Launch interactive TUI
claude-monitor --tui

# With specific plan
claude-monitor --tui --plan max5

# With custom refresh rate
claude-monitor --tui --refresh-rate 5

Keyboard Shortcuts

Documents

Success Criteria

1. ✅ Developers can check usage in <3 seconds (glanceable dashboard)
2. ✅ No mouse required for any task (keyboard-first)
3. ✅ Works on smallest reasonable terminal (60x20 minimum)
4. ✅ Advanced features discoverable but not intrusive
5. ✅ Users report feeling "in control" of their usage

Future Enhancements

1. Comparison mode (today vs yesterday)
2. Historical trends with sparklines
3. Peak hours analysis
4. Configurable alert thresholds
5. Agent relationships visualization
6. Model efficiency metrics
7. Density modes (compact/normal/detailed)