llm-monitor — clawmeter Agent Skill\r

\r 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".\r \r ---\r \r

CRITICAL SECURITY RULES\r

\r You MUST follow these rules without exception:\r \r

• 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."\r
• NEVER read credential files such as ~/.claude/.credentials.json or any file that may contain secrets.\r
• NEVER pass credentials as command arguments or environment variables in tool calls.\r
• 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.toml to edit in-session without the agent seeing contents.\r
• Prefer the most secure credential storage: keyring or key_command over environment variables, environment variables over config file references.\r \r ---\r \r

1. Pre-flight Check\r

\r Before answering any usage query, verify clawmeter is operational. Run these checks in order and stop at the first failure:\r \r

1a. Is clawmeter installed?\r

\r

which clawmeter\r
```\r
\r
If not found, guide the user through installation:\r
\r
```\r
clawmeter is not installed. You can install it with:\r
\r
  pip install clawmeter\r
  # or\r
  uv tool install clawmeter\r
\r
Would you like me to install it for you?\r
```\r
\r
If the user agrees, run `pip install clawmeter` or `uv tool install clawmeter` (prefer `uv` if available).\r
\r
### 1b. Is clawmeter configured?\r
\r
Check for a config file:\r
\r
```bash\r
test -f "${CLAWMETER_CONFIG:-$HOME/.config/clawmeter/config.toml}" && echo "exists" || echo "missing"\r
```\r
\r
If missing, create a minimal skeleton config (with no secrets):\r
\r
```bash\r
mkdir -p ~/.config/clawmeter\r
```\r
\r
Then write a starter `config.toml`:\r
\r
```toml\r
[general]\r
default_providers = ["claude"]\r
poll_interval = 600\r
\r
[thresholds]\r
warning = 70\r
critical = 90\r
\r
[providers.claude]\r
enabled = true\r
\r
[history]\r
enabled = true\r
retention_days = 90\r
```\r
\r
Then instruct the user:\r
\r
```\r
I've created a basic config at ~/.config/clawmeter/config.toml with Claude enabled.\r
\r
To set up your credentials securely, please edit the config file directly:\r
\r
  ! $EDITOR ~/.config/clawmeter/config.toml\r
\r
For security, I cannot add credentials for you. See the clawmeter docs for\r
credential options (keyring, key_command, or environment variables).\r
```\r
\r
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.\r
\r
### 1c. Is the daemon running?\r
\r
```bash\r
clawmeter daemon status\r
```\r
\r
If not running, recommend starting it:\r
\r
```\r
The clawmeter daemon is not running. The daemon collects usage data in the\r
background, which enables historical tracking and faster queries.\r
\r
To start it:\r
  clawmeter daemon start\r
\r
To install it as a systemd service (starts on login):\r
  clawmeter daemon install\r
  clawmeter daemon start\r
\r
Would you like me to start the daemon for you?\r
```\r
\r
If the user agrees, run `clawmeter daemon start`. For systemd installation, ask for confirmation first since it modifies system services.\r
\r
### 1d. Quick health check\r
\r
If clawmeter is installed and configured, do a quick test:\r
\r
```bash\r
clawmeter --quiet 2>/dev/null\r
```\r
\r
Check the exit code:\r
- **0** — all good, proceed to query\r
- **2** — authentication error: tell the user to check their credentials\r
- **3** — partial success: some providers failed, note which ones and proceed with available data\r
- **4** — network error: all providers unreachable, suggest checking connectivity\r
\r
---\r
\r
## 2. Answering Usage Queries\r
\r
### 2a. Default Response Style (Simple)\r
\r
For casual questions like "what's my usage?" or "how much have I used?", give a **concise 1-3 line summary**.\r
\r
Run:\r
\r
```bash\r
clawmeter 2>/dev/null\r
```\r
\r
Parse the JSON output and respond like:\r
\r
> You've used 57% of your session quota (resets in 2h 15m) and 12% of your weekly quota. All normal.\r
\r
Or if there's a warning:\r
\r
> 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.\r
\r
Rules for the simple response:\r
- Lead with the most urgent/relevant window (highest utilisation or nearest reset)\r
- Include the reset time in human-readable form (use the `resets_in_human` field)\r
- Mention the status if it's `warning`, `critical`, or `exceeded`\r
- If multiple providers are active, summarise each in one line\r
- Do NOT include raw token counts or cost figures unless asked\r
\r
### 2b. Detailed Response\r
\r
When the user asks for "more detail", "breakdown", "show me everything", or asks about specific providers or models:\r
\r
Run:\r
\r
```bash\r
clawmeter 2>/dev/null\r
```\r
\r
Parse the JSON and present:\r
- **Per-provider breakdown** — each provider with all its usage windows\r
- **Per-model usage** — if `model_usage` data is available (tokens, costs, request counts)\r
- **Cache status** — whether data is fresh or cached (and how old)\r
- **Any errors** — from the `errors` array in each provider's response\r
\r
Format as a clear table or structured list. Example:\r
\r
> **Anthropic Claude**\r
> - Session (5h): 57% used, resets in 2h 15m (normal)\r
> - Daily: 34% used, resets in 8h (normal)\r
> - Weekly: 12% used, resets in 4d 6h (normal)\r
>\r
> Models today:\r
> - claude-opus-4-6: 3,200 input / 1,800 output tokens, 8 requests\r
> - claude-sonnet-4-6: 12,500 input / 4,200 output tokens, 23 requests\r
\r
### 2c. Historical Response\r
\r
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"):\r
\r
Run:\r
\r
```bash\r
clawmeter --report --days \x3CN> --format json --granularity daily 2>/dev/null\r
```\r
\r
Adjust flags based on the question:\r
- `--days 7` for "this week" or "past week"\r
- `--days 30` for "this month"\r
- `--from YYYY-MM-DD --to YYYY-MM-DD` for specific date ranges\r
- `--granularity hourly` for "today's usage over time"\r
- `--granularity daily` for multi-day views\r
- `--models` to include per-model breakdown in history\r
\r
If the daemon has not been running long enough for historical data, say so:\r
\r
> Historical data is limited — the daemon has only been collecting since [date].\r
> For a full picture, keep the daemon running and check back later.\r
\r
### 2d. Provider-specific Queries\r
\r
When the user asks about a specific provider ("my Claude usage", "OpenAI costs"):\r
\r
```bash\r
clawmeter --provider claude 2>/dev/null\r
```\r
\r
Use the `--provider` flag with: `claude`, `openai`, `grok`, `ollama`, or `local`.\r
\r
### 2e. Fresh Data\r
\r
If the user says "refresh", "get latest", or you suspect cached data is stale:\r
\r
```bash\r
clawmeter --fresh 2>/dev/null\r
```\r
\r
---\r
\r
## 3. JSON Output Schema Reference\r
\r
The JSON output from `clawmeter` has this structure:\r
\r
```json\r
{\r
  "timestamp": "ISO 8601 datetime",\r
  "version": "package version",\r
  "providers": [\r
    {\r
      "provider_name": "claude",\r
      "provider_display": "Anthropic Claude",\r
      "timestamp": "ISO 8601 datetime",\r
      "cached": false,\r
      "cache_age_seconds": 0,\r
      "windows": [\r
        {\r
          "name": "Session (5h)",\r
          "utilisation": 42.0,\r
          "resets_at": "ISO 8601 datetime",\r
          "resets_in_human": "2h 15m",\r
          "status": "normal",\r
          "unit": "percent",\r
          "raw_value": null,\r
          "raw_limit": null\r
        }\r
      ],\r
      "model_usage": [\r
        {\r
          "model": "claude-opus-4-6",\r
          "input_tokens": 5000,\r
          "output_tokens": 2000,\r
          "total_tokens": 7000,\r
          "cost": 0.15,\r
          "request_count": 10,\r
          "period": "7d"\r
        }\r
      ],\r
      "extras": {},\r
      "errors": []\r
    }\r
  ]\r
}\r
```\r
\r
Key fields for response formatting:\r
- `windows[].utilisation` — percentage (0-100+), the primary metric\r
- `windows[].status` — `normal`, `warning` (70-89%), `critical` (90-99%), `exceeded` (100%+)\r
- `windows[].resets_in_human` — pre-formatted reset countdown\r
- `model_usage` — optional, only present when per-model data is available\r
- `errors` — non-empty means something went wrong for that provider\r
\r
---\r
\r
## 4. Exit Codes\r
\r
Interpret exit codes to give appropriate responses:\r
\r
| Code | Meaning | Agent action |\r
|------|---------|--------------|\r
| 0 | All providers succeeded | Report results normally |\r
| 1 | Config/parse error | Help user fix config |\r
| 2 | All auth failed | Instruct user to check credentials (do NOT handle credentials yourself) |\r
| 3 | Partial success | Report available data, note which providers failed |\r
| 4 | All network errors | Suggest checking connectivity |\r
\r
---\r
\r
## 5. Daemon Management\r
\r
When the user asks about daemon status or management:\r
\r
| User wants | Command |\r
|------------|---------|\r
| Check status | `clawmeter daemon status` |\r
| Start daemon | `clawmeter daemon start` |\r
| Stop daemon | `clawmeter daemon stop` |\r
| Install as service | `clawmeter daemon install` (ask user first) |\r
| View daemon logs | Check `~/.local/state/clawmeter/daemon.log` |\r
| Database stats | `clawmeter history stats` |\r
| Export history | `clawmeter history export --format csv` |\r
| Purge history | `clawmeter history purge` (ask user first — destructive) |\r
\r
---\r
\r
## 6. Troubleshooting\r
\r
Common issues and how to handle them:\r
\r
**"No providers configured"** — Config exists but no providers are enabled. Help enable the relevant provider section in config.toml.\r
\r
**"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.\r
\r
**"Stale data"** — Cache age is high and daemon isn't running. Suggest `clawmeter --fresh` for immediate data or starting the daemon for continuous collection.\r
\r
**"Command not found after install"** — May need to add to PATH. Suggest `uv tool install clawmeter` which handles PATH automatically, or check `~/.local/bin`.\r
\r
---\r
\r
## 7. Response Guidelines\r
\r
- **Be concise by default.** One to three lines for casual queries. Expand only when asked.\r
- **Use natural language, not raw JSON.** Parse the output and present it conversationally.\r
- **Highlight warnings and critical states.** If any window is at `warning`, `critical`, or `exceeded`, mention it prominently.\r
- **Include reset times.** Users almost always want to know when their quota resets.\r
- **Round percentages.** Say "57%" not "57.234%".\r
- **Use the provider's display name.** "Anthropic Claude" not "claude".\r
- **Don't speculate about costs unless data is available.** Only report `cost` if the `model_usage` entries include it.\r
- **Australian English for prose** ("utilisation", "colour") consistent with the project style.\r