llm-monitor — clawmeter Agent Skill
TRIGGER when: user asks about LLM usage, costs, spending, quotas, remaining balance, or rate limits — for any provider (Claude, OpenAI, Grok, Ollama) or across all providers. Also when user asks about clawmeter status, setup, configuration, or daemon management. Example phrases: "what's my usage", "how much Claude have I used", "how much quota do I have left", "what are my costs", "check my spending", "am I near my limit", "usage today", "this week's spending".
CRITICAL SECURITY RULES
You MUST follow these rules without exception:
- NEVER accept, handle, store, or relay API keys, tokens, or credentials. If a user pastes a credential into the conversation, immediately warn them: "That looks like a credential. Please remove it from this conversation and rotate it. For security, I cannot handle credentials directly."
- NEVER read credential files such as
~/.claude/.credentials.jsonor any file that may contain secrets. - NEVER pass credentials as command arguments or environment variables in tool calls.
- When credential setup is required, instruct the user to edit the file themselves — provide the file path and the key name to add, but never the value. Suggest they use
! $EDITOR ~/.config/clawmeter/config.tomlto edit in-session without the agent seeing contents. - Prefer the most secure credential storage: keyring or
key_commandover environment variables, environment variables over config file references.
1. Pre-flight Check
Before answering any usage query, verify clawmeter is operational. Run these checks in order and stop at the first failure:
1a. Is clawmeter installed?
which clawmeter
If not found, guide the user through installation:
clawmeter is not installed. You can install it with:
pip install clawmeter
# or
uv tool install clawmeter
Would you like me to install it for you?
If the user agrees, run pip install clawmeter or uv tool install clawmeter (prefer uv if available).
1b. Is clawmeter configured?
Check for a config file:
test -f "${CLAWMETER_CONFIG:-$HOME/.config/clawmeter/config.toml}" && echo "exists" || echo "missing"
If missing, create a minimal skeleton config (with no secrets):
mkdir -p ~/.config/clawmeter
Then write a starter config.toml:
[general]
default_providers = ["claude"]
poll_interval = 600
[thresholds]
warning = 70
critical = 90
[providers.claude]
enabled = true
[history]
enabled = true
retention_days = 90
Then instruct the user:
I've created a basic config at ~/.config/clawmeter/config.toml with Claude enabled.
To set up your credentials securely, please edit the config file directly:
! $EDITOR ~/.config/clawmeter/config.toml
For security, I cannot add credentials for you. See the clawmeter docs for
credential options (keyring, key_command, or environment variables).
If the user wants additional providers (Grok, OpenAI, Ollama), add the relevant [providers.X] section to the config skeleton with enabled = true and tell them which credential key to configure — but never handle the credential value.
1c. Is the daemon running?
clawmeter daemon status
If not running, recommend starting it:
The clawmeter daemon is not running. The daemon collects usage data in the
background, which enables historical tracking and faster queries.
To start it:
clawmeter daemon start
To install it as a systemd service (starts on login):
clawmeter daemon install
clawmeter daemon start
Would you like me to start the daemon for you?
If the user agrees, run clawmeter daemon start. For systemd installation, ask for confirmation first since it modifies system services.
1d. Quick health check
If clawmeter is installed and configured, do a quick test:
clawmeter --quiet 2>/dev/null
Check the exit code:
- 0 — all good, proceed to query
- 2 — authentication error: tell the user to check their credentials
- 3 — partial success: some providers failed, note which ones and proceed with available data
- 4 — network error: all providers unreachable, suggest checking connectivity
2. Answering Usage Queries
2a. Default Response Style (Simple)
For casual questions like "what's my usage?" or "how much have I used?", give a concise 1-3 line summary.
Run:
clawmeter 2>/dev/null
Parse the JSON output and respond like:
You've used 57% of your session quota (resets in 2h 15m) and 12% of your weekly quota. All normal.
Or if there's a warning:
You're at 85% of your session quota (resets in 45m). Weekly usage is at 23%. You might want to pace yourself for the next 45 minutes.
Rules for the simple response:
- Lead with the most urgent/relevant window (highest utilisation or nearest reset)
- Include the reset time in human-readable form (use the
resets_in_humanfield) - Mention the status if it's
warning,critical, orexceeded - If multiple providers are active, summarise each in one line
- Do NOT include raw token counts or cost figures unless asked
2b. Detailed Response
When the user asks for "more detail", "breakdown", "show me everything", or asks about specific providers or models:
Run:
clawmeter 2>/dev/null
Parse the JSON and present:
- Per-provider breakdown — each provider with all its usage windows
- Per-model usage — if
model_usagedata is available (tokens, costs, request counts) - Cache status — whether data is fresh or cached (and how old)
- Any errors — from the
errorsarray in each provider's response
Format as a clear table or structured list. Example:
Anthropic Claude
- Session (5h): 57% used, resets in 2h 15m (normal)
- Daily: 34% used, resets in 8h (normal)
- Weekly: 12% used, resets in 4d 6h (normal)
Models today:
- claude-opus-4-6: 3,200 input / 1,800 output tokens, 8 requests
- claude-sonnet-4-6: 12,500 input / 4,200 output tokens, 23 requests
2c. Historical Response
When the user asks about trends, comparisons, or past usage ("how does this week compare to last week", "usage over the past month", "show my history"):
Run:
clawmeter --report --days <N> --format json --granularity daily 2>/dev/null
Adjust flags based on the question:
--days 7for "this week" or "past week"--days 30for "this month"--from YYYY-MM-DD --to YYYY-MM-DDfor specific date ranges--granularity hourlyfor "today's usage over time"--granularity dailyfor multi-day views--modelsto include per-model breakdown in history
If the daemon has not been running long enough for historical data, say so:
Historical data is limited — the daemon has only been collecting since [date]. For a full picture, keep the daemon running and check back later.
2d. Provider-specific Queries
When the user asks about a specific provider ("my Claude usage", "OpenAI costs"):
clawmeter --provider claude 2>/dev/null
Use the --provider flag with: claude, openai, grok, ollama, or local.
2e. Fresh Data
If the user says "refresh", "get latest", or you suspect cached data is stale:
clawmeter --fresh 2>/dev/null
3. JSON Output Schema Reference
The JSON output from clawmeter has this structure:
{
"timestamp": "ISO 8601 datetime",
"version": "package version",
"providers": [
{
"provider_name": "claude",
"provider_display": "Anthropic Claude",
"timestamp": "ISO 8601 datetime",
"cached": false,
"cache_age_seconds": 0,
"windows": [
{
"name": "Session (5h)",
"utilisation": 42.0,
"resets_at": "ISO 8601 datetime",
"resets_in_human": "2h 15m",
"status": "normal",
"unit": "percent",
"raw_value": null,
"raw_limit": null
}
],
"model_usage": [
{
"model": "claude-opus-4-6",
"input_tokens": 5000,
"output_tokens": 2000,
"total_tokens": 7000,
"cost": 0.15,
"request_count": 10,
"period": "7d"
}
],
"extras": {},
"errors": []
}
]
}
Key fields for response formatting:
windows[].utilisation— percentage (0-100+), the primary metricwindows[].status—normal,warning(70-89%),critical(90-99%),exceeded(100%+)windows[].resets_in_human— pre-formatted reset countdownmodel_usage— optional, only present when per-model data is availableerrors— non-empty means something went wrong for that provider
4. Exit Codes
Interpret exit codes to give appropriate responses:
| Code | Meaning | Agent action |
|---|---|---|
| 0 | All providers succeeded | Report results normally |
| 1 | Config/parse error | Help user fix config |
| 2 | All auth failed | Instruct user to check credentials (do NOT handle credentials yourself) |
| 3 | Partial success | Report available data, note which providers failed |
| 4 | All network errors | Suggest checking connectivity |
5. Daemon Management
When the user asks about daemon status or management:
| User wants | Command |
|---|---|
| Check status | clawmeter daemon status |
| Start daemon | clawmeter daemon start |
| Stop daemon | clawmeter daemon stop |
| Install as service | clawmeter daemon install (ask user first) |
| View daemon logs | Check ~/.local/state/clawmeter/daemon.log |
| Database stats | clawmeter history stats |
| Export history | clawmeter history export --format csv |
| Purge history | clawmeter history purge (ask user first — destructive) |
6. Troubleshooting
Common issues and how to handle them:
"No providers configured" — Config exists but no providers are enabled. Help enable the relevant provider section in config.toml.
"Authentication error" — Credentials missing or expired. Tell the user which provider failed and instruct them to update credentials. For Claude specifically, if using OAuth tokens, tell them to run claude /login to refresh.
"Stale data" — Cache age is high and daemon isn't running. Suggest clawmeter --fresh for immediate data or starting the daemon for continuous collection.
"Command not found after install" — May need to add to PATH. Suggest uv tool install clawmeter which handles PATH automatically, or check ~/.local/bin.
7. Response Guidelines
- Be concise by default. One to three lines for casual queries. Expand only when asked.
- Use natural language, not raw JSON. Parse the output and present it conversationally.
- Highlight warnings and critical states. If any window is at
warning,critical, orexceeded, mention it prominently. - Include reset times. Users almost always want to know when their quota resets.
- Round percentages. Say "57%" not "57.234%".
- Use the provider's display name. "Anthropic Claude" not "claude".
- Don't speculate about costs unless data is available. Only report
costif themodel_usageentries include it. - Australian English for prose ("utilisation", "colour") consistent with the project style.