hermes - 💡(How to fix) Fix Add `hermes usage` CLI command and agent-accessible quota tool [1 pull requests]

Feature Description

Expose the same live token/account quota information currently available via the gateway /usage slash command through:

1. a CLI command: hermes usage
2. optionally an agent-accessible tool: get_usage / quota_status

The command should report current session usage, context usage, token counts, API calls, cost if available, and provider account limits such as session/weekly remaining percentages and reset times.

Motivation

In Telegram/gateway sessions, /usage can show useful live limits for providers such as openai-codex (Plus), including:

• Session remaining / used percentage
• Session reset time
• Weekly remaining / used percentage
• Weekly reset time
• Context usage
• Input/output/cache-read tokens
• API calls

However, the agent cannot currently query this information directly through tools or CLI. Before starting large tasks — repo analysis, coding features, subagents, long research, large file/log reads — the agent has to ask the user to manually run /usage and paste the result.

This makes quota-aware autonomous task planning harder and increases the chance of exhausting limits halfway through a task.

Proposed Solution

Add:

bash hermes usage

with output equivalent to /usage.

Also add a structured machine-readable mode:

bash hermes usage --json

Example JSON fields:

json { "model": "gpt-5.5", "provider": "openai-codex", "plan": "Plus", "tokens": { "input": 137182, "cache_read": 846336, "output": 7985, "total": 991503 }, "api_calls": 28, "context": { "used": 75247, "limit": 272000, "percent": 28 }, "limits": { "session": { "remaining_percent": 86, "used_percent": 14, "resets_at": "2026-05-08T14:00:00Z" }, "weekly": { "remaining_percent": 97, "used_percent": 3, "resets_at": "2026-05-12T06:50:00Z" } } }

Then expose this to the agent as a tool, so it can proactively check quota before large tasks and warn/split/wait before beginning expensive work.

Alternatives Considered

• Keep using /usage manually in gateway chats.
• Use hermes insights, but this is retrospective and does not expose live account remaining limits.
• Use provider dashboards, but this is provider-specific and not accessible to the agent.

Benefits

• Better quota-aware planning.
• Fewer interrupted long-running tasks.
• Easier automation.
• Better UX across CLI and gateway.
• Enables agent policies like “check quota before large tasks”.

Related work / context

There are existing quota-related issues such as #9085, #6564, #6589, and #15167. This request is specifically about exposing the live /usage-style information through a CLI command and ideally a structured agent/tool interface, so agents can perform quota checks autonomously before large tasks.