Claude Code Context Statusline

Real-time context window monitoring for Claude Code – Know exactly how much context you have left before you hit the limit.

A lightweight, accurate statusline module that displays your current context usage in Claude Code, helping you manage long conversations and avoid unexpected context limits.

🎯 Why You Need This

When working with Claude Code on complex projects, you might not realize you're running out of context until it's too late. This statusline gives you instant visibility into your context usage, displayed right at the bottom of your terminal.

Problems this solves:

• ❌ Losing progress when hitting context limits unexpectedly
• ❌ Not knowing when to use /compact to free up space
• ❌ Guessing how much context budget you have left
• ❌ Context resets that could have been avoided with better awareness

What you get:

• ✅ Visual ASCII progress bar showing usage at a glance
• ✅ Real-time context usage percentage
• ✅ Remaining context percentage
• ✅ Color-coded warnings (green → yellow → red)
• ✅ Automatic reset tracking after /compact
• ✅ Accurate calculations - matches /context command exactly (more accurate than Claude's built-in indicator)

📸 What It Looks Like

Sonnet 4.5 | [█████░░░░░░░░░░░░░┃░] 25.3% used | 74.7% free
session: 93e6f36e-be31-4466-956e-3279f6ad7790
                          ↑ auto-compact at 95%

Features:

• 📊 Visual progress bar - See your usage at a glance
• 🎨 Color-coded warnings - Bar changes color as you fill up
• ⚡ 95% threshold indicator - Yellow line marks critical warning point (auto-compact default)
• 💫 Flashing warning - Indicator blinks when within 5% of threshold
• 📈 Dual percentages - Both used and remaining shown
• 🎛️ Useful for everyone - Helpful whether auto-compact is enabled or you prefer manual control

Color coding:

• 🟢 Green (0-69%): You're good, plenty of space
• 🟡 Yellow (70-89%): Getting full, consider compacting soon
• 🔴 Red (90-100%): Time to compact or start fresh

🚀 Installation

Step 1: Download the Script

Save the context-statusline.js file to your Claude configuration directory:

# Download to ~/.claude/
curl -o ~/.claude/context-statusline.js https://gitlab.com/second-factory-tools/claude-code-context-statusline/-/raw/main/context-statusline.js

# Make it executable
chmod +x ~/.claude/context-statusline.js

Step 2: Configure Claude Code

Add the statusline configuration to your ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/context-statusline.js",
    "padding": 0
  }
}

If you already have other settings, just add the statusLine section:

{
  "alwaysThinkingEnabled": true,
  "statusLine": {
    "type": "command",
    "command": "~/.claude/context-statusline.js",
    "padding": 0
  }
}

Step 3: Restart or Refresh

The statusline will appear automatically. If it doesn't show up immediately, try starting a new conversation.

💡 Usage Examples

Example 1: Normal Development Session

Sonnet 4.5 | [███░░░░░░░░░░░░░░┃░] 15.2% used | 84.8% free

Green bar - you're early in a session. Yellow ┃ shows auto-compact threshold at 95%.

Example 2: Long Conversation

Sonnet 4.5 | [██████████████░░░┃░] 73.5% used | 26.5% free

Yellow warning - bar changes color, getting closer to the threshold.

Example 3: Approaching Auto-Compact

Sonnet 4.5 | [█████████████████┃░] 91.0% used | 9.0% free

Red alert - threshold indicator FLASHES! Auto-compact will trigger at 95%.

Example 4: After Auto-Compact

Sonnet 4.5 | [███░░░░░░░░░░░░░░┃░] 18.3% used | 81.7% free

Back to green - context automatically reset after Claude's auto-compact!

🔧 How It Works

The script:

1. Reads your session transcript (conversation history)
2. Parses API usage data from each message
3. Calculates total context consumption
4. Displays percentage used vs. 200k token limit
5. Automatically detects /compact commands and resets tracking

Technical details:

• Monitors cache_read_input_tokens, input_tokens, and output_tokens
• Filters out synthetic messages and side-chain contexts
• Updates every ~300ms (Claude Code's refresh rate)
• Zero performance impact - reads from existing transcript files

Accuracy Note

Our calculations match Claude's official /context command exactly. You may notice Claude Code's built-in context indicator (bottom-right of terminal) sometimes shows different percentages - this appears to be a calculation inconsistency in Claude Code itself. Always trust /context and our statusline for accurate numbers.

To verify: Run /context and compare the percentages - you'll see our tool matches the official output perfectly.

📊 Context Management Best Practices

Understanding the auto-compact indicator:

• The yellow ┃ line marks the 95% threshold - a critical warning point
• Auto-compact enabled (default): Claude automatically compacts at this threshold
• Auto-compact disabled: The indicator still serves as a useful warning to manually compact
• When you get within 5% (90-95%), the indicator flashes as a warning
• The indicator is helpful for all users regardless of auto-compact settings

Note: The statusline cannot detect if auto-compact is enabled, so the indicator always shows. This is intentional - it provides valuable context management guidance whether you rely on auto-compact or prefer manual control. You can disable the indicator by setting SHOW_AUTO_COMPACT_INDICATOR = false in the script if you don't find it useful.

When to manually compact:

• 🟡 Yellow (70%+): Good time to compact if you're starting a new task
• 🟠 Orange (85%+): Consider compacting to avoid auto-compact mid-task
• 🔴 Red (90%+): Flashing indicator warns auto-compact is imminent

Tips:

• Run /compact between major tasks or features
• Watch for the flashing indicator during long sessions
• Manual compacting gives you control over when context resets
• Use the percentage to plan how much work you can fit in a session

🎨 Customization

Want to modify the display? The script is well-commented and easy to customize:

// Change the context window size (default: 200,000)
const CONTEXT_WINDOW = 200_000;

// Adjust progress bar width
const PROGRESS_BAR_WIDTH = 20; // Number of segments

// Toggle progress bar on/off
const SHOW_PROGRESS_BAR = true; // Set to false for text-only mode

// Auto-compact threshold (Claude defaults to 95%)
const AUTO_COMPACT_THRESHOLD = 95;

// Show/hide the auto-compact indicator
const SHOW_AUTO_COMPACT_INDICATOR = true;

// Customize color thresholds
function color(p) {
  if (p >= 90) return "\x1b[31m"; // red
  if (p >= 70) return "\x1b[33m"; // yellow
  return "\x1b[32m"; // green
}

Display modes:

• With progress bar + indicator (default): [████░░░░░░┃░] 25.3% used | 74.7% free
• Progress bar only: Set SHOW_AUTO_COMPACT_INDICATOR = false
• Text-only mode: Set SHOW_PROGRESS_BAR = false

🤝 Contributing

Found a bug? Have an idea for improvement?

• Open an issue on GitLab
• Submit a merge request
• Share your customizations

📝 License

MIT License - feel free to use, modify, and share!

🙏 Credits

Created by the Claude Code community. Special thanks to all contributors who helped refine the accuracy and user experience.

---

Pro tip: Combine this with the built-in /context command for detailed breakdowns of where your tokens are going (system prompt, tools, memory files, messages).