claude-code-status-line 1.2.3

# Known Issues

This page documents known limitations and issues with the Claude Code statusline.

## 🔔 Claude Notification Messages Obstruct Status Line

**Issue:** Claude Code displays notification messages on the right side of the terminal, which can overlap and obstruct the statusline.

**Impact:**
- Quota limit warnings
- System notifications
- Error messages

**Workaround:** None available. This is a limitation of how Claude Code renders notifications.

**Status:** Cannot be fixed from the statusline side. This would require changes to Claude Code itself.

---

## 📊 Quota Notification is 1% Behind

**Issue:** When Claude Code displays a notification about quota limits being almost reached, the percentage shown in the notification is often 1% behind the actual quota value displayed in the statusline.

**Example:**
- Statusline shows: `5h: 95%`
- Claude notification says: "Quota at 94%"

**Explanation:** This appears to be a bug in Claude Code's notification system. The statusline fetches quota data directly from the API endpoint (`https://api.anthropic.com/api/oauth/usage`) and displays the current values accurately. You can verify this matches the [official usage page](https://console.anthropic.com/settings/usage).

**Verification:**
```bash
# Check what the statusline is reading
curl -H "Authorization: Bearer YOUR_TOKEN" \
     -H "anthropic-beta: oauth-2025-04-20" \
     https://api.anthropic.com/api/oauth/usage
```

**Status:** Claude Code bug, not a statusline issue.

---

## 🎨 Powerline Characters Not Supported in Default Terminals

**Issue:** Powerline arrow characters () display as boxes, question marks, or other invalid characters in most default terminal applications.

**Affected Terminals:**
- **macOS:** Terminal.app (default), iTerm2 without Powerline fonts
- **Linux:** GNOME Terminal, Konsole, xterm (default configurations)
- **Windows:** Command Prompt (cmd.exe), older versions of Windows Terminal

**Why This Happens:**
Powerline characters are Unicode symbols (U+E0B0, U+E0B1, etc.) that are NOT part of standard fonts. They require special "Powerline-patched" fonts that include these glyphs.

**Solutions:**

### Option 1: Install Powerline Fonts (Recommended if you like the look)

**macOS:**
```bash
# Install via Homebrew
brew tap homebrew/cask-fonts
brew install font-meslo-lg-nerd-font

# Or manually download from:
# https://github.com/powerline/fonts
```

**Linux:**
```bash
# Ubuntu/Debian
sudo apt install fonts-powerline

# Arch Linux
sudo pacman -S powerline-fonts

# Or download from:
# https://github.com/powerline/fonts
```

**Windows:**
```powershell
# Download from:
# https://github.com/powerline/fonts
# Or use Windows Terminal with Cascadia Code PL
```

Then configure your terminal to use a Powerline font:
- **iTerm2:** Preferences → Profiles → Text → Font → Select a "Nerd Font" or "Powerline" font
- **Terminal.app:** Preferences → Profiles → Font → Select a Powerline font
- **Windows Terminal:** Settings → Profiles → Appearance → Font face

### Option 2: Disable Powerline (Simpler)

Edit `~/.claude/statusline/settings.json`:
```json
{
  "display": {
    "use_powerline": false,
    "segment_separator": " | "
  }
}
```

Or run:
```
/customize-statusline
```

**Status:** Expected behavior. User configuration required.

---

## 🔢 Context Value Mismatch with `/context`

**Issue:** The context usage shown in the statusline may differ from what `/context` displays in Claude Code.

**Example:**
- Statusline: `110k/200k (55%)`
- `/context` command: `104k/200k`

### Why This Happens

The statusline and `/context` use **different data sources** with different information:

#### Statusline Calculation

The statusline receives JSON input from Claude Code with this structure:
```json
{
  "context_window": {
    "context_window_size": 200000,
    "current_usage": {
      "input_tokens": 8,
      "cache_creation_input_tokens": 568,
      "cache_read_input_tokens": 90608
    }
  }
}
```

**Formula:**
```
content_tokens = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
total_used = content_tokens + autocompact_buffer_size
percentage = (total_used / context_window_size) × 100
```

**Key point:** The statusline includes the **autocompact buffer** (default: 45,000 tokens) to show when Claude Code will trigger autocompact. This is a safety margin.

#### `/context` Command

The `/context` command has access to:
- Full conversation history
- Message boundaries
- Turn-by-turn token counts
- Cache hit ratios
- Detailed breakdown of each message

It calculates context based on the **actual conversation structure**, not the raw token data provided to the statusline.

### What the Statusline CANNOT Access

The statusline does **not** have access to:
- Individual message contents
- Turn-by-turn breakdowns
- Cache efficiency metrics
- Conversation history structure
- Per-message token counts

It only receives the aggregated `current_usage` data shown above.

### Which One is "Correct"?

**Both are correct** for their purposes:

- **`/context`** - Shows actual conversation token usage for the current session
- **Statusline** - Shows total allocated tokens including safety buffer, useful for knowing when autocompact will trigger

### Configuration

You can adjust the autocompact buffer in `settings.json`:
```json
{
  "sections": {
    "context": {
      "autocompact_buffer_size": 45000  // Reduce or increase as needed
    }
  }
}
```

Set to `0` to match `/context` more closely (not recommended - won't warn about autocompact).

**Status:** Expected behavior. Different tools, different purposes.

---

## ⏸️ Context Hidden at 100% 5h Quota

**Issue:** When the 5h quota limit reaches 100%, the statusline hides the context section to avoid showing stale data.

**Example:**
- Quota: `5h: 100%`
- Context displays: `ctx: -`

**Note:** The 7d quota limit does NOT affect context display, as it doesn't actually block API access. Only the 5h limit blocks requests.

### Why This Happens

When the 5h quota is maxed out (100%), Claude Code cannot make any new requests to the API. This means:
1. No new context window data is generated
2. The last known context value becomes "stuck"
3. The statusline has no way to refresh this data

### How We Handle It

**Since v1.2.0** (improved in v1.2.2), the statusline automatically detects when the 5h quota hits 100% and displays:
```
ctx: -
```

This indicates that context data is unavailable due to the 5h quota limit being reached.

**Implementation:**
```rust
// Check if 5h quota is at 100% (only 5h limit blocks API access, not 7d)
let quota_maxed = quota.as_ref().is_some_and(|q| {
    q.five_hour_pct.is_some_and(|p| p >= 100.0)
});

// Don't show stale context when quota is maxed
let ctx = if config.sections.context.enabled && !quota_maxed {
    calculate_context(input.context_window.as_ref(), &config)
} else {
    None  // Shows "ctx: -"
};
```

**Status:** Working as intended. This is now handled gracefully by showing "ctx: -" only when the 5h limit is reached.

---

## 🖥️ Platform and Terminal Compatibility

**Development Environment:**
- **Platform:** macOS (Apple Silicon)
- **Terminal:** [Warp](https://www.warp.dev/)
- **Testing:** Primarily tested in Warp terminal on macOS

**Other Platforms:**
While the statusline is designed to work cross-platform (macOS, Linux, Windows), testing on other platforms and terminals is **community-driven**. If you encounter issues on:
- Different terminal emulators (iTerm2, Alacritty, Kitty, GNOME Terminal, etc.)
- Different operating systems (Linux distributions, Windows)
- Different shells (bash, zsh, fish, PowerShell)

Please report them with detailed information including:
- Platform and OS version
- Terminal emulator and version
- Shell type and version
- Statusline version
- Screenshots or error messages

**Testing Status:**
- ✅ **Tested:** macOS + Warp
- ⚠️ **Community testing needed:** All other combinations

## 📝 Summary

| Issue | Impact | Workaround | Status |
|-------|--------|------------|--------|
| Notification overlap | Visual | None | Cannot fix |
| Quota notification lag | Informational | Trust statusline | Claude Code bug |
| Powerline characters | Visual | Install fonts or disable | User config |
| Context mismatch | Informational | Understand difference | Expected |
| Quota 100% stuck | Functional | Shows "ctx: -" | Fixed in v1.2.0 |

---

## 🐛 Reporting New Issues

Found a bug or issue not listed here?

1. Check the [Troubleshooting Guide](Troubleshooting) first
2. Search [existing issues](https://github.com/ndave92/claude-code-status-line/issues)
3. If it's new, [create an issue](https://github.com/ndave92/claude-code-status-line/issues/new) with:
   - Your platform (macOS/Linux/Windows)
   - Statusline version (`claude-code-status-line --version`)
   - Steps to reproduce
   - Expected vs actual behavior