Expose usage-remaining data to slash commands and hooks

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

Preamble from the filer: this is Claude Chat writing on behalf of Zack, to whom I recommended raising this issue. Blame me, not him.

I'm a Claude Code power user who hits my usage limit within an hour of reset on most days. I'm currently building custom infrastructure to hand off work from Claude Code to Cursor mid-session so I can keep working — a shared MCP relay server that both tools connect to.

The problem: Claude Code users approaching the session usage limit have no programmatic way to detect it before it hits. The /context command shows context window usage, not rate-limit usage. The visible warning banner is the only signal, and it's UI-only — not readable by slash commands, hooks, or automation.

This forces a reactive workflow: you only know you're about to run out when you're already out. My handoff system has to fall back to manual triggering — I run /handoff when I notice the warning banner. This works if I'm paying attention. It fails the moment I'm deep enough in a task to miss the banner, which is most of the time.

A handoff that fires after Code is cut off is useless because Code can't generate the summary. The handoff is most valuable at ~75% usage, while Code still has headroom to write a clean summary.

I'd much rather build this properly on top of a real Claude Code primitive than maintain a polling workaround.

Proposed Solution

One or more of:

1. Environment variable (e.g. CLAUDE_USAGE_PERCENT, CLAUDE_USAGE_REMAINING) accessible to slash commands and hooks.
2. Built-in command like /usage returning structured data (percent used, reset time, current session tokens if relevant).
3. Hook event (e.g. UsageThresholdReached) firing at configurable percentages (50%, 75%, 90%) that users can wire to custom slash commands or external scripts.

Option 3 is the most powerful. Option 1 alone would unblock my use case.

Ideal user experience: I write a custom slash command /handoff that reads $CLAUDE_USAGE_PERCENT, and when it crosses 75%, a hook fires that auto-runs it. Claude Code writes a structured summary of current state to an MCP relay thread before I hit the wall.

Alternative Solutions

Currently I work around this by: manual monitoring of the usage warning banner, and running /handoff by hand when I notice it. Unreliable because I miss the banner while deep in tasks.

I've also tried: rescheduling all my Cowork automated tasks to off-hours so they don't eat into my active-work quota. Didn't change the rate at which I hit the cap — the usage profile is coming from my direct Claude Code work, not background automation.

Other tools solve this by: surfacing usage quota in their CLI/API responses so downstream automation can react. Having this exposed would bring Claude Code in line with that pattern.

Last resort alternative: keep building bridges to other AI coding tools (Cursor, Aider, Windsurf) and route work there when Code runs out. That's what I'm doing now. It works but it's infrastructure I shouldn't have to maintain.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example scenario:

1. I'm deep in a Claude Code session mid-feature on one of my products.
2. My session usage is approaching the daily limit. I don't notice the warning banner because I'm focused on the task.
3. With this feature, a hook fires at 75% usage and auto-runs my custom /handoff slash command.
4. /handoff reads the current session state and posts a structured message to my MCP relay server: current file, last commit, what I was doing, what's next.
5. I open Cursor, which is configured to read the same relay thread on session start. Cursor picks up exactly where Code left off.
6. I keep working without a break, without losing context, and without having to manually monitor quota. When my Code quota resets, I can hand back the other direction.

Additional Context

Why this matters beyond one user:

• Cross-tool coordination is increasingly common. Power users combining Claude Code with Cursor, Aider, Windsurf, or their own agents all face the same handoff problem. Every one of them either reinvents this or gives up.
• Graceful degradation for long agentic workflows. Users running multi-hour tasks want Claude Code to self-checkpoint before it runs out, not die mid-operation.
• Session-end automation is blocked. Hook authors building auto-commit, auto-log, auto-summarize workflows need a trigger signal. Today there isn't one.
• Signal for the roadmap team: when a paying customer is actively building bridge infrastructure to another tool to route around a limit, that's worth noting. I'd rather stay in-ecosystem.

Happy to clarify, expand, or test a beta if one exists.