telegram-usage

# Telegram Usage Stats

Display comprehensive session usage statistics by running the handler script.

## What it does

Shows a quick status message with:
- **Quota Remaining**: Percentage of API quota left with visual indicator
- **Reset Timer**: Time remaining until quota resets

## How to use this skill

When the user asks for usage statistics, quota info, or session data:

```bash
node /home/drew-server/clawd/skills/telegram-usage/handler.js
```

This will output formatted HTML suitable for Telegram's parseMode.

## Output Format

The response is formatted as a clean Telegram message with:
- Section headers (bold)
- Clear percentages and time remaining
- Visual indicators (emoji)
- All in one message for quick reference

## Example Output

```
📊 API Usage

🔋 Quota: 🟢 47%
⏱️ Resets in: 53m
```

## Notes

- Pulls real-time data from `clawdbot models status`
- Updates on each invocation with current API quota values
- Uses plain text formatting for Telegram compatibility

# Telegram Usage Command Skill

A custom Telegram command that displays comprehensive session usage statistics in a clean, formatted message.

## Features

✅ **Quota Remaining** - Shows percentage of API quota left (provider-specific)  
✅ **Session Time** - Displays time remaining before session resets  
✅ **Token Usage** - Shows input and output tokens used in session  
✅ **Context Window** - Displays current context window usage  
✅ **Visual Indicators** - Color-coded emoji for quick status check  
✅ **Single Message** - All info in one clean Telegram message  

## Installation

### Option 1: Automatic (via ClawdHub)

```bash
clawdhub install telegram-usage
```

### Option 2: Manual (Already in workspace)

The skill is located at `/skills/telegram-usage` in your Clawdbot workspace.

## Setup

### 1. Enable the Skill

Ensure the skill is enabled in `~/.clawdbot/clawdbot.json`:

```json
{
  "skills": {
    "entries": {
      "telegram-usage": {
        "enabled": true
      }
    }
  }
}
```

### 2. Add Custom Command to Telegram (Optional)

Register the command in Telegram's bot menu via config:

```json
{
  "channels": {
    "telegram": {
      "customCommands": [
        {
          "command": "usage",
          "description": "Show session usage stats"
        }
      ]
    }
  }
}
```

### 3. Restart Gateway

```bash
clawdbot gateway restart
```

Or if running manually:

```bash
clawdbot gateway
```

## Usage

### In Telegram

Send any of these:

```
/telegram_usage
/usage          (if custom command registered)
/skill telegram-usage
```

### Output Example

```
📊 Session Usage Report

🔋 Quota Remaining
🟢 82% of API quota available
Provider: anthropic

⏱️ Session Time
3 hours 40 minutes remaining
(resets daily at 4:00 AM)

🎯 Tokens Used
4,370 total tokens
├─ Input: 2,847
└─ Output: 1,523

📦 Context Window
🟢 45% used
1,856 / 4,096 tokens

Model: Claude 3.5 Haiku
```

## Configuration

No additional configuration required. The skill reads from Clawdbo...