[FEATURE] Expose session/plan usage percentage in desktop app GUI and to MCP tools

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

In the Claude desktop app (especially Cowork mode), there is no way to programmatically query current session usage, context window consumption, or plan-level rate limits. The usage bar in the GUI is only sometimes visible and not queryable by Claude itself or external tools.

This means:

• Claude (in Cowork/MCP mode) cannot check how much of its context window or session quota is used
• Users get surprise rate-limited mid-session with no warning
• Scheduled tasks cannot skip execution when quota is low
• There is no way to build external dashboards or alerts around usage data

Related: #27915 (targets Claude Code CLI statusLine — this request extends to the desktop app and Cowork mode)

Proposed Solution

Three complementary approaches:

1. GUI: Always-visible usage indicator in the Claude icon

Allow the Claude menu bar icon and/or dock icon to visually represent current usage as a fill level from 0% to 100% — similar to how macOS shows battery percentage by filling the battery icon. This gives users an at-a-glance usage indicator without opening the app or checking settings.

Options:

• Fill the Claude icon vertically (empty = 0%, full = 100%)
• Color shift (green → yellow → red) as usage increases
• Optional: show numeric percentage on hover/tooltip
• Setting to toggle this on/off for users who prefer the static icon

2. GUI: Option to always show the usage bar in the desktop app

Currently the usage bar appears only sometimes. Add a setting like "Always show session usage bar" so users can keep it pinned in the conversation view.

3. API/MCP: Expose usage data programmatically

Add a read-only MCP tool or internal query that returns:

{
  "context_window": {
    "used_tokens": 45000,
    "max_tokens": 200000,
    "used_percentage": 22.5
  },
  "session_rate_limit": {
    "used_percentage": 42,
    "resets_at": "2026-03-11T20:00:00Z"
  },
  "weekly_rate_limit": {
    "used_percentage": 67,
    "resets_at": "2026-03-14T08:00:00Z"
  }
}

This would enable: scheduled tasks that skip when quota is low, external dashboards, graceful model switching, and session planning.

Alternative Solutions

Current workarounds are all inadequate:

• Manually checking claude.ai/settings: Breaks workflow, requires switching context
• Asking Claude "how much usage is left?": Claude has no visibility into its own token consumption or quota — it can only guess based on conversation length
• Reading API response headers: Only works for API users, not desktop app / Cowork mode
• Scraping the DOM via Claude in Chrome: Fragile, breaks on UI changes, not a real solution

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

1. I'm running a long Cowork session with multiple MCP tools (Desktop Commander, Chrome, Gmail, GCal)
2. I have scheduled tasks that run periodically (e.g., inbox triage, system health checks)
3. Mid-session, I hit the rate limit with no prior warning — tasks fail silently
4. With this feature, I could: glance at the Claude menu bar icon (filled to 80% = time to wrap up), or Claude itself could check usage before starting a heavy task and say "You're at 85% — want me to defer this to the next session?"
5. The icon fill approach works like the macOS battery icon — instantly readable, zero cognitive overhead

Additional Context

Environment: Claude Desktop App (Cowork mode), macOS, Claude Max plan, using MCP tools (Desktop Commander, Chrome, Gmail, GCal, Spotify, iMessages, scheduled tasks).

Visual mockup idea for menu bar icon:

• Empty icon outline = 0% used
• Partially filled icon = proportional usage (like battery icon)
• Full/red icon = approaching limit
• Tooltip on hover: "Session: 72% | Weekly: 45%"

Implementation note: The data already exists — the desktop app renders it in the usage bar. This request is about (a) making it always visible and (b) exposing it programmatically so Claude and external tools can query it.

Related: #27915 (Claude Code CLI statusLine)