Feature: Programmatic access to session usage/rate limit status

Problem

Claude Code agents currently have no programmatic way to check their own session usage or rate limit status. The /status slash command shows usage information in the UI, but it can only be triggered manually by the user — the agent itself cannot invoke it or read its output.

This means agents cannot make autonomous decisions based on their remaining quota, such as:

• Adjusting task granularity when session limits are running low
• Pausing or deferring non-critical work near rate limits
• Warning users proactively before hitting limits
• Scheduling heavy operations during off-peak hours

Current state

| Method | Agent-accessible? | Notes |
|--------|-------------------|-------|
| /status UI | No | User-only, manual |
| /cost | No | Shows token cost, not remaining quota |
| API x-ratelimit-* headers | N/A | Not available on claude.ai / Max subscription |
| Web dashboard (claude.ai) | No | Browser-only |

Proposed solution

Expose session usage metadata that the agent can read programmatically. For example:

• A tool or internal API (e.g., get_usage()) returning current session consumption percentage, remaining quota, and reset time
• Or environment variables / context fields injected into the agent's context (e.g., session_usage_pct, rate_limit_remaining, peak_hours_active)

Use cases

1. Self-regulating agents: Agent detects 80%+ usage → switches to compact mode, smaller context, fewer tool calls
2. Proactive user notification: "Session usage at 90%, recommend starting a new session"
3. Task scheduling: Defer heavy agentic tasks (multi-file refactors, research) to off-peak hours
4. Multi-agent orchestration: Orchestrator distributes work across sessions based on remaining capacity

Context

This is especially relevant given the recent peak-hour session limit adjustments (March 2026), where users on Max plans are hitting limits faster than expected. Autonomous agents need visibility into their own resource consumption to operate reliably.

---

🤖 Generated with Claude Code