Fine-tuned Context Monitor

Real-time context window usage monitoring with visual progress bars and auto-compact warnings.

When to Use This Setting

Apply this setting when you need to:

• Track conversation context consumption with visual progress indicators to prevent unexpected session limits
• Monitor session analytics including cost estimates, duration, and lines of code changed
• Receive proactive warnings when context usage approaches the limit so you can compact before interruption Consider alternatives when:
• You prefer a minimal statusline and track context usage through other means
• Your sessions are typically short and context limits are never a concern

Quick Start

Configuration

Copy
name: fine-tuned-context-monitor
type: setting
category: statusline

Example Application

Copy
claude setting:apply fine-tuned-context-monitor

Example Output

Setting applied. Changes:
- statusLine: Context monitor with progress bars and session analytics
- Script: .claude/scripts/context-monitor.py

Core Concepts

Context Monitoring Overview

Aspect	Details
Usage Tracking	Monitors the percentage of context window consumed by the current conversation
Progress Bars	Visual ASCII or Unicode progress bars showing context fill level
Color Alerts	Green (<60%), yellow (60-80%), red (>80%) color coding for urgency levels
Auto-compact Warning	Displays a prominent warning when context approaches the compaction threshold

Monitor Display Architecture

+---------------------------+
|  Context Monitor Engine   |
|  .claude/scripts/         |
|  context-monitor.py       |
+---------------------------+
         |
    +----+----+----+
    |    |    |    |
    v    v    v    v
  Usage  Cost  Time Lines
  Bar    Est.  Dur  Changed
         |
         v
+---------------------------+
|  Color-coded Output       |
+---------------------------+
|  [====----] 62% (yellow)  |
|  Cost: $0.42 | 23min      |
|  Lines: +142 -38          |
+---------------------------+
         |
    >80% triggers
         |
         v
+---------------------------+
|  AUTO-COMPACT WARNING     |
|  Context nearing limit    |
+---------------------------+

Configuration

Parameter	Type	Default	Description
statusLine.type	string	"command"	Status line type using Python script for dynamic monitoring
statusLine.command	string	"python3 .claude/scripts/context-monitor.py"	Path to the context monitoring Python script
Warning Threshold	number	80	Percentage of context usage that triggers the auto-compact warning
Alert Threshold	number	60	Percentage of context usage that changes the progress bar from green to yellow
Critical Threshold	number	90	Percentage of context usage that changes the progress bar to red

Best Practices

1. Install the monitoring script before applying - The setting references .claude/scripts/context-monitor.py. Create this directory and script before applying the setting to avoid errors on first use.
2. Set warning thresholds based on your work style - If you frequently work on large refactoring tasks that consume context quickly, set the warning threshold lower to give yourself more time to compact.
3. Use the cost estimate for budget tracking - The session cost estimate helps teams monitor their Claude Code spending. Review costs at the end of each session to identify optimization opportunities.
4. Compact proactively when warned - When the auto-compact warning appears, save your current progress and use the /compact command. Waiting until context is exhausted may cause lost context.
5. Customize the progress bar style - The Python script can be modified to use different bar characters, widths, and color schemes. Match the visual style to your terminal theme for a cohesive look.

Common Issues

1. Python script not found - The setting expects the script at .claude/scripts/context-monitor.py relative to the project root. Create the directory structure and script before applying this setting.
2. Context percentage shows 0% - The monitor may not have access to actual context window usage data. Verify that the script correctly reads the session context JSON from stdin.
3. Colors not displaying - The Python script uses ANSI color codes. If your terminal shows raw escape sequences, ensure your terminal supports ANSI colors or modify the script to use plain text indicators.